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.
"MOCK"
mode, you don't have to provide keys.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 fromgetSupportedExchanges
method.uid
-string
, optional
For exchanges requiring an additional UID with API Keys. You get this information fromgetSupportedExchanges
method.timeout
-number
, optional
Timeout of the checks and registration (in milliseconds), the default value is10_000
.sharedThrottler
-boolean
, optional
Iftrue
, 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
Iftrue
, 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",
});
In case of OAuth authentication, the SDK will automatically refresh the access token when it expires. However, if the refresh token expires, you will need to redirect the user to the OAuth flow again.
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.
Cede SDK Errors
Code | Class | Description |
---|---|---|
10000 | DefaultError | Default SDK error |
10001 | InvalidParamsError | Invalid parameters provided to a SDK method |
10002 | InvalidCacheError | Thrown when the cache can't be persisted |
10003 | InvalidAddressError | The provided address is invalid |
10004 | FetchFromCacheError | An error occured while fetching from the cache |
Internal Errors
Code | Class | Description |
---|---|---|
11000 | InternalError | Default error for internal SDK errors |
11001 | InvalidExchangeIdError | An invalid exchange id is provided |
11002 | InvalidExchangeInstanceIdError | An invalid exchange instance id is provided |
Authentication Errors
Code | Class | Description |
---|---|---|
12000 | AuthenticationError | Default error for authentication errors |
12001 | InvalidCredentialsError | Invalid credentials provided |
12002 | AuthenticationFlowNotSupportedError | Authentication flow not supported |
12003 | OAuthAccessRevokedError | Can't perform the operation since the OAuth access are revoked |
Withdrawal Errors
Code | Class | Description |
---|---|---|
13000 | WithdrawalError | Default error for withdrawal errors |
13001 | ReadonlyExchangeNotProvidedError | Readonly account not provided. It needs to be provided to perform some operations |
13002 | TokenSymbolNotFoundError | The withdrawal can't be executed since the token symbol isn't found |
13003 | WithdrawalNotFoundError | The withdrawal isn't found |
13004 | UnderWithdrawMinimumError | The withdrawal amount is under the minimum amount allowed by the exchange |
13005 | OverWithdrawMaximumError | The withdrawal amount is over the maximum amount allowed by the exchange |
13006 | WhitelistCheckFailedError | The provided address isn't whitelisted for the withdrawal |
Trade Errors
Code | Class | Description |
---|---|---|
14000 | TradeError | Default error for trade errors |
14001 | MarketError | Default error for market errors |
14002 | MarketNotFoundError | The given pair symbol was not found |
14003 | OrderNotFoundError | The order isn't found |
14004 | MarketNotLoadedError | The market isn't loaded |
14005 | MarketTypeNotSupportedError | The market type isn't supported |
14006 | InvalidOHLCVFormatError | The OHLCV format is invalid |
14007 | CannotProvideOHLCVError | Cannot provide OHLCV data |
Portfolio Errors
Code | Class | Description |
---|---|---|
15000 | PortfolioError | Default error for portfolio errors |
15001 | InsufficientBalanceError | The user doesn't have enough balance to perform the operation |
Deposit Errors
Code | Class | Description |
---|---|---|
16000 | DepositError | Default error for deposit errors |
16001 | GetDepositAddressError | Can't get the deposit address |
16002 | CreateDepositAddressError | Can't create the deposit address |
Network Errors
Code | Class | Description |
---|---|---|
17000 | NetworkError | Default error for network errors |
17001 | NetworkNotFoundError | The network isn't found |
API Errors
Code | Class | Description |
---|---|---|
18000 | APIError | Default error for API errors |
18001 | InvalidApiRequestError | The API request is invalid |
Exchange Errors
Code | Class | Description |
---|---|---|
19000 | ExchangeError | Default error for exchange errors |
19001 | ExchangeServerError | The exchange server is down |
19002 | ExchangeUnderMaintenanceError | The exchange API is under maintenance |
19003 | ExchangeRequestExpiredError | The exchange request is expired |
19004 | ExchangeInvalidPermissionsError | The permissions are invalid to perform the operation |
19005 | ExchangeTransferNotAllowedError | Transfer is not allowed |
19006 | ExchangeTransferError | Transfer error |
19007 | ExchangeDDosProtectionError | DDoS protection error |
19008 | ExchangeRateLimitExceededError | Rate limit exceeded |
19010 | ExchangeUnknownAssetError | Unknown asset |
19011 | ExchangeOperationFailedError | Operation failed |
19012 | ExchangeAccountSuspendedError | Account suspended |
19013 | ExchangeNotAllowedMethodError | Method isn't allowed to be called for an exchange |
19014 | ExchangeNotAvailableError | Exchange is not available |
19015 | ExchangeInvalidNonceError | The nonce is invalid |
19016 | ExchangeUnavailableInCountryError | Exchange is unavailable in the country |
19017 | ExchangeWalletTypeNotSupportedError | Wallet type not supported or not available for transfers |
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.api
object.cedeSDK.setUserId("user-123");