Cede SDK API

Cede SDK exposes its API via a JavaScript object. To use it, import it and create a new instance:

import CedeSDK from "@cedelabs-private/sdk";
 
const SDK_MODE = "REAL"; // or "MOCK", the default value is "MOCK"
const cedeSDK = new CedeSDK(SDK_MODE, { clientId: YOUR_CLIENT_ID });

"REAL" instance will use real exchange API, while "MOCK" instance will use mock API. The "MOCK" instance does not require a valid client ID and will let you test your integration without real funds and API keys.

Supported exchanges

In order to fetch all supported exchanges and their specificities, use the following method:

method: getSupportedExchanges
response structure: Promise<ExchangeInfo[]>, see ExchangeInfo for details.

const supportedExchanges = await cedeSDK.api.getSupportedExchanges();

The ExchangeInfo type contains information regarding:

• the exchange ID, name, and logo,
• the exchange's status,
• supported wallet types for fetching balances,
• supported wallet types for internal transfers,
• authentification mode and requirements,
• the exchange's features and constraints (e.g. email confirmation, address whitelisting),

Authentication

To authenticate your requests, you need to register an exchange instance and provide credentials used in further requests. You can register the user either with an API keys pair (apiKey and secretKey) or OAuth keys pair (accessToken and refreshToken). This method also checks if the provided credentials are valid.

Check the section below to learn how to get access and refresh tokens for OAuth authentication.

method: registerExchangeInstance
params:

• exchangeId - string
  The exchange identifier.
• apiKey - string, optional
  A public API key.
• secretKey - string, optional
  A private API key.
• password - string, optional
  For exchanges requiring an additional password with API Keys. You get this information from getSupportedExchanges method.
• uid - string, optional
  For exchanges requiring an additional UID with API Keys. You get this information from getSupportedExchanges method.
• timeout - number, optional
  Timeout of the checks and registration (in milliseconds), the default value is 10_000.
• sharedThrottler - boolean, optional
  If true, the Cede SDK will use a shared throttler for all requests sent to the exchange servers.
  Default: false.
• accessToken - string, optional
  For OAuth authentication, an access token.
• refreshToken - string, optional
  For OAuth authentication, a refresh token.
• expiresAt - number, optional
  For OAuth authentication, a token expiration time.
• deviceId - string, optional
  For exchanges requiring a Device ID with OAuth.
• noValidation - boolean, optional
  If true, the Cede SDK will not validate the provided credentials.
  Default: false.

response structure: Promise<RegisterExchangeInstanceReturn>, see RegisterExchangeInstanceReturn for details.

const exchangeInstanceId = await cedeSDK.api.registerExchangeInstance({
  exchangeId: "binance",
  accessToken: "access token here",
  refreshToken: "refresh token here",
});

Revoke access

To revoke access, you can use removeExchangeInstance method. It will remove keys from memory. If authentication is through OAuth, it will revoke the access token.

method: removeExchangeInstance
params:

• exchangeInstanceId - string
  The exchange instance identifier.

response structure: Promise<void>

await cedeSDK.api.removeExchangeInstance({ exchangeInstanceId });

OAuth tokens

Get the list of exchanges supporting OAuth authentication with the getSupportedExchanges method and the auhenticationMethod field.

In case if you use OAuth authentication, first you'll need to provide your clientId and clientSecret to the SDK. We provide guides on how to get them for each exchange.

method: setupOAuthClientCredentials
params:

• exchangeId - string
  The ID of the exchange you want to authenticate with.
• clientId - string
  The client ID you got from the exchange.
• clientSecret - string
  The client secret you got from the exchange. \

response structure: Promise<void>

cedeSdk.api.setupOAuthClientCredentials({
  exchangeId: "coinbase",
  clientId,
  clientSecret,
});

In order to get OAuth tokens, you need first to get the authorization code. To do that, you need to redirect the user to an URL provided by the Cede SDK:

method: getOAuthUrl
params:

• exchangeId - string
  The exchange identifier.
• redirectUri - string
  The URL to which the user will be redirected after the authorization.
• permissions - ApiPermissions[]
  The permissions required for the OAuth token.
• deviceId - string, optional
  For OKX, the device ID.

response structure: Promise<{ url: string; codeVerifier?: string }>, the codeVerifier is used by OKX, it will be needed for the getOAuthTokens method use.

const { url } = await cedeSDK.api.getOAuthUrl({
  exchangeId: "coinbase",
  redirectUri: "https://your-redirect-uri.com",
  permissions: ["read", "trade", "withdraw"],
});

After the user is redirected back to your app, copy the entire URL and pass it to the Cede SDK:

method: getOAuthTokens
params:

• exchangeId - string
  The exchange identifier.
• redirectUriWithCode - string
  The URL with the authorization code.
• codeVerifier - string, optional
  The code verifier used for the OAuth token.
• deviceId - string, optional
  The device ID used for the OAuth token.

response structure: Promise<{ accessToken: string; refreshToken: string; expiresAt: number; }

const { accessToken, refreshToken } = await cedeSDK.api.getOAuthTokens({
  exchangeId: "coinbase",
  redirectUriWithCode: "https://your-redirect-uri.com?code=123",
});

Now, you can register the exchange instance as specified above.

Errors

How to handle the SDK errors

Each Cede SDK method can throw errors, where each error is a class representing the scope of the issue. This allows you to handle errors in your code with specificity.

try {
  // ... your code
  await cedeSDK.api.createWithdrawal(...params);
} catch (error) {
  if (error instanceof OverWithdrawMaximumError) {
    // ... your logic to handle the case where the withdrawal amount is too high
  } else if (error instanceof WithdrawalError) {
    // ... handle the case where it's a withdrawal error
  } else if (error instanceof CedeSdkError) {
    // ... handle the case where it's a cede SDK generic error
  } else {
    // ... handle the case where it's a generic error
  }
}

There is an observable error hierarchy here. OverWithdrawMaximumError is a subclass of WithdrawalError, which in turn is a subclass of CedeSdkError. This allows you to catch the error at either a specific level or a more general level. In the given example, OverWithdrawMaximumError represents the specific error, while WithdrawalError represents the more general error for the withdrawal scope.

List of errors

You can see below the list of all the errors which can be thrown by the SDK. For your information, the first error of each section is the generic one, and the others are the inherited ones.

Identify an user

The Cede SDK collects client side errors. To identify an user and focus on the errors related to him, you can use the setUserId method. You have the responsability to provide a unique identifier for each user.

method: setUserId
params:

• userId - string
  The user identifier.

cedeSDK.setUserId("user-123");