Integrate Orders Feature in your dApp

ℹ️

Estimated feature integration time: ~6 hours*

Prerequisites

The following steps are required. If you haven't done so already, please follow the steps in the prerequisites guide:

Implement logic for extension detection and connection
Implement logic for vaults & accounts selection
Subscribe to cede.store events

Retrieve available market types for your exchange from our Provider API. It can be "spot", "margin", "futures", "options", if it's available for your exchange.

const supportedExchanges = await provider.request({ method: "supportedExchanges" });
console.log({ supportedExchanges });
// [
//     {
//         "name": "binance",
//         "id": "binance",
//         "logo": "...",
//         "status": "ok",
//         "supportedWalletTypes": [
//             "spot",
//             "bot",
//             "card",
//             "earn",
//             "futures",
//             "margin",
//             "options"
//         ],
//         "supportedFeatures": [
//             "send",
//             "trade",
//             "receive",
//             "nfts",
//             "withdrawalHistory",
//             "depositHistory",
//             "tradeHistory"
//         ]
//     },
//     ...
// ]

Filter out exchanges that don't support "trade" feature.

Note, that there are maximum 4 wallet types that you can use for trading:

"spot",
"margin" - available soon,
"futures" - available soon,
"options" - available soon.

⚠️

Only spot markets are supported for now.

Retrieve available market pairs from our Provider API.

const marketPairs = await provider.request({
  method: "getMarketPairs",
  params: {
    accountId: "binance-125805-530845-212023-888168",
  },
});
console.log({ marketPairs });
// [
//     {
//         "symbol": "ETH/BTC",
//         "base": "ETH",
//         "quote": "BTC",
//         "type": "spot",
//         "taker": 0.001,
//         "maker": 0.001,
//         "precision": {
//             "amount": 4,
//             "price": 5,
//             "base": 8,
//             "quote": 8
//         },
//         "active": true,
//         "limits": {
//             "amount": {
//                 "min": 0.0001,
//                 "max": 100000
//             },
//             "cost": {
//                 "min": 0.0001
//             },
//             "price": {
//                 "min": 0.00001,
//                 "max": 922327
//             },
//             "market": {
//                 "min": 0,
//                 "max": 0
//             }
//         }
//     },
//     ...
// ]

Notice that you can filter out market pairs by "type" field. For example, if you want to display only "spot" market pairs, you can filter out all other types.

Also note that you can trade only "active" market pairs.

Retrieve user balances from our Provider API. It will allow you to display "tokens from" and "tokens to" balances.

const balances = await provider.request({
  method: "balances",
  params: {
    vaultId: "740351-125805-530845-212023-888168",
    accountIds: ["binance-125805-530845-212023-888168"],
    walletTypes: ["spot"], // optional. You can use "spot", "margin", "futures", "options", if it's available for your exchange
    version: 2,
  },
});
console.log({ balances });
// {
//   "binance-125805-530845-212023-888168": {
//     "USDT": {
//       "freeBalance": 5780,
//       "refFreeBalance": 1200,
//       "usedBalance": 0,
//       "refUsedBalance": 0,
//       "totalBalance": 5780,
//       "refTotalBalance": 1200,
//       "spot": {
//         "freeBalance": 270,
//         "refFreeBalance": 40,
//         "usedBalance": 0,
//         "refUsedBalance": 0,
//         "totalBalance": 270,
//         "refTotalBalance": 40,
//         "originalWalletName": "spot"
//       },
//       "margin": {
//         "freeBalance": 270,
//         "refFreeBalance": 40,
//         "usedBalance": 0,
//         "refUsedBalance": 0,
//         "totalBalance": 270,
//         "refTotalBalance": 40,
//         "originalWalletName": "margin"
//       }
//     }
//   }
// }

Note, that you should use "freeBalance" field to display user balances. Total balance includes locked funds (in limit orders, for example).

When the user selects a market pair ("token from" and "token to"), you should retrieve the minimum order amount of "token from" for this market pair from our Provider API.

const minimumAmount = await provider.request({
  method: "getMinAmounts",
  params: {
    accountId: "binance-125805-530845-212023-888168",
    pairSymbol: "ETH/USDT",
    orderSide: "buy",
    price: "1837.21",
  },
});
console.log({ minimumAmount });
// 0.001 ETH

Please note that sometimes we use the terms "token from" and "token to" for fields, while at other times we refer to the "base" and "quote" fields.

For example, in the "ETH/USDT" market pair, "ETH" is referred to as the "base token," and "USDT" is the "quote token." This doesn't change: the base token is always the first part of the pair symbol (before the slash), and the quote is the second part.

However, the terms "token from" and "token to" depend on the side of the order. If the user is buying "USDT," then "token from" is "ETH," and "token to" is "USDT." We don't have a "USDT/ETH" pair; only "ETH/USDT" exists. In this scenario, the order side is a sell because the order side always refers to the base token.

In the future, we will standardize these conventions by choosing one of the following options:

Either the "token from," "token to," "amount from," and "amount to" fields Or the "base," "quote," "amount base," and "amount quote" fields.

Also, you'll need to load prices. Retrieve market rate you need.

const marketRate = await provider.request({
  method: "getMarketRate",
  params: {
    accountId: "binance-125805-530845-212023-888168",
    pairSymbol: "ETH/USDT", // pairSymbol the user selected
  },
});
console.log("marketRate", marketRate);
// {
//     "bid": "1836.31",
//     "ask": "1836.32",
// }

We recommend to use "high" and "low" fields to the price. The reason is that low/last/average prices are not available on some exchanges. So you can take high/low prices and calculate average price by yourself.

Finally, post an order to our Provider API.

const order = await provider.request({
  method: "createOrder",
  params: {
    accountId: "binance-125805-530845-212023-888168",
    pairSymbol: "ETH/USDT",
    orderSide: "buy",
    orderType: "limit",
    price: "1890",
    amount: "0.1", // limit order amount in base currency
  },
});
console.log({ order });
// {
//   "id": "13960869081",
//   "amount": 0.1,
//   "timestamp": 1691059056395,
//   "price": 1836.31,
//   "status": "closed",
//   "symbol": "ETH/USDT",
//   "type": "limit",
//   "side": "buy",
//   "filled": 0.1,
//   "fee": {}
// }

You can also retrieve the order status, edit or cancel the order.

Withdraw KYC - (WIP 🏗️)