Introduction
Our API is similar to major exchanges such as coinbase and binance, but as our exchange is decentralized there are a few key differences:
- You trade directly from your Ethereum wallet. Therefore authentication does not rely on a typical API key scheme, but rather on the cryptographic signature scheme used to interact with the Ethereum blockchain. (Authentication)
- Submitting an order is a multi-step process where you must:
- Ask the API to construct an unsigned order (Build Unsigned Order)
- Locally sign the order (Sign Order)
- Submit the signed order to the exchange (Place Order)
- Moving funds is completely under your control, which means some operations require you to call the smart contract directly. These operations include Deposit, Withdraw, Get Balance and more. The Contract Interaction section has more information about this.
If you have any questions or feedback, please come chat with us on our Discord.
High Level Overview
There are three main categories of users on DDEX:
- Traders (either margin trading or spot trading)
- Lenders (earn interest on crypto assets)
- Borrowers (borrow crypto assets)
All actions can be performed through our website UI, or through API as documented here.
Note that DDEX uses a Smart Contract Account system, where your public wallet address is linked to several different accounts within the DDEX Smart Contracts. Here is a breakdown of the account types:
- Spot Trading Account (for all markets)
- Margin Trading Accounts (specific to each market, i.e. ETH-USDT)
- Lending Pools (specific to each asset, i.e. lending USDT)
- Your external wallet (the account balances outside of the DDEX smart contracts)
Endpoints
Rest API Endpoint
https://api.ddex.io/v4
Websocket Endpoint
wss://ws.ddex.io/v4
Rate Limit
API Name | Path | Rate Limit |
---|---|---|
market orderbook | /markets/MARKET-NAME/orderbook | 30 Requests per minute per IP |
market trades | /markets/MARKET-NAME/trades | 30 Requests per minute per IP |
Contract Interaction
Overview
DDEX stores your orders until matched with a corresponding order. When an order is matched, it is immediately sent to blockchain for settlement. By using specific order signatures, DDEX has no control of your funds throughout this process. Some operations such as Deposit and Withdraw have to be done by the private key holder. In the website, we provide UI tools and you perform these actions by clicking buttons. For who want to do these actions in a programmed way, we have provided a git repository for demonstration. https://github.com/HydroProtocol/contract-interactions
Public Rest API
Introduction
These API calls do not require any user authentication. Generally these calls provide publicly available information about the state of markets and lending pools.
List Markets
Response
{
"status": 0,
"desc": "success",
"data": {
"markets": [
{
"id": "ETH-USDT",
"maxSlippage": "0.01",
"marginMarketId": 0,
"isMarginMarket": true,
"baseAsset": "ETH",
"baseAssetName": "Ethereum",
"baseAssetDecimals": 18,
"baseAssetDisplayDecimals": 2,
"baseAssetAddress": "0x000000000000000000000000000000000000000e",
"quoteAsset": "USDT",
"quoteAssetName": "Tether USD",
"quoteAssetDecimals": 6,
"quoteAssetDisplayDecimals": 2,
"quoteAssetAddress": "0xdac17f958d2ee523a2206206994597c13d831ec7",
"minOrderSize": "1",
"pricePrecision": 5,
"priceDecimals": 2,
"amountDecimals": 2,
"asMakerFeeRate": "0",
"asTakerFeeRate": "0",
"gasFeeAmount": "0.0348333333333333",
"supportedOrderTypes": ["limit", "market", "stopLimit"],
"lastPriceIncrease": "-0.39",
"lastPrice": "170.32",
"price24h": "0.0034761091144759",
"amount24h": "189.06",
"quoteAssetVolume24h": "32106.9828",
"baseAssetUSDPrice": "171.015",
"quoteAssetUSDPrice": "1",
"maxLeverageRate": "5",
"withdrawRate": "2",
"liquidationRate": "1.1"
}
]
}
}
Returns all active markets.
HTTP Request
GET https://api.ddex.io/v4/markets
Details
The value returned for minOrderSize represents the lower bound for the amount of quoteAsset you can specify in a single order.
Both baseAsset and quoteAsset give you the contract address of the asset, as well as the number of decimal places used by the asset.
Both price and amount have a minimum unit, as defined in priceDecimals and amountDecimals. Any value specified must not have an increment smaller than the minimum defined unit. For example if priceDecimals is 2, a price of "0.01" is valid, but a price of "1.001" is not.
Each market defines the fee rate for makers and takers with asMakerFeeRate and asTakerFeeRate
The estimated amount of gas in quoteAsset needed to fill an order is defined in gasFeeAmount. Note that this value is just an estimate and may change as Ethereum prices fluctuate.
The order types supported by a market are found in supportedOrderTypes. Possible values are limit
, market
, and stopLimit
.
stopLimit
is a new order type in supportedOrderTypes field.
If isMarginMarket is true, this means that the current market supports margin tradinng. maxLeverageRate is the maximum leverage available for this market. marginMarketId is the corresponding market id within the hydro contract.
Example Request
https://api.ddex.io/v4/markets
Get a Market
Response
{
"status": 0,
"desc": "success",
"data": {
"market": {
"id": "ETH-USDT",
"maxSlippage": "0.01",
"marginMarketId": 0,
"isMarginMarket": true,
"baseAsset": "ETH",
"baseAssetName": "Ethereum",
"baseAssetDecimals": 18,
"baseAssetDisplayDecimals": 2,
"baseAssetAddress": "0x000000000000000000000000000000000000000e",
"quoteAsset": "USDT",
"quoteAssetName": "Tether USD",
"quoteAssetDecimals": 6,
"quoteAssetDisplayDecimals": 2,
"quoteAssetAddress": "0xdac17f958d2ee523a2206206994597c13d831ec7",
"minOrderSize": "1",
"pricePrecision": 5,
"priceDecimals": 2,
"amountDecimals": 2,
"asMakerFeeRate": "0",
"asTakerFeeRate": "0",
"gasFeeAmount": "0.0348333333333333",
"supportedOrderTypes": ["limit", "market", "stopLimit"],
"lastPriceIncrease": "-0.39",
"lastPrice": "170.32",
"price24h": "0.0034761091144759",
"amount24h": "189.06",
"quoteAssetVolume24h": "32106.9828",
"baseAssetUSDPrice": "171.015",
"quoteAssetUSDPrice": "1",
"maxLeverageRate": "5",
"withdrawRate": "2",
"liquidationRate": "1.1"
}
}
}
Returns a single market identified by marketId.
HTTP Request
GET https://api.ddex.io/v4/markets/:marketId
URL Parameters
Parameter | Description | Required | Type | Example |
---|---|---|---|---|
marketId | Query for information on a specific market. Specified in the form of a trading pair of assets. | required | string | ETH-USDT |
Details
Please see List Markets for a description of the returned metadata.
Example Request
https://api.ddex.io/v4/markets/ETH-USDT
List Tickers
Response
{
"status": 0,
"desc": "success",
"data": {
"tickers": [
{
"marketId": "ETH-USDT",
"price": "170.32",
"volume": "189.06",
"bid": "170.32",
"ask": "170.92",
"low": "170.92",
"high": "170.71",
"updateAt": 1567391667580
}
]
}
}
Returns ticker data for all active markets.
HTTP Request
GET https://api.ddex.io/v4/markets/tickers
Details
Ticker data is general information about the state of each market on DDEX. Each set of ticker data contains a marketId, as well as the price of the last trade made.
It also gives you some more detailed information about the status of the market at the time of the last trade. ask is the best sell price at the time. bid is the best buy price at the time. Data about the last 24 hours of trading is presented as low, high, and volume.
Example Request
https://api.ddex.io/v4/markets/tickers
Get a Ticker
Response
{
"status": 0,
"desc": "success",
"data": {
"ticker": {
"marketId": "ETH-USDT",
"price": "170.32",
"volume": "189.06",
"bid": "170.32",
"ask": "170.92",
"low": "170.92",
"high": "170.71",
"updateAt": 1567391667580
}
}
}
Return ticker data for a single market identified by marketId
HTTP Request
GET https://api.ddex.io/v4/markets/:marketId/ticker
URL Parameters
Parameter | Description | Required | Type | Example |
---|---|---|---|---|
marketId | Query ticker data on a specific market. Specified in the form of a trading pair of assets. | required | string | ETH-USDT |
Details
Please see List Tickers for a description of the returned metadata.
Example Request
https://api.ddex.io/v4/markets/ETH-USDT/ticker
Get Orderbook
Level 1 Response
{
"status": 0,
"desc": "success",
"data": {
"orderbook": {
"sequence": 1152147,
"marketId": "ETH-USDT",
"bids": [
{
"price": "212.44",
"amount": "6.73"
}
],
"asks": [
{
"price": "212.82",
"amount": "6.4"
}
]
}
}
}
Level 2 Response
{
"status": 0,
"desc": "success",
"data": {
"orderbook": {
"sequence": 1152005,
"marketId": "ETH-USDT",
"bids": [
{
"price": "212.49",
"amount": "14.1"
},
{
"price": "212.24",
"amount": "74.97"
}
],
"asks": [
{
"price": "212.8",
"amount": "11.18"
}
]
}
}
}
Level 3 Response
{
"status": 0,
"desc": "success",
"data": {
"orderbook": {
"sequence": 1151777,
"marketId": "ETH-USDT",
"bids": [
{
"price": "212.49",
"amount": "14.1",
"orderId": "0x865345939d5d0b8e86d7eedbbdac03de7ed95dc6b5fac82f15b9473893b1e5ad"
},
{
"price": "212.46",
"amount": "12.69",
"orderId": "0xe1d61f06de8cfc6f83e11d5d909a6676e7d1a549e9ad13b69253475a023b79ad"
}
],
"asks": [
{
"price": "212.8",
"amount": "11.18",
"orderId": "0xd5f21e350a5d15a1cf3d8446644b400db0c63a90c5791e8e298b288e913cc14e"
}
]
}
}
}
Return order data for a single market specified by marketId
HTTP Request
GET https://api.ddex.io/v4/markets/:marketId/orderbook
URL Parameters
Parameter | Description | Required | Type | Example |
---|---|---|---|---|
marketId | Query for orderbook data on a specific market. Specified in the form of a trading pair of assets. | required | string | ETH-USDT |
Query Parameters
Parameter | Description | Required | Type | Example |
---|---|---|---|---|
level | Controls the level of detail in the returned orderbook data. Valid options: 1 , 2 , 3 |
optional (default: 1 ) |
number | 1 |
Levels
Level | Description |
---|---|
1 | The best bid and ask prices |
2 | The top 50 bids and asks, with orders at the same price aggregated together |
3 | Returns the full orderbook with no aggregation |
Details
This returns an array of bids and asks for the orderbook in the specified market. Each bid/ask contains the price and the amount of asset available/requested at that price. If you set the level to 3, you will get the full orderbook with no aggregation, and as such we also include the orderId with each bid/ask.
Example Requests
https://api.ddex.io/v4/markets/ETH-USDT/orderbook?level=1
https://api.ddex.io/v4/markets/ETH-USDT/orderbook?level=2
https://api.ddex.io/v4/markets/ETH-USDT/orderbook?level=3
List Trades
Response
{
"status": 0,
"desc": "success",
"data": {
"count": 1300,
"trades": [
{
"id": "0eed5d00-6478-402e-99d9-b79ac42b7866",
"transactionId": "829e5cef-f926-44af-b931-589b21975a5a",
"transactionHash": "0x101982560de08fab5bcefd13de256b7f7c7a203eacccaf309fc0406768f78bc1",
"status": "successful",
"marketId": "ETH-USDT",
"maker": "0xbf1ac1aaffc2db4471efa455e553a0725d8e54fb",
"taker": "0xeddef02ee9316b9ab0294b8789308e440eb3e2ef",
"buyer": "0xbf1ac1aaffc2db4471efa455e553a0725d8e54fb",
"seller": "0xeddef02ee9316b9ab0294b8789308e440eb3e2ef",
"makerOrderId": "0x11f75ad62c0d9d2a52937027d6b6f980ad27fdc25cb6158a276ec08723d5518a",
"takerOrderId": "0xe7337def3dffe634d492e4b445a31a41a93ba4b9fd5b73207883298f6155a705",
"makerBalanceCategory": 0,
"makerMarginMarketId": 0,
"takerBalanceCategory": 0,
"takerMarginMarketId": 0,
"sequence": 0,
"amount": "9.1",
"price": "169.54",
"takerPrice": "169.37",
"feeAmount": "0.038",
"bid": "169.54",
"ask": "170.43",
"rebateAmount": "0",
"executedAt": 1567360207000,
"createdAt": 1567360186989,
"updatedAt": 1567360223149
}
]
}
}
Return paginated data for all trades in a single market identified by marketId. The trades are sorted by creation time in descending order.
HTTP Request
GET https://api.ddex.io/v4/markets/:marketId/trades
URL Parameters
Parameter | Description | Required | Type | Example |
---|---|---|---|---|
marketId | Query for trade data on a specific market. Specified in the form of a trading pair of assets. | required | string | ETH-USDT |
Query Parameters
Parameter | Description | Required | Type | Example |
---|---|---|---|---|
page | Used for pagination. | optional (default: 1 ) |
number | 1 |
perPage | Used for pagination. Value must be between 1-100 . |
optional (default: 100 ) |
number | 100 |
Details
Returns all trade data for the specified market. Results will be paginated with a default page size of 20 results.
Each set of trade data includes the price and amount of the order, as well as the status. We also include the time at which the trade was created (createdAt) and the time the trade was completed on the blockchain (executedAt).
status shows the current state of the trade. It can be successful
, pending
, or failed
.
successful
: The trade is confirmed on-chain. The transaction status is success. The Trade successfully happened.pending
: The trade has been sent to Ethereum network, but it's still waiting to be mined.failed
: The trade is confrimed on-chain. The transaction status is failed. The trade did not successfully happened.
Example Request
https://api.ddex.io/v4/markets/ETH-USDT/trades?page=1&perPage=10
List Candles
Response
{
"status": 0,
"desc": "success",
"data": {
"candles": [
{
"time": 1564542300000,
"open": "210.92",
"close": "211",
"low": "210.5",
"high": "211",
"volume": "1112.34"
},
{
"time": 1564543200000,
"open": "211",
"close": "211",
"low": "211",
"high": "211",
"volume": "987.66"
}
]
}
}
Returns "candles" for a specific market specified by marketId. These candles are useful for creating a chart of the trading history of a market.
HTTP Request
GET https://api.ddex.io/v4/markets/:marketId/candles
URL Parameters
Parameter | Description | Required | Type | Example |
---|---|---|---|---|
marketId | Query for candles on a specific market. Specified in the form of a trading pair of assets. | required | string | ETH-USDT |
Query Parameters
Parameter | Description | Required | Type | Example |
---|---|---|---|---|
from | The beginning of the time range in seconds for which you want candles. Specified as a Unix Timestamp. | required | number | 1535875975000 |
to | The end of the time range in seconds for which you want candles. Specified as a Unix Timestamp. | required | number | 1567411975000 |
granularity | The width of each candle. Valid values: 5m , 1h , 12h , 24h |
required | string | 5m |
Details
Returns a list of candles, each representing a span of time on the graph defined by the granularity passed in. The candle data includes the open and close price, the high and low price, and the amount of volume traded in the span of time represented by the candle.
Example Request
https://api.ddex.io/v4/markets/ETH-USDT/candles?from=1535875975000&to=1567411975000&granularity=5m
Calculate Fees
Response
{
"status": 0,
"desc": "success",
"data": {
"fees": {
"gasFeeAmount": "0.0221666666666667",
"asMakerTotalFeeAmount": "0.0221666666666667",
"asMakerTradeFeeAmount": "0",
"asMakerFeeRate": "0",
"asTakerTotalFeeAmount": "0.0221666666666667",
"asTakerTradeFeeAmount": "0",
"asTakerFeeRate": "0"
}
}
}
Calculates the approximate fee that will be charged for an order.
HTTP Request
GET https://api.ddex.io/v4/fees
Query Parameters
Parameter | Description | Required | Type | Example |
---|---|---|---|---|
price | The price of the order. | required | string | 0.001 |
amount | The amount of asset in the order. | required | string | 5500000 |
marketId | Query for fee data on a specific market. Specified in the form of a trading pair of assets. | required | string | ETH-USDT |
Details
The server will calculate a fee based on current network conditions and return the totalFeeAmount as well as the feeRate that was used to calculate that amount.
Example Request
https://api.ddex.io/v4/fees?marketId=ETH-USDT&amount=1&price=172
Get GasPrice
Response
{
"status": 0,
"desc": "success",
"data": {
"gas": "11"
}
}
Returns the gas price that the DDEX server is currently using for processing trades. The unit is in Gwei.
HTTP Request
GET https://api.ddex.io/v4/fees/gas
Example Request
https://api.ddex.io/v4/fees/gas
Get Lending Pool Stats
Response
{
"status": 0,
"desc": "success",
"data": {
"lendingPoolStats": [
{
"blockNumber": 9036945,
"dateTime": "2019-12-02T07:49:41Z",
"assetAddress": "0x000000000000000000000000000000000000000e",
"borrowRate": "0.0334139450519681",
"supplyRate": "0.0128884086916687",
"totalBorrowAmount": "664.8960880219525884",
"totalSupplyAmount": "1637.5924901074577244",
"utilizationRate": "0.4060204794773592",
"kind": "latest"
},
...
]
}
}
HTTP Request
GET https://api.ddex.io/v4/lending_pool_stats
Query Parameters
Parameter | Description | Required | Type | Example |
---|---|---|---|---|
address | The address of the asset. | optional | string | 0x6b175474e89094c44da98b954eedeac495271d0f |
Details
Without an address parameter, the API will return the latest statistics for all potential assets. With an address parameter specified, the API will return the latest statistics along with 7 days of history for the specified asset.
Example Request
https://api.ddex.io/v4/lending_pool_stats?address=0x6b175474e89094c44da98b954eedeac495271d0f
Private Rest API
Introduction
API calls that return data about a specific account, or that let you post data to the system. These calls will require you to authenticate your address in order to access them. Please see the Authentication) section below for more details.
Authentication
Example (browser web3)
window.ethereum.enable().then(() => {
const address = web3.eth.coinbase;
const message = "[email protected]" + Date.now();
// message => [email protected]
web3.personal.sign(web3.toHex(message), address, (err, sign) => {
const hydroAuthentication = address + "#" + message + "#" + sign;
// hydroAuthentication => 0xed6d484f5c289ec8c6b6f934ef6419230169f534#[email protected]#0x2a10e17a0375a6728947ae4a4ad0fe88e7cc8dd929774be0e33d7e1988f1985f13cf66267134ec4777878b6239e7004b9d2defb03ede94352a20acf0a20a50dc1b
});
});
Example (nodejs)
import {
hashPersonalMessage,
ecsign,
toRpcSig,
toBuffer,
privateToAddress
} from "ethereumjs-util";
const message = "[email protected]" + Date.now();
// message => [email protected]
const privateKey =
"0xe4abcbf75d38cf61c4fde0ade1148f90376616f5233b7c1fef2a78c5992a9a50";
const address = "0x" + privateToAddress(privateKey).toString("hex");
// address => 0xed6d484f5c289ec8c6b6f934ef6419230169f534
const sha = hashPersonalMessage(toBuffer(message));
// sha => <Buffer 68 ce f5 04 a5 bf 9b 82 1d f3 31 3d a9 af 66 35 4d 88 65 f2 9b a0 38 c4 2b 62 ce a5 3c d9 98 6d>
const ecdsaSignature = ecsign(sha, toBuffer(privateKey));
const signature = toRpcSig(
ecdsaSignature.v,
ecdsaSignature.r,
ecdsaSignature.s
);
// signature => 0x2a10e17a0375a6728947ae4a4ad0fe88e7cc8dd929774be0e33d7e1988f1985f13cf66267134ec4777878b6239e7004b9d2defb03ede94352a20acf0a20a50dc1b
const hydroAuthentication = address + "#" + message + "#" + signature;
// hydroAuthentication => 0xed6d484f5c289ec8c6b6f934ef6419230169f534#[email protected]#0x2a10e17a0375a6728947ae4a4ad0fe88e7cc8dd929774be0e33d7e1988f1985f13cf66267134ec4777878b6239e7004b9d2defb03ede94352a20acf0a20a50dc1b
DDEX uses an Authentication Header to control access to the API.
Header Format
Hydro-Authentication: {Address}#{Message}#{Signature}
Header Components
Component | Description |
---|---|
Address | The Ethereum address used for trading, e.g. 0xed6d484f5c289ec8c6b6f934ef6419230169f534 |
Message | A static message plus the current UTC timestamp in milliseconds, e.g. [email protected] |
Signature | The result of signing the Message component with the private key of the Address |
Details
In order to authenticate a request, you must construct a signature validating your ownership of the trading address. The authentication is time sensitive to prevent a leaked signature from giving irrevocable access to the DDEX API for a particular trading address. As part of the Message component, you will include a current timestamp in UTC. The signature will be valid for up to 5 minutes. In general we suggest creating a new signature for each request.
A full example header using the example Address and Message values above:
Hydro-Authentication: 0xed6d484f5c289ec8c6b6f934ef6419230169f534#[email protected]#0x2a10e17a0375a6728947ae4a4ad0fe88e7cc8dd929774be0e33d7e1988f1985f13cf66267134ec4777878b6239e7004b9d2defb03ede94352a20acf0a20a50dc1b
Build Unsigned Order
Request (Limit Order)
{
"amount": "0.50",
"marketId": "ETH-USDT",
"orderType": "limit",
"price": "169.65",
"side": "buy",
"walletType": "margin"
}
Request (Market Order)
{
"amount": "0.5",
"price": 0,
"side": "buy",
"orderType": "market",
"walletType": "trading",
"marketId": "ETH-USDT",
"isMakerOnly": false
}
Request (Stoplimit order)
{
"amount": "10",
"price": "0.1",
"triggerPrice": "0.01",
"side": "sell",
"orderType": "stopLimit",
"walletType": "trading",
"marketId": "ETH-USDT",
"isMakerOnly": false
}
Response
{
"status": 0,
"desc": "success",
"data": {
"order": {
"id": "0xddcf41a8aa28a87fde65dd2e3c7fe80b5dddb6087403cfdd6f69650ca42f05af",
"marketId": "ETH-USDT",
"side": "buy",
"type": "limit",
"walletType": "margin",
"price": "169.65",
"triggerPrice": "0",
"amount": "0.5",
"json": {
"trader": "0x1a671e90db05af4b128ac4faef01f5a36de468ad",
"relayer": "0x6ac4baab1d85c9cb390b2a353f242bec056026ff",
"baseAssetAmount": "500000000000000000",
"quoteAssetAmount": "84825000",
"baseAsset": "0x000000000000000000000000000000000000000e",
"quoteAsset": "0xdac17f958d2ee523a2206206994597c13d831ec7",
"gasAssetAmount": "38000",
"signature": { "config": "", "r": "", "s": "", "v": 0 },
"data": "0x02000011964f85e000000000000040bd6e6521ee2f2500010000000000000000"
},
"makerFeeRate": "0",
"takerFeeRate": "0",
"makerRebateRate": "0",
"gasFeeAmount": "0.038"
}
}
}
Returns data about an unsigned order based on the requested order parameters passed in. To place an order you will sign this data and post it back to the API to authenticate the use of your account in the trade.
HTTP Request
POST https://api.ddex.io/v4/orders/build
Body JSON Parameters
Parameter | Description | Require | Type | Example |
---|---|---|---|---|
marketId | The market you wish to post the order to. Specified in the form of a trading pair. | required | string | ETH-USDT |
side | buy or sell . |
required | string | buy |
orderType | The type of the order. Valid options: limit or market or stopLimit or fillOrKill . |
required | string | limit |
walletType | The Account Type of the order. Valid options: trading or margin . trading , will use your trading balance in the contract. margin , will use your margin balance in the contract. |
required | string | trading |
price | 1) If orderType is limit , stopLimit , fillOrKill , this is the price of the order. 2) If orderType is market , this is used as the maximum price you are willing to pay for buy and the minimum price you are willing to sell for. No price limit will be used if set to 0 . |
required | string | 0.0007 |
amount | If orderType is market and side is buy then this is the amount of quoteAsset . Otherwise, this is the amount of baseAsset . |
required | string | 0.0007 |
expires | Time in seconds after which this order will expire. Minimum valid value is 3600 (1 hour), any smaller positive value will be read as a 1 hour expiration time. An expiration time of 0 means the order will never expire. Defaults to 0. | optional (default: 0 ) |
number | 3600 |
isMakerOnly | For limit order, set this to true to indicate it only make liquidity, if any part of the order results in taking liquidity, the order will be rejected and no part of it will execute. |
optional (default: false ) |
boolean | false |
triggerPrice | Only used for stopLimit orders. This is the price that will trigger the corresponding order. If order type is not stopLimit , this will be ignored. |
optional | string | 0.0007 |
Details
Returns information about the order you wish to create, mostly mirroring the values passed in. The id field inside order is what you will sign and post to allow the exchange to fulfill the order on your behalf. Additionally we return data about the the rates that will be charged to makers and takers, and an estimated amount of gas that will be charged to fill the order.
Sign Order
Example (EthSign, web3)
const address = web3.eth.coinbase;
const orderId =
"0x36975d8312c7f09003e0d280f3e8f48d406961a74afdf023873c12b99d35e86f";
web3.personal.sign(web3.toHex(orderId), address, (err, signature) => {
console.log(signature);
});
Example (EthSign, ethereumjs-util)
import {
hashPersonalMessage,
ecsign,
toRpcSig,
toBuffer,
privateToAddress
} from "ethereumjs-util";
const orderId =
"0x36975d8312c7f09003e0d280f3e8f48d406961a74afdf023873c12b99d35e86f";
const privateKey =
"0xe4abcbf75d38cf61c4fde0ade1148f90376616f5233b7c1fef2a78c5992a9a50";
const address = privateToAddress(privateKey).toString("hex");
// address => ed6d484f5c289ec8c6b6f934ef6419230169f534
const sha = hashPersonalMessage(toBuffer(orderId));
// sha => <Buffer 6e 95 b8 4d 13 e4 22 c7 c1 48 d0 9c 32 83 4f 38 e2 14 73 79 32 cf 32 90 b2 74 7a 91 0b 07 5d b3>
const ecdsaSignature = ecsign(sha, toBuffer(privateKey));
// r => <Buffer 3f 66 8c 47 28 2f b4 49 94 25 c2 b9 85 77 d9 ff 7c ad 33 9b a6 c1 30 be 38 77 26 39 f7 b4 46 6b>
// s => <Buffer 50 74 9e cf 4d 0d b1 47 c6 b8 05 94 66 33 14 ae f5 b1 27 42 e4 6c 01 71 fa 86 45 5a 1c 30 c2 51>
// v => 28
const signature = toRpcSig(
ecdsaSignature.v,
ecdsaSignature.r,
ecdsaSignature.s
);
// signature => 0x3f668c47282fb4499425c2b98577d9ff7cad339ba6c130be38772639f7b4466b50749ecf4d0db147c6b80594663314aef5b12742e46c0171fa86455a1c30c2511c
Once you have an orderId for an unsigned order built on the server, you will have to sign it in order to post it to the orderbook.
Place Order
Request
{
"orderId": "0x81e6031c4f6dd2d4ef4d3fd688dc3a8ebf4fbdad41265a3ab503afd659c0fb01",
"signature": "0x7ec1f88bceb223a11f612de483b5cc25fa21b271674e4836914bffce36d05cfb2710b8d65b4c86e5bf14c46e279da7f70c63fc4108ca82e7a36455027d8a160e1c",
"method": 1
}
Response
{
"status": 0,
"desc": "success"
}
After signing the orderId you can post it to this endpoint with the signature you created which sends it to the orderbook. If you used the EthSign method to sign the order id hash, pass 0. If you signed the full order data with EIP712, pass 1.
HTTP Request
POST https://api.ddex.io/v4/orders
Body JSON Parameters
Parameter | Description | Required | Type | Example |
---|---|---|---|---|
orderId | The id returned from the Build Unsigned Order endpoint. | required | string | 0x36..6f |
signature | The signature created during the Sign Order step. | required | string | 0x3f..1c |
method | The signing method. 0 (EthSign) or 1 (EIP712). | optional (default: 0 ) |
number | 0 |
Response
{
"status": 0,
"desc": "success",
"data": {
"order": {
"id": "0x81e6031c4f6dd2d4ef4d3fd688dc3a8ebf4fbdad41265a3ab503afd659c0fb01",
"type": "limit",
"version": "hydro-v2",
"status": "pending",
"amount": "1",
"availableAmount": "1",
"pendingAmount": "0",
"canceledAmount": "0",
"confirmedAmount": "0",
"price": "1",
"triggerPrice": "1",
"averagePrice": "0",
"side": "buy",
"makerFeeRate": "0.00100",
"takerFeeRate": "0.01000",
"makerRebateRate": "0.001",
"gasFeeAmount": "0.08826210908345922093",
"account": "0x85cf54dd216997bcf324c72aa1c845be2f059299",
"createdAt": null,
"marketId": "ETH-USDT",
"json": {
"trader": "0x85cf54dd216997bcf324c72aa1c845be2f059299",
"relayer": "0xd4a1963e645244c7fb4fe8efab12e4bc02c5fad3",
"baseAsset": "0xa0530fa979fdbc3c6e8a91573277827826b80950",
"quoteAsset": "0x9712e6cadf82d1902088ef858502ca17261bb893",
"baseAssetAmount": "1000000000000000000",
"quoteAssetAmount": "1000000000000000000",
"gasAssetAmount": "88262109083459220",
"data": "0x010000005c135353006403e8006400000000000ee40800000000000000000000",
"signature": {
"v": 28,
"r": "0x7ec1f88bceb223a11f612de483b5cc25fa21b271674e4836914bffce36d05cfb",
"s": "0x2710b8d65b4c86e5bf14c46e279da7f70c63fc4108ca82e7a36455027d8a160e",
"config": "0x1c01"
}
}
}
}
}
Details
Returns information about the order that was posted to the orderbook. The json field in the order contains values that the exchange will need to complete the transaction. Also included in the data is the original marketId, side, price and amount requested for the order, the account used to make the order, and information on the various rates and fees that will be applied to fill the order.
The averagePrice shows the average cost per asset so far for this order. If no asset has been exchanged yet, this will always be 0. Once the order has begun being filled, this could differ from the requested order price in a few ways. If a matching order with a better price was found, the better price will be used. In the case of a market order, the price is only used as an upper/lower bound, so this will display the actual price used. Finally, the average price also takes into account any trading fees, gas fees, and rebates involved in the process.
The order also includes a four amounts values related to the status of the order. The availableAmount is the amount still unfilled for this order. The pendingAmount is the amount currently being filled but not yet confirmed on the blockchain. The confirmedAmount is the amount that has been filled and confirmed on the blockchain. The canceledAmount is amount of unfilled assets remaining when an order was canceled.
status shows the fill state of the order. It can be waiting
, pending
, canceled
, partial_filled
or full_filled
.
waiting
: Only for stop limit orders. This is a stop limit order before triggered or canceled.pending
: The order has not been completely filled, so availableAmount > 0 or pendingAmount > 0partial_filled
: The order was partially filled, but no longer has any available assets due to the rest being cancelled. More explicitly, both confirmedAmount and canceledAmount are positive and the sum of those two equals the total amount of the order.full_filled
: The order has been completely filled and confirmed, and thus confirmedAmount is equal to the total amount of the order.canceled
: The order was canceled before even partial fulfillment. This means canceledAmount is equal to the total amount of the order.
Cancel Order
Response
{
"status": 0,
"desc": "success"
}
Used to cancel an order given an orderId
HTTP Request
DELETE https://api.ddex.io/v4/orders/:orderId
URL Parameters
Parameter | Description | Required | Type | Example |
---|---|---|---|---|
orderId | The id of the order you wish to cancel. | required | string | 0x23..a3 |
Details
This API inserts a cancel-order-event
into matching engine message queue, waits for a matching result, then returns the order details. It will return an error if the order doesn't exist or is not in a cancellable state(e.g. being fulfilled).
List Orders
Response
{
"status": 0,
"desc": "success",
"data": {
"totalCount": 100,
"totalPages": 10,
"currentPage": 1,
"orders": [
{
"id": "0xb8beb447e62a8f22c0e3fad435b43e28e365c297366c0016563b9ddb0a7bedf1",
"type": "limit",
"version": "hydro-v2",
"status": "pending",
"amount": "1",
"availableAmount": "1",
"pendingAmount": "0",
"canceledAmount": "0",
"confirmedAmount": "0",
"price": "2",
"averagePrice": "0",
"side": "buy",
"makerFeeRate": "0.00100",
"takerFeeRate": "0.01000",
"makerRebateRate": "0.00100",
"gasFeeAmount": "0.127706049036078318",
"account": "0x85cf54dd216997bcf324c72aa1c845be2f059299",
"createdAt": 1544091412000,
"marketId": "ETH-USDT",
"json": {
"data": "0x010000005c122e28006403e80064000000000009aa3f00000000000000000000",
"trader": "0x85cf54dd216997bcf324c72aa1c845be2f059299",
"relayer": "0xd4a1963e645244c7fb4fe8efab12e4bc02c5fad3",
"baseAsset": "0xa0530fa979fdbc3c6e8a91573277827826b80950",
"signature": {
"r": "0xcae9f845e40a2d8de9fd4703c85e85ba71d5c1f58b5ba9e8b5f50110fcdebea1",
"s": "0x75e4d7b22e34322076423f3c43275ac165ff10f412793cd6f545cfe602509d39",
"config": "0x1c01"
},
"quoteAsset": "0x9712e6cadf82d1902088ef858502ca17261bb893",
"gasAssetAmount": "127706049036078317",
"baseAssetAmount": "1000000000000000000",
"quoteAssetAmount": "2000000000000000000"
}
}
]
}
}
Return paginated data for all orders created by the currently authenticated trading account. The orders are sorted by creation time in descending order.
HTTP Request
GET https://api.ddex.io/v4/orders
Query Parameters
Parameter | Description | Required | Type | Example |
---|---|---|---|---|
marketId | The market you wish to list orders from. Specified in the form of a trading pair. | optional | string | ETH-USDT |
status | pending or all . |
optional (default: pending ) |
string | pending |
page | Used for pagination. | optional (default: 1 ) |
number | 1 |
perPage | Used for pagination. Value must be between 1-100 . |
optional (default: 100 ) |
number | 100 |
Details
Please see Place Order for a description of the data returned for each order in the list.
Get Order
Response
{
"status": 0,
"desc": "success",
"data": {
"order": {
"id": "0xde27b4cd08177f11a129490c872729976856291e8169e40e8cc75454b271c948",
"type": "limit",
"version": "hydro-v2",
"status": "full filled",
"amount": "1",
"availableAmount": "0",
"pendingAmount": "0",
"canceledAmount": "0",
"confirmedAmount": "1",
"price": "1",
"averagePrice": "0.7778615582982067",
"side": "sell",
"makerFeeRate": "0.00100",
"takerFeeRate": "0.00200",
"makerRebateRate": "0.00100",
"gasFeeAmount": "0.222138441701793308",
"account": "0x85cf54dd216997bcf324c72aa1c845be2f059299",
"createdAt": 1545203072441,
"marketId": "ETH-USDT",
"json": {
"data": "0x01010007b3cb197d006400c8006400000000000491d700000000000000000000",
"trader": "0x85cf54dd216997bcf324c72aa1c845be2f059299",
"relayer": "0xd10bc568235c6838b0620e2081643deecbddf504",
"baseAsset": "0x6829f329f8f0768ad62a65477514deed90825564",
"signature": {
"r": "0x933c050e69ad2b797c3b0b39bbe5971a93e422151264e474ae7d211e46ffdd01",
"s": "0x5f896a53b6eb1109b4d840f8b512b5a342efa1b8aa873d714d11849e96fdff40",
"config": "0x1c01"
},
"quoteAsset": "0x9712e6cadf82d1902088ef858502ca17261bb893",
"gasAssetAmount": "222138441701793307",
"baseAssetAmount": "1000000000000000000",
"quoteAssetAmount": "1000000000000000000"
}
}
}
}
Return a single order identified by orderId
HTTP Request
GET https://api.ddex.io/v4/orders/:orderId
URL Parameters
Parameter | Description | Required | Type | Example |
---|---|---|---|---|
orderId | The id of the order you wish to query. | required | string | 0x12..d3 |
Details
Please see Place Order for a description of the data returned for the order.
List Account Trades
Response
{
"status": 0,
"desc": "success",
"data": {
"count": 2,
"trades": [
{
"id": "e301b19c-d182-4e72-9bfd-f1900732e20a",
"transactionId": "fef48697-ca12-4f37-9037-e035e839ee5b",
"transactionHash": "0x8dd184cc2aa39b97c67ee90cfc9c648a10fba2106edb6c61eb5829ecd6972294",
"status": "successful",
"marketId": "ETH-USDT",
"maker": "0xbf1ac1aaffc2db4471efa455e553a0725d8e54fb",
"taker": "0x1a671e90db05af4b128ac4faef01f5a36de468ad",
"buyer": "0xbf1ac1aaffc2db4471efa455e553a0725d8e54fb",
"seller": "0x1a671e90db05af4b128ac4faef01f5a36de468ad",
"makerOrderId": "0x54bbffbf6c5261b078efa00f7f2208fc2dd98050d619fde634dd6065e2f0bda4",
"takerOrderId": "0x76f3a1c0fc52caa3ba44969b759805ba1024cc63bc725725b5970f8d7d426a62",
"makerBalanceCategory": 0,
"makerMarginMarketId": 0,
"takerBalanceCategory": 0,
"takerMarginMarketId": 0,
"sequence": 0,
"amount": "0.59",
"price": "167.73",
"takerPrice": "0",
"feeAmount": "0.0633333333333334",
"bid": "167.73",
"ask": "168.26",
"rebateAmount": "0",
"executedAt": 1567139127000,
"createdAt": 1567139060785,
"updatedAt": 1567139147767
}
]
}
}
Return paginated data for all trades made by the currently authenticated user account in a single market identified by marketId. The trades are sorted by creation time in descending order.
HTTP Request
GET https://api.ddex.io/v4/markets/:marketId/trades/mine
URL Parameters
Parameter | Description | Required | Type | Example |
---|---|---|---|---|
marketId | Query for trade data on a specific market. Specified in the form of a trading pair. | required | string | ETH-USDT |
Query Parameters
Parameter | Description | Required | Type | Example |
---|---|---|---|---|
page | Used for pagination. | optional (default: 1 ) |
number | 1 |
perPage | Used for pagination. Value must be between 1-100 . |
optional (default: 100 ) |
number | 100 |
Details
Returns all of the authenticated user's trade data for the specified market. Results will be paginated with a default page size of 20 results.
Each set of trade data contains all the information about the maker (creator of the order) and taker, including account addresses, order ids, and the final transaction id. It also includes all the order details including the price and amount of the order. We also return the feeAmount paid to the exchange, as well as the takerPrice. Finally you can view the status of the order, the time at which the trade was created due to matching orders in the book (createdAt) and the time the trade was completed on the blockchain (executedAt).
List Locked Balances
Response
{
"status": 0,
"desc": "success",
"data": {
"lockedBalances": [
{
"address": "0x79e83661810b8e997616ed2a9dc1a9cfe42fdc95",
"symbol": "USDT",
"assetAddress": "0xdac17f958d2ee523a2206206994597c13d831ec7",
"walletType": "margin",
"marginMarketId": 0,
"amount": "0"
}
]
}
}
List locked balances of each active symbol on the market for the currently authenticated user.
HTTP Request
GET https://api.ddex.io/v4/account/lockedBalances
Details
The locked balance for a symbol is the amount of that asset that is currently listed in orders owned by the currently authenticated user. For example, if the account has created 3 sell orders for the USDT
symbol at 100
, 1000
, and 500
assets respectively, and the orders are still pending, the locked balance for USDT
will be 1600
.
List Positions
Response
{
"status": 0,
"desc": "success",
"data": {
"positions": [
{
"account": "0x1a671e90db05af4b128ac4faef01f5a36de468ad",
"recordType": "staged_margin_account",
"marginMarketId": 0,
"netAssetValue": "18.738149497192065481",
"cost": "24.81072",
"baseDebtAmount": "0.592344381990880356",
"basePrincipleBalanceAmount": "0.592",
"baseAccumulateInterestAmount": "0.000344381990880356",
"quoteDebtAmount": "0",
"quotePrincipleBalanceAmount": "0",
"quoteAccumulateInterestAmount": "0",
"blockNumber": 8474474,
"blockTime": 1567477220000,
"createdAt": 1567445300636,
"updatedAt": 1567477229355,
"pnlRatio": "-0.2447559161043265"
}
]
}
}
Lists the authenticated account's positions for all margin markets
HTTP Request
GET https://api.ddex.io/v4/positions
Details
The units of cost and netAssetValue are in USD.
Websocket
Overview
The Websocket API is intended to provide real-time updates to the state of the market. In order to receive updates, you must open a socket to the websocket endpoint, and send a subscription message. This message will define what real-time data you are interested in, so you only get the updates you need.
Endpoint: wss://ws.ddex.io/v4
Subscribe
Request
{
"type": "subscribe",
"channels": [
{
"name": "full",
"marketIds": ["ETH-USDT"]
},
{
"name": "ticker",
"marketIds": ["ETH-USDT"]
}
]
}
Response
{
"type": "subscriptions",
"channels": [
{
"name": "full",
"marketIds": ["ETH-USDT"]
},
{
"name": "ticker",
"marketIds": ["ETH-USDT"]
}
]
}
To begin receiving websocket messages, you must first send a subscribe message to the server indicating which channels you are interested in, and for which markets you wish to receive updates.
JSON Fields
Parameter | Description |
---|---|
type | Action |
channels | An array of Channel Data describing which channels and markets you wish to subscribe to. |
Channel Data
Parameter | Description |
---|---|
name | ticker , orderbook , or full |
marketIds | An array of market ids, specified in the form of a trading pair of assets, e.g. ETH-USDT |
Details
Once a subscribe message is received, the server will respond with a subscriptions message that lists all channels you are currently subscribed to.
Unsubscribe
Request
{
"type": "unsubscribe",
"channels": [
{
"name": "full",
"marketIds": ["ETH-USDT"]
}
]
}
Response
{
"type": "subscriptions",
"channels": [
{
"name": "ticker",
"marketIds": ["ETH-USDT"]
}
]
}
If you are no longer interested in a channel, you may send an unsubscribe message to the server indicating which channels you no longer wish to receive updates for.
JSON Fields
Parameter | Description |
---|---|
type | unsubscribe |
channels | An array of Channel Data describing which channels and markets you wish to unsubscribe to. |
Channel Data
Parameter | Description |
---|---|
name | ticker , orderbook , or full |
marketIds | An array of market ids, specified in the form of a trading pair of assets, e.g. ETH-USDT |
Details
Once an unsubscribe message is received, the server will respond with a subscriptions message that lists all channels you are currently subscribed to.
Ticker Channel
Subscription Request
{
"type": "subscribe",
"channels": [
{
"name": "ticker",
"marketIds": ["ETH-USDT"]
}
]
}
Sample Message
{
"type": "ticker",
"time": 1520847743338,
"marketId": "ETH-USDT",
"bid": null,
"price": "0.08",
"amount": "20",
"volume": "1",
"high": "0.08",
"low": "0",
"tradeId": "f8548cd5-b9be-4e43-a6e8-12b468c7dd6c",
"transactionHash": "0x2e044e7bbaf30cda209ee434fe45aac571e005a1e7fbec78af6958c21382f1b2",
"makerSide": "sell"
}
Subscribing to the ticker channel will provide real time price updates every time a trade is completed. In case of cascading trades, the updates will be batched to avoid excess bandwidth usage.
Details
The ticker data returned in the message includes the marketId, as well as the current price, volume, high and low values for that market.
Orderbook Channel
Subscription Request
{
"type": "subscribe",
"channels": [
{
"name": "orderbook",
"marketIds": ["ETH-USDT"]
}
]
}
Snapshot Message
{
"type": "level2OrderbookSnapshot",
"marketId": "ETH-USDT",
"bids": [
{ "price": "0.007", "amount": "400" },
{ "price": "0.00911", "amount": "270" },
{ "price": "0.00913", "amount": "190" },
{ "price": "0.014412", "amount": "120" },
{ "price": "0.014413", "amount": "220" },
{ "price": "0.014434", "amount": "130" },
{ "price": "0.014438", "amount": "170" },
{ "price": "0.014456", "amount": "100" },
{ "price": "0.01448", "amount": "200" },
{ "price": "0.0145", "amount": "400" }
],
"asks": [
{ "price": "0.01498", "amount": "100" },
{ "price": "0.014977", "amount": "130" },
{ "price": "0.014971", "amount": "130" },
{ "price": "0.014949", "amount": "130" },
{ "price": "0.014855", "amount": "146" },
{ "price": "0.014848", "amount": "110" },
{ "price": "0.014843", "amount": "100" },
{ "price": "0.014818", "amount": "100" },
{ "price": "0.01481", "amount": "82" },
{ "price": "0.0148", "amount": "400" },
{ "price": "0.014774", "amount": "100" }
]
}
Update Message
{
"type": "level2OrderbookUpdate",
"marketId": "ETH-USDT",
"changes": [{ "side": "sell", "price": "0.014789", "amount": "0" }]
}
The orderbook channel provides an easy way to maintain a live view of the aggregated orderbook.
Snapshot
After subscribing to the channel, it will send a message of type level2OrderbookSnapshot for each subscribed market. The message is a complete, although aggregated, snapshot of the current orderbook, where bids and asks are lists of json data containing price and amount of asset available at that price (aggregated over all orders in the book).
Update
Once you get the initial snapshot, messages will be sent corresponding to any change in the orderbook. The message will have the type level2OrderbookUpdate and list which market the change occurred in. It also contains a list of changes which contain which side the change occurred on, the price the change occurred at, and the new amount at that price level.
Note that if the new amount in an update is 0, the price level can be removed from your orderbook.
Full Channel
Subscription Request
{
"type": "subscribe",
"channels": [
{
"name": "full",
"marketIds": ["ETH-USDT"]
}
]
}
Snapshot Message
{
"type": "level3OrderbookSnapshot",
"marketId": "ETH-USDT",
"sequence": 345,
"bids": [
{
"price": "0.00054",
"amount": "1200",
"orderId": "0xabde02351..."
}
],
"asks": [
{
"price": "0.00064",
"amount": "40000",
"orderId": "0x4055f060c..."
}
]
}
Receive Message
{
"type": "receive",
"time": 1520577582556,
"marketId": "ETH-USDT",
"sequence": 1,
"price": "0.1",
"orderId": "0xa60d846292e50bed9a37eac69d91bb9180ed754f43fa44c5dff5bf9aeddb5128",
"orderType": "limit",
"side": "sell",
"canceledAmount": "0",
"confirmedAmount": "0",
"availableAmount": "1",
"pendingAmount": "0"
}
Open Message
{
"type": "open",
"time": 1520837845343,
"marketId": "ETH-USDT",
"sequence": 2,
"price": "0.8",
"orderId": "0x531b9e9e7aba5f4f84940e4a9923ce44cf8a43b6e3f5aac98d56e439e467efdb",
"orderType": "limit",
"side": "sell",
"canceledAmount": "0",
"confirmedAmount": "0",
"availableAmount": "1",
"pendingAmount": "0"
}
Done Message
{
"type": "done",
"time": 1520837846102,
"marketId": "ETH-USDT",
"sequence": 14,
"price": "0.8",
"orderId": "0x531b9e9e7aba5f4f84940e4a9923ce44cf8a43b6e3f5aac98d56e439e467efdb",
"orderType": "limit",
"side": "sell",
"canceledAmount": "0",
"confirmedAmount": "0",
"availableAmount": "0",
"pendingAmount": "1"
}
Change Message
{
"type": "change",
"time": 1520837846102,
"marketId": "ETH-USDT",
"sequence": 14,
"price": "0.8",
"orderId": "0x531b9e9e7aba5f4f84940e4a9923ce44cf8a43b6e3f5aac98d56e439e467efdb",
"orderType": "limit",
"side": "sell",
"oldAvailableAmount": "2",
"newAvailableAmount": "1"
}
Trade Message
{
"type": "trade",
"time": 1520844812020,
"marketId": "ETH-USDT",
"sequence": 15,
"price": "0.8",
"transactionId": "0xb1a42cbe03b749edb07d220286f4c99c5ac6ebcac6f8ef92b26769cb5f0f0fc2",
"makerOrderId": "0x1f6d2e6c9deba47c842eda4a1529f53d4d74c071ab6dffcf8d4b71a5bc913c2b",
"takerOrderId": "0x50ca7438f009d752bd4bd093d93f1db49076dea0c566690891cd6b9fee4c2343",
"taker": "0x5409ed021d9299bf6814279a6a1411a7e866a631",
"maker": "0x1edad6dad44367a6e0e342e76e9df595049b8224",
"amount": "1",
"makerSide": "sell"
}
Trade Success Message
{
"type": "trade_success",
"time": 1520844820685,
"marketId": "ETH-USDT",
"price": "0.09",
"transactionId": "0x9ed3c60f199aaadf13e9766ceebb156f10817a2186a78f3f3f374757471bbfc5",
"makerOrderId": "0x722794395d38d70c848be14484f016c8bb696c15c655bea3a951d47ae413f731",
"takerOrderId": "0x8a3eddfd60a64714afcbfdf1079a45bcb6707931142e9cdc03181f6d5dd03640",
"amount": "0.5",
"makerSide": "sell"
}
The full channel provides real-time updates on all orders and trades for the specified markets. These updates can be applied on to a level 3 orderbook snapshot to maintain an accurate, non-aggregated copy of the exchange orderbook.
Sequence Numbers
Updates you receive will contain a sequence number. Sequence numbers are increasing integer values that will always increase by 1 for each new message in the sequence. If the sequence number you receive is more than 1 higher than the previous value, then a message has been dropped. If you see a sequence number lower than the previous value, then a message has arrived out of order and can likely be ignored. In both cases you may need to perform some logic to get your system to consistent state. For example, if you miss a change message, you should resubscribe to the channel in order to receive a full snapshot message and reset your state.
Snapshot
After subscribing to the channel, it will send a message of type level3OrderbookSnapshot for each subscribed market. The message is a complete, non-aggregated snapshot of the current orderbook, where bids and asks are lists of json data containing price, amount, and the orderId for the order it represents. These data blobs are not aggregated, so you will receive one for every order on the market.
Receive
A valid order has been received and is now active. This message is emitted for every valid order as soon as the matching engine receives it, whether it fills immediately or not.
Open
A new order is now open on the orderbook. This message will only be sent for orders which are not fulfilled immediately. availableAmount will indicate how much of the order is unfulfilled and available on the orderbook.
Done
An order is no longer available on the orderbook. This message can result from an order being canceled or completely filled. There will be no more messages for this orderId once this message has been received. canceledAmount indicates how much of the order went unfulfilled, and confirmedAmount indicates how much of the order was fulfilled.
Change
If an order is changed due to self-trade prevention, you will receive a change message for that orderId. It will contain the oldAvailableAmount, as well as the newAvailableAmount which is the amount of asset left over in the order that can still be fulfilled.
Trade
Two orders have been matched, and a trade has occurred. The orders will be marked as pending until the trade is successfully validated on the blockchain.
Trade Success
A trade has been validated on the blockchain.