Cede SDK API

The Cede SDK API is available via two integration options: the Typescript SDK or the on-premise HTTP SDK. Please select your preferred option below. You can seamlessly switch between the two at any time using the toggle button in the navigation bar.

Getting started

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 });

Mode: "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.

Configuration:

• clientId - string
  The client identifier. It is required for the "REAL" mode.
• proxyUrl - string, optional
  This field specifies the proxy to be used for making private requests to exchanges, which is particularly useful when API keys are restricted to whitelisted IP addresses. If left unset, the SDK will bypass the proxy and send private requests directly.
• cacheStorage - SdkCacheStorage, optional: By default, the Cede SDK utilizes InMemoryCacheStorage, which, as the name implies, stores cache data in memory. This means that when the server instance is shut down, all cached data is lost. To persist cache data beyond server restarts, you can implement a custom cache storage solution tailored to your needs or use RedisCacheStorage.
• credentialsStorage - CredentialsStorage, optional: If you need to get/set the credentials from/to a specific storage system, you can provide a connector to the SDK.
  💡

  The retention of the exchange instance after service restarts depends on the implementation of CredentialsStorage. If you use an external service to store credentials, the SDK will automatically retrieve these credentials using the exchange instance ID and create an exchange instance during the first call.

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 must provide an auth parameter with every method you wish to invoke. You can use either a pair of API keys (apiKey and secretKey) or a pair of OAuth tokens (accessToken and refreshToken).

You'll also need to provide the exchangeInstanceId to methods that use private data, such as user balances. The SDK will use this identifier for caching.

For example, if you're calling the getBalances method, you'll need to provide at least the exchangeInstanceId and auth parameters:

const auth = {
  apiKey: "your-api-key",
  secretKey: "your-secret-key",
};
const balances = await cedeSDK.api.getBalances({ exchangeInstanceId, auth });

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

auth params for API key based authentication:

• apiKey - string, optional
  A public API key. Required for exchanges using API keys for the SDK in "REAL" mode.
• secretKey - string, optional
  A private API key. Required for exchanges using API keys for the SDK in "REAL" mode.
• 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.

auth params for OAuth based authentication:

• 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.

Revoke access

To revoke access for an OAuth2 connection, you can use the revokeOAuth method. This will invalidate the existing access and refresh tokens.

method: revokeOAuth
params:

• exchangeInstanceId - string
  The exchange instance identifier.

response structure: Promise<void>

await cedeSDK.api.revokeOAuth({ 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");