Introduction

API Key Setup

API Key Restrictions

Contact Us

General Info

General API Information

HTTP Return Codes

Error Codes and Messages

The error payload on API is as follows:

{
  "error":"Invalid symbol."
}

LIMITS

IP Limits

Websocket Limits

API Limit Introduction

The /api/* endpoints adopt either of two access limiting rules, IP limits or UID (account) limits.

Data Sources

These are the three sources, ordered by which is has the most up-to-date response to the one with potential delays in updates.

Endpoint security type

Security Type Description
NONE Endpoint can be accessed freely.
TRADE Endpoint requires sending a valid API-Key and signature.
USER_DATA Endpoint requires sending a valid API-Key and signature.
USER_STREAM Endpoint requires sending a valid API-Key.
MARKET_DATA Endpoint requires sending a valid API-Key.

SIGNED (TRADE, AND USER_DATA ) Endpoint security

SIGNED Endpoint Examples for POST /api/v2/order

Here is a step-by-step example of how to send a valid signed payload from the Linux command line using echo, openssl, and curl.

Key Value
apiKey vmPUZE6mv9SD5VNHk4HlWFsOr6aKE2zvsw0MuIgwCIPy6utIco14y7Ju91duEh8A
secretKey NhqPtmdSJYdKjVHjA7PZj4Mge3R5YNiP1e3UZjInClVN65XAbvqqM6A7H5fATj0j
Parameter Value
symbol LTC/BTC
side BUY
type LIMIT
timeInForce GTC
quantity 1
price 0.1
timestamp 1499827319559

Example : As a request body

Example

HMAC SHA256 signature:

    $ echo -n "{"symbol":"LTC/BTC","side":"BUY","type":"LIMIT","timeInForce":"GTC","quantity":1,"price":0.1,"timestamp":1499827319559}" | openssl dgst -sha256 -hmac "NhqPtmdSJYdKjVHjA7PZj4Mge3R5YNiP1e3UZjInClVN65XAbvqqM6A7H5fATj0j"
    (stdin)= 57e52eb7945cdfa8938e607fa3e3c498dc531b0639e62c276d6f92e31f3095a1

curl command:

    (HMAC SHA256)
    $ curl -H 'X-MBX-APIKEY: vmPUZE6mv9SD5VNHk4HlWFsOr6aKE2zvsw0MuIgwCIPy6utIco14y7Ju91duEh8A' -H 'signature: 57e52eb7945cdfa8938e607fa3e3c498dc531b0639e62c276d6f92e31f3095a1' -H 'Content-Type: application/json' -X POST 'https://carbon.credit/api/v2/order' -d '{"symbol":"LTC/BTC","side":"BUY","type":"LIMIT","timeInForce":"GTC","quantity":1,"price":0.1,"timestamp":1499827319559}'

{ "symbol":"LTC/BTC", "side":"BUY", "type":"LIMIT", "timeInForce":"GTC", "quantity":1, "price":0.1, "timestamp":1499827319559 }

Public API Definitions

Terminology

These terms will be used throughout the documentation, so it is recommended especially for new users to read to help their understanding of the API.

ENUM definitions

Symbol status (status):

Account and Symbol Permissions (permissions):

Order status (status):

Status Description
NEW The order has been accepted by the engine.
PARTIALLY_FILLED A part of the order has been filled.
FILLED The order has been completed.
CANCELED The order has been canceled by the user.
PENDING_CANCEL Currently unused
REJECTED The order was not accepted by the engine and not processed.
EXPIRED The order was canceled according to the order type's rules (e.g. LIMIT FOK orders with no fill, LIMIT IOC or MARKET orders that partially fill) or by the exchange, (e.g. orders canceled during liquidation, orders canceled during maintenance)

OCO Status (listStatusType):

Status Description
RESPONSE This is used when the ListStatus is responding to a failed action. (E.g. Orderlist placement or cancellation)
EXEC_STARTED The order list has been placed or there is an update to the order list status.
ALL_DONE The order list has finished executing and thus no longer active.

OCO Order Status (listOrderStatus):

Status Description
EXECUTING Either an order list has been placed or there is an update to the status of the list.
ALL_DONE An order list has completed execution and thus no longer active.
REJECT The List Status is responding to a failed action either during order placement or order canceled.)

Order types (orderTypes, type):

Order Response Type (newOrderRespType):

Order side (side):

Time in force (timeInForce):

This sets how long an order will be active before expiration.

Status Description
GTC Good Til Canceled
An order will be on the book unless the order is canceled.
IOC Immediate Or Cancel
An order will try to fill the order as much as it can before the order expires.
FOK Fill or Kill
An order will expire if the full order cannot be filled upon execution.

Kline/Candlestick chart intervals:

s-> seconds; m -> minutes; h -> hours; d -> days; w -> weeks; M -> months

Market Data Endpoints

Exchange Information

Response:


[
  {
    "exchangeFilters": [],
    "rateLimits": [
      {
        "interval": "MINUTE",
        "intervalNum": 1,
        "limit": 900,
        "rateLimitType": "ORDERS"
      }
    ],
    "serverTime": 1686824188823,
    "instruments": [],
    "instrumentPairs": [
      [
        53,
        "ETH/USD",
        1,
        2,
        2,
        6,
        1,
        "null",
        "PAIR",
        "ETH",
        "USDC",
        "USDC",
        "USDC",
        "null",
        "null",
        2,
        0.009999999776482582,
        0.009999999776482582,
        0,
        0.01,
        0,
        -1,
        0,
        "",
        0,
        "M",
        "",
        0,
        "",
        "",
        "",
        -1,
        0,
        "",
        "SECONDARY"
      ]
    ]
  }
]

GET /api/v2/exchangeInfo

Current exchange trading rules and symbol information

Parameters:

There are 3 possible options:

Options Example
No parameter curl -X GET "https://carbon.credit/api/v2/exchangeInfo"
verbose curl -X GET "https://carbon.credit/api/v2/exchangeInfo?verbose=true"
symbol curl -X GET "https://carbon.credit/api/v2/exchangeInfo?symbol=CCC-USD"

Notes:

Data Source: Memory

Order Book

Response:

{
  "lastUpdateId": 1027024,
  "bids": [
    [
      "4.00000000",     // PRICE
      "431.00000000"    // QTY
    ]
  ],
  "asks": [
    [
      "4.00000200",
      "12.00000000"
    ]
  ]
}

GET /api/v2/depth

Parameters:

Name Type Mandatory Description
symbol STRING YES e.g. ETH-USD
limit INT NO Default 100; max 5000.
If limit > 5000, then the response will truncate to 5000.

Data Source: Memory

Recent Trades List

Response:

[
  {
    "id": 28457,
    "price": "4.00000100",
    "qty": "12.00000000",
    "quoteQty": "48.000012",
    "time": 1499865549590,
    "isBuyerMaker": true,
    "isBestMatch": true
  }
]

GET /api/v2/trades

Get recent trades.

Parameters:

Name Type Mandatory Description
symbol STRING YES e.g. ETH-USD
limit INT NO Default 500; max 1000.

Data Source: Memory

Websocket Market Streams

Live Subscribing/Unsubscribing to streams

Subscribe to a stream

Response

  {
    "result": null,
    "id": 1
  }

Unsubscribe to a stream

Response

  {
    "result": null,
    "id": 312
  }

{
"method": "UNSUBSCRIBE",
"params":
[
"BTC-USD@depth"
],
"id": 312
}

Listing Subscriptions

Response

  {
    "result": [
      "BTC-USD@aggTrade"
    ],
    "id": 3
  }

{
"method": "LIST_SUBSCRIPTIONS",
"id": 3
}

Setting Properties

Currently, the only property can be set is to set whether combined stream payloads are enabled or not. The combined property is set to false when connecting using /ws/ ("raw streams") and true when connecting using /stream/.

Response

{
  "result": null,
  "id": 5
}

{
"method": "SET_PROPERTY",
"params":
[
"combined",
true
],
"id": 5
}

Retrieving Properties

Response

  {
    "result": true, // Indicates that combined is set to true.
    "id": 2
  }

{
"method": "GET_PROPERTY",
"params":
[
"combined"
],
"id": 2
}

Error Messages

Error Message Description
{"code": 0, "msg": "Unknown property", "id": '%s'} Parameter used in the SET_PROPERTY or GET_PROPERTY was invalid
{"code": 1, "msg": "Invalid value type: expected Boolean", "id": '%s'} Value should only be true or false
{"code": 2, "msg": "Invalid request: property name must be a string"} Property name provided was invalid
{"code": 2, "msg": "Invalid request: request ID must be an unsigned integer"} Parameter id had to be provided or the value provided in the id parameter is an unsupported type
{"code": 2, "msg": "Invalid request: unknown variant %s, expected one of SUBSCRIBE, UNSUBSCRIBE, LIST_SUBSCRIPTIONS, SET_PROPERTY, GET_PROPERTY at line 1 column 28"} Possible typo in the provided method or provided method was neither of the expected values
{"code": 2, "msg": "Invalid request: too many parameters"} Unnecessary parameters provided in the data
{"code": 2, "msg": "Invalid request: property name must be a string"} Property name was not provided
{"code": 2, "msg": "Invalid request: missing field method at line 1 column 73"} method was not provided in the data
{"code":3,"msg":"Invalid JSON: expected value at line %s column %s"} JSON data sent has incorrect syntax.

Aggregate Trade Streams

Payload:

{
  "e": "aggTrade",  // Event type
  "E": 123456789,   // Event time
  "s": "CCC/USD",    // Symbol
  "a": 12345,       // Aggregate trade ID
  "p": "0.001",     // Price
  "q": "100",       // Quantity
  "f": 100,         // First trade ID
  "l": 105,         // Last trade ID
  "T": 123456785,   // Trade time
  "m": true,        // Is the buyer the market maker?
  "M": true         // Ignore
}

The Aggregate Trade Streams push trade information that is aggregated for a single taker order.

Stream Name: <symbol>@aggTrade

Update Speed: Real-time

Trade Streams

Payload:

{
  "e": "trade",     // Event type
  "E": 123456789,   // Event time
  "s": "CCC/USD",    // Symbol
  "t": 12345,       // Trade ID
  "p": "0.001",     // Price
  "q": "100",       // Quantity
  "b": 88,          // Buyer order ID
  "a": 50,          // Seller order ID
  "T": 123456785,   // Trade time
  "m": true,        // Is the buyer the market maker?
  "M": true         // Ignore
}

The Trade Streams push raw trade information; each trade has a unique buyer and seller.

Stream Name: <symbol>@trade

Update Speed: Real-time

Kline/Candlestick Streams

Payload:

{
  "e": "kline",     // Event type
  "E": 123456789,   // Event time
  "s": "CCC/USD",    // Symbol
  "k": {
    "t": 123400000, // Kline start time
    "T": 123460000, // Kline close time
    "s": "CCC/USD",  // Symbol
    "i": "1m",      // Interval
    "f": 100,       // First trade ID
    "L": 200,       // Last trade ID
    "o": "0.0010",  // Open price
    "c": "0.0020",  // Close price
    "h": "0.0025",  // High price
    "l": "0.0015",  // Low price
    "v": "1000",    // Base asset volume
    "n": 100,       // Number of trades
    "x": false,     // Is this kline closed?
    "q": "1.0000",  // Quote asset volume
    "V": "500",     // Taker buy base asset volume
    "Q": "0.500",   // Taker buy quote asset volume
    "B": "123456"   // Ignore
  }
}

The Kline/Candlestick Stream push updates to the current klines/candlestick every second.

Stream Name: <symbol>@kline_<interval>

Update Speed: 2000ms

Kline/Candlestick chart intervals:

s-> seconds; m -> minutes; h -> hours; d -> days; w -> weeks; M -> months

Individual Symbol Mini Ticker Stream

Payload:

  {
    "e": "24hrMiniTicker",  // Event type
    "E": 123456789,         // Event time
    "s": "CCC/USD",          // Symbol
    "c": "0.0025",          // Close price
    "o": "0.0010",          // Open price
    "h": "0.0025",          // High price
    "l": "0.0010",          // Low price
    "v": "10000",           // Total traded base asset volume
    "q": "18"               // Total traded quote asset volume
  }

24hr rolling window mini-ticker statistics. These are NOT the statistics of the UTC day, but a 24hr rolling window for the previous 24hrs.

Stream Name: <symbol>@miniTicker

Update Speed: 1000ms

All Market Mini Tickers Stream

Payload:

[
  {
    // Same as <symbol>@miniTicker payload
  }
]

24hr rolling window mini-ticker statistics for all symbols that changed in an array. These are NOT the statistics of the UTC day, but a 24hr rolling window for the previous 24hrs. Note that only tickers that have changed will be present in the array.

Stream Name: !miniTicker@arr

Update Speed: 1000ms

Individual Symbol Ticker Streams

Payload:

{
  "e": "24hrTicker",  // Event type
  "E": 123456789,     // Event time
  "s": "CCC/USD",      // Symbol
  "p": "0.0015",      // Price change
  "P": "250.00",      // Price change percent
  "w": "0.0018",      // Weighted average price
  "x": "0.0009",      // First trade(F)-1 price (first trade before the 24hr rolling window)
  "c": "0.0025",      // Last price
  "Q": "10",          // Last quantity
  "b": "0.0024",      // Best bid price
  "B": "10",          // Best bid quantity
  "a": "0.0026",      // Best ask price
  "A": "100",         // Best ask quantity
  "o": "0.0010",      // Open price
  "h": "0.0025",      // High price
  "l": "0.0010",      // Low price
  "v": "10000",       // Total traded base asset volume
  "q": "18",          // Total traded quote asset volume
  "O": 0,             // Statistics open time
  "C": 86400000,      // Statistics close time
  "F": 0,             // First trade ID
  "L": 18150,         // Last trade Id
  "n": 18151          // Total number of trades
}

24hr rolling window ticker statistics for a single symbol. These are NOT the statistics of the UTC day, but a 24hr rolling window for the previous 24hrs.

Stream Name: <symbol>@ticker

Update Speed: 1000ms

All Market Tickers Stream

Payload:

[
  {
    // Same as <symbol>@ticker payload
  }
]

24hr rolling window ticker statistics for all symbols that changed in an array. These are NOT the statistics of the UTC day, but a 24hr rolling window for the previous 24hrs. Note that only tickers that have changed will be present in the array.

Stream Name: !ticker@arr

Update Speed: 1000ms

Individual Symbol Rolling Window Statistics Streams

Payload:

{
  "e": "1hTicker",    // Event type
  "E": 123456789,     // Event time
  "s": "CCC/USD",      // Symbol
  "p": "0.0015",      // Price change
  "P": "250.00",      // Price change percent
  "o": "0.0010",      // Open price
  "h": "0.0025",      // High price
  "l": "0.0010",      // Low price
  "c": "0.0025",      // Last price
  "w": "0.0018",      // Weighted average price
  "v": "10000",       // Total traded base asset volume
  "q": "18",          // Total traded quote asset volume
  "O": 0,             // Statistics open time
  "C": 86400000,      // Statistics close time
  "F": 0,             // First trade ID
  "L": 18150,         // Last trade Id
  "n": 18151          // Total number of trades
}

Rolling window ticker statistics for a single symbol, computed over multiple windows.

Stream Name: <symbol>@ticker_<window_size>

Window Sizes: 1h,4h,1d

Update Speed: 1000ms

Note: This stream is different from the <symbol>@ticker stream. The open time O always starts on a minute, while the closing time C is the current time of the update.

As such, the effective window might be up to 59999ms wider that <window_size>.

All Market Rolling Window Statistics Streams

Payload:

[
  {
    // Same as <symbol>@ticker_<window-size> payload,
    // one for each symbol updated within the interval.
  }
]

Rolling window ticker statistics for all market symbols, computed over multiple windows. Note that only tickers that have changed will be present in the array.

Stream Name: !ticker_<window-size>@arr

Window Size: 1h,4h,1d

Update Speed: 1000ms

Individual Symbol Book Ticker Streams

Payload:

{
  "u":400900217,     // order book updateId
  "s":"BNBUSDT",     // symbol
  "b":"25.35190000", // best bid price
  "B":"31.21000000", // best bid qty
  "a":"25.36520000", // best ask price
  "A":"40.66000000"  // best ask qty
}

Pushes any update to the best bid or ask's price or quantity in real-time for a specified symbol.

Multiple <symbol>@bookTicker streams can be subscribed to over one connection.

Stream Name: <symbol>@bookTicker

Update Speed: Real-time

All Book Tickers Stream

Payload:

{
  // Same as <symbol>@bookTicker payload
}

Pushes any update to the best bid or ask's price or quantity in real-time for all symbols.

Stream Name: !bookTicker

Update Speed: Real-time

Partial Book Depth Streams

Payload:

{
  "lastUpdateId": 160,  // Last update ID
  "bids": [             // Bids to be updated
    [
      "0.0024",         // Price level to be updated
      "10"              // Quantity
    ]
  ],
  "asks": [             // Asks to be updated
    [
      "0.0026",         // Price level to be updated
      "100"             // Quantity
    ]
  ]
}

Top bids and asks, Valid are 5, 10, or 20.

Stream Names: <symbol>@depth<levels> OR <symbol>@depth<levels>@100ms.

Update Speed: 1000ms or 100ms

Diff. Depth Stream

Payload:

{
  "e": "depthUpdate", // Event type
  "E": 123456789,     // Event time
  "s": "CCC/USD",      // Symbol
  "U": 157,           // First update ID in event
  "u": 160,           // Final update ID in event
  "b": [              // Bids to be updated
    [
      "0.0024",       // Price level to be updated
      "10"            // Quantity
    ]
  ],
  "a": [              // Asks to be updated
    [
      "0.0026",       // Price level to be updated
      "100"           // Quantity
    ]
  ]
}

Stream Name: <symbol>@depth OR <symbol>@depth@100ms

Update Speed: 1000ms or 100ms

Order book price and quantity depth updates used to locally manage an order book.

How to manage a local order book correctly

  1. Open a stream to wss://carbon.credit/ws/CCC-USD@depth.
  2. Buffer the events you receive from the stream.
  3. Get a depth snapshot from https://carbon.credit/api/v2/depth?symbol=CCC-USD&limit=1000 .
  4. Drop any event where u is <= lastUpdateId in the snapshot.
  5. The first processed event should have U <= lastUpdateId+1 AND u >= lastUpdateId+1.
  6. While listening to the stream, each new event's U should be equal to the previous event's u+1.
  7. The data in each event is the absolute quantity for a price level.
  8. If the quantity is 0, remove the price level.
  9. Receiving an event that removes a price level that is not in your local order book can happen and is normal.

Note: Due to depth snapshots having a limit on the number of price levels, a price level outside of the initial snapshot that doesn't have a quantity change won't have an update in the Diff. Depth Stream. Consequently, those price levels will not be visible in the local order book even when applying all updates from the Diff. Depth Stream correctly and cause the local order book to have some slight differences with the real order book. However, for most use cases the depth limit of 5000 is enough to understand the market and trade effectively.

Spot Account/Trade

New Order (TRADE)

Response ACK:

{
  "symbol": "BTC/USDC",
  "orderId": 28,
  "orderListId": -1, //Unless OCO, value will be -1
  "clientOrderId": "6gCrw2kRUAF9CvJDGP16IP",
  "transactTime": 1507725176595
}

Response RESULT:

{
  "symbol": "BTC/USDC",
  "orderId": 28,
  "orderListId": -1, //Unless OCO, value will be -1
  "clientOrderId": "6gCrw2kRUAF9CvJDGP16IP",
  "transactTime": 1507725176595,
  "price": "0.00000000",
  "origQty": "10.00000000",
  "executedQty": "10.00000000",
  "cummulativeQuoteQty": "10.00000000",
  "status": "FILLED",
  "timeInForce": "GTC",
  "type": "MARKET",
  "side": "SELL",
  "strategyId": 1,               // This is only visible if the field was populated on order placement.
  "strategyType": 1000000        // This is only visible if the field was populated on order placement.
}

POST /api/v2/order (HMAC SHA256)

Send in a new order.

Parameters:

Name Type Mandatory Description
symbol STRING YES
side ENUM YES Used with BUY, SELL
type ENUM YES Used with MARKET, LIMIT, STOP, STOP_LIMIT, SELECT
timeInForce ENUM NO Used with GTC, IOC, FOK, POST_ONLY
quantity DECIMAL NO
price DECIMAL NO
newClientOrderId STRING NO A unique id among open orders. Automatically generated if not sent.
reduceOnly BOOLEAN NO Used with true, false
targetStrategy INT NO Used with REDUCE_ONLY=101, PROFIT_LIMIT=120, PROFIT_LIMIT_REDUCE_ONLY=121, PROFIT_MARKET=130, PROFIT_MARKET_REDUCE_ONLY=131, STOP_MARKET=150<, STOP_MARKET_REDUCE_ONLY=151, TRAILING_STOP_LIMIT=160, TRAILING_STOP_LIMIT_REDUCE_ONLY=161, TRAILING_STOP_MARKET=170, TRAILING_STOP_MARKET_REDUCE_ONLY=171, TWAP=180, TWAP_REDUCE_ONLY=181
stopPrice DECIMAL NO Used with STOP_LOSS, STOP_LOSS_LIMIT, TAKE_PROFIT, and TAKE_PROFIT_LIMIT orders.
recvWindow LONG NO The value cannot be greater than 60000
timestamp LONG YES
expireTime LONG NO
instrumentId LONG NO
isHidden INT NO Used with true1, false=0
assetId LONG NO Used with select assets
tokenId LONG NO Used with select assets
groupAssetId LONG NO Used with select assets
selectId LONG NO Used with select assets
quoteType ENUM NO Used with RFQ orders INDICATIVE, TRADEABLE, RESTRICTED_TRADEABLE, COUNTER_TRADEABLE, NONE
quoteTargetUserId LONG NO Used with select assets
origOrdId LONG NO
price2 DECIMAL NO
actionType INT NO Used with EDIT_RFQ_ORDER=1, RESPOND_RFQ_ORDER=2, ACCEPT_RFQ_ORDER=3
userId LONG NO
account LONG NO

Additional mandatory parameters based on type:

Type Additional mandatory parameters
LIMIT timeInForce, quantity, price
MARKET quantity or quoteOrderQty
STOP_LOSS quantity, stopPrice or trailingDelta
STOP_LOSS_LIMIT timeInForce, quantity, price, stopPrice or trailingDelta
TAKE_PROFIT quantity, stopPrice or trailingDelta
TAKE_PROFIT_LIMIT timeInForce, quantity, price, stopPrice or trailingDelta
LIMIT_MAKER quantity, price

Other info:

Trigger order price rules against market price for both MARKET and LIMIT versions:

Data Source: Matching Engine

Cancel Order (TRADE)

Response:

{
  "symbol": "LTC/BTC",
  "origClientOrderId": "myOrder1",
  "orderId": 4,
  "orderListId": -1, //Unless part of an OCO, the value will always be -1.
  "clientOrderId": "cancelMyOrder1",
  "price": "2.00000000",
  "origQty": "1.00000000",
  "executedQty": "0.00000000",
  "cummulativeQuoteQty": "0.00000000",
  "status": "CANCELED",
  "timeInForce": "GTC",
  "type": "LIMIT",
  "side": "BUY"
}

DELETE /api/v2/order (HMAC SHA256)

Cancel an active order.

Parameters:

Name Type Mandatory Description
symbol STRING YES
orderId LONG NO
origClientOrderId STRING NO
newClientOrderId STRING NO Used to uniquely identify this cancel. Automatically generated by default.
recvWindow LONG NO The value cannot be greater than 60000
timestamp LONG YES

Either orderId or origClientOrderId must be sent. If both orderId and origClientOrderId are provided, orderId takes precedence.

Data Source: Matching Engine

Query Order (USER_DATA)

Response:

{
  "symbol": "LTC/BTC",
  "orderId": 1,
  "orderListId": -1, //Unless OCO, value will be -1
  "clientOrderId": "myOrder1",
  "price": "0.1",
  "origQty": "1.0",
  "executedQty": "0.0",
  "cummulativeQuoteQty": "0.0",
  "status": "NEW",
  "timeInForce": "GTC",
  "type": "LIMIT",
  "side": "BUY",
  "stopPrice": "0.0",
  "time": 1499827319559,
  "updateTime": 1499827319559,
  "isWorking": true,
  "origQuoteOrderQty": "0.000000"
}

GET /api/v2/orderStatus (HMAC SHA256)

Check an order's status.

Parameters:

Name Type Mandatory Description
symbol STRING YES
orderId LONG NO
origClientOrderId STRING NO
recvWindow LONG NO The value cannot be greater than 60000
timestamp LONG YES

Notes:

Data Source: Memory => Database

Cancel Replace (TRADE)

Response SUCCESS:

//Both the cancel order placement and new order placement succeeded.
{
  "cancelResult": "SUCCESS",
  "newOrderResult": "SUCCESS",
  "cancelResponse": {
    "symbol": "BTC/USDC",
    "origClientOrderId": "DnLo3vTAQcjha43lAZhZ0y",
    "orderId": 9,
    "orderListId": -1,
    "clientOrderId": "osxN3JXAtJvKvCqGeMWMVR",
    "price": "0.01000000",
    "origQty": "0.000100",
    "executedQty": "0.00000000",
    "cummulativeQuoteQty": "0.00000000",
    "status": "CANCELED",
    "timeInForce": "GTC",
    "type": "LIMIT",
    "side": "SELL"
  },
  "newOrderResponse": {
    "symbol": "BTC/USDC",
    "orderId": 10,
    "orderListId": -1,
    "clientOrderId": "wOceeeOzNORyLiQfw7jd8S",
    "transactTime": 1652928801803,
    "price": "0.02000000",
    "origQty": "0.040000",
    "executedQty": "0.00000000",
    "cummulativeQuoteQty": "0.00000000",
    "status": "NEW",
    "timeInForce": "GTC",
    "type": "LIMIT",
    "side": "BUY",
    "fills": []
  }
}

Response when Cancel Order Fails with STOP_ON_FAILURE:

{
  "code": -2022,
  "msg": "Order cancel-replace failed.",
  "data": {
    "cancelResult": "FAILURE",
    "newOrderResult": "NOT_ATTEMPTED",
    "cancelResponse": {
      "code": -2011,
      "msg": "Unknown order sent."
    },
    "newOrderResponse": null
  }
}

Response when Cancel Order Succeeds but New Order Placement Fails:

{
  "code": -2021,
  "msg": "Order cancel-replace partially failed.",
  "data": {
    "cancelResult": "SUCCESS",
    "newOrderResult": "FAILURE",
    "cancelResponse": {
      "symbol": "BTC/USDC",
      "origClientOrderId": "86M8erehfExV8z2RC8Zo8k",
      "orderId": 3,
      "orderListId": -1,
      "clientOrderId": "G1kLo6aDv2KGNTFcjfTSFq",
      "price": "0.006123",
      "origQty": "10000.000000",
      "executedQty": "0.000000",
      "cummulativeQuoteQty": "0.000000",
      "status": "CANCELED",
      "timeInForce": "GTC",
      "type": "LIMIT_MAKER",
      "side": "SELL"
    },
    "newOrderResponse": {
      "code": -2010,
      "msg": "Order would immediately match and take."
    }
  }
}

Response when Cancel Order fails with ALLOW_FAILURE:

{
  "code": -2021,
  "msg": "Order cancel-replace partially failed.",
  "data": {
    "cancelResult": "FAILURE",
    "newOrderResult": "SUCCESS",
    "cancelResponse": {
      "code": -2011,
      "msg": "Unknown order sent."
    },
    "newOrderResponse": {
      "symbol": "BTC/USDC",
      "orderId": 11,
      "orderListId": -1,
      "clientOrderId": "pfojJMg6IMNDKuJqDxvoxN",
      "transactTime": 1648540168818
    }
  }
}

Response when both Cancel Order and New Order Placement fail:

{
  "code": -2022,
  "msg": "Order cancel-replace failed.",
  "data": {
    "cancelResult": "FAILURE",
    "newOrderResult": "FAILURE",
    "cancelResponse": {
      "code": -2011,
      "msg": "Unknown order sent."
    },
    "newOrderResponse": {
      "code": -2010,
      "msg": "Order would immediately match and take."
    }
  }
}

POST /api/v2/order/cancelReplace

Cancels an existing order and places a new order on the same symbol.

Filters and Order Count are evaluated before the processing of the cancellation and order placement occurs.

A new order that was not attempted (i.e. when newOrderResult: NOT_ATTEMPTED), will still increase the order count by 1.

Parameters:

Name Type Mandatory Description
symbol STRING YES
side ENUM YES
type ENUM YES
cancelReplaceMode ENUM YES The allowed values are:
STOP_ON_FAILURE - If the cancel request fails, the new order placement will not be attempted.
ALLOW_FAILURE - new order placement will be attempted even if cancel request fails.
timeInForce ENUM NO
quantity DECIMAL NO
quoteOrderQty DECIMAL NO
price DECIMAL NO
cancelNewClientOrderId STRING NO Used to uniquely identify this cancel. Automatically generated by default.
cancelOrigClientOrderId STRING NO Either the cancelOrigClientOrderId or cancelOrderId must be provided. If both are provided, cancelOrderId takes precedence.
cancelOrderId LONG NO Either the cancelOrigClientOrderId or cancelOrderId must be provided. If both are provided, cancelOrderId takes precedence.
newClientOrderId STRING NO Used to identify the new order.
strategyId INT NO
strategyType INT NO The value cannot be less than 1000000.
stopPrice DECIMAL NO
newOrderRespType ENUM NO Allowed values:
ACK, RESULT, FULL
MARKET and LIMIT orders types default to FULL; all other orders default to ACK
recvWindow LONG NO The value cannot be greater than 60000
timestamp LONG YES

Similar to POST /api/v2/order, additional mandatory parameters are determined by type.

Response format varies depending on whether the processing of the message succeeded, partially succeeded, or failed.

Data Source: Matching Engine

Current Open Orders (USER_DATA)

Response:

[
  {
    "symbol": "LTC/BTC",
    "orderId": 1,
    "orderListId": -1, //Unless OCO, the value will always be -1
    "clientOrderId": "myOrder1",
    "price": "0.1",
    "origQty": "1.0",
    "executedQty": "0.0",
    "cummulativeQuoteQty": "0.0",
    "status": "NEW",
    "timeInForce": "GTC",
    "type": "LIMIT",
    "side": "BUY",
    "stopPrice": "0.0",
    "time": 1499827319559,
    "updateTime": 1499827319559,
    "isWorking": true,
    "origQuoteOrderQty": "0.000000"
  }
]

GET /api/v2/openOrders (HMAC SHA256)

Get all open orders on a symbol. Careful when accessing this with no symbol.

Parameters:

Name Type Mandatory Description
symbol STRING NO
recvWindow LONG NO The value cannot be greater than 60000
timestamp LONG YES

Data Source: Memory => Database

All Orders (USER_DATA)

Response:

[
  {
    "symbol": "LTC/BTC",
    "orderId": 1,
    "orderListId": -1, //Unless OCO, the value will always be -1
    "clientOrderId": "myOrder1",
    "price": "0.1",
    "origQty": "1.0",
    "executedQty": "0.0",
    "cummulativeQuoteQty": "0.0",
    "status": "NEW",
    "timeInForce": "GTC",
    "type": "LIMIT",
    "side": "BUY",
    "stopPrice": "0.0",
    "time": 1499827319559,
    "updateTime": 1499827319559,
    "isWorking": true,
    "origQuoteOrderQty": "0.000000"
  }
]

GET /api/v2/allOrders (HMAC SHA256)

Get all account orders; active, canceled, or filled.

Parameters:

Name Type Mandatory Description
symbol STRING YES
orderId LONG NO
startTime LONG NO
endTime LONG NO
limit INT NO Default 500; max 1000.
recvWindow LONG NO The value cannot be greater than 60000
timestamp LONG YES

Notes:

Data Source: Database

Account Information (USER_DATA)

Response:

{
  "makerCommission": 15,
  "takerCommission": 15,
  "buyerCommission": 0,
  "sellerCommission": 0,
  "canTrade": true,
  "canWithdraw": true,
  "canDeposit": true,
  "brokered": false,
  "updateTime": 123456789,
  "accountType": "SPOT",
  "balances": [
    {
      "asset": "BTC",
      "free": "4723846.89208129",
      "locked": "0.00000000"
    },
    {
      "asset": "LTC",
      "free": "4763368.68006011",
      "locked": "0.00000000"
    }
  ],
  "permissions": [
    "SPOT"
  ]
}

GET /api/v2/account (HMAC SHA256)

Get current account information.

Parameters:

Name Type Mandatory Description
recvWindow LONG NO The value cannot be greater than 60000
timestamp LONG YES

Data Source: Memory => Database

Account Trade List (USER_DATA)

Response:

[
  {
    "symbol": "CCC/USD",
    "id": 28457,
    "orderId": 100234,
    "orderListId": -1, //Unless OCO, the value will always be -1
    "price": "4.00000100",
    "qty": "12.00000000",
    "quoteQty": "48.000012",
    "commission": "10.10000000",
    "commissionAsset": "USD",
    "time": 1499865549590,
    "isBuyer": true,
    "isMaker": false,
    "isBestMatch": true
  }
]

GET /api/v2/myTrades (HMAC SHA256)

Get trades for a specific account and symbol.

Parameters:

Name Type Mandatory Description
symbol STRING YES
orderId LONG NO This can only be used in combination with symbol.
startTime LONG NO
endTime LONG NO
fromId LONG NO TradeId to fetch from. Default gets most recent trades.
limit INT NO Default 500; max 1000.
recvWindow LONG NO The value cannot be greater than 60000
timestamp LONG YES

Notes:

Data Source: Memory => Database

Query Current Order Count Usage (TRADE)

Response:

[

  {
    "rateLimitType": "ORDERS",
    "interval": "SECOND",
    "intervalNum": 10,
    "limit": 10000,
    "count": 0
  },
  {
    "rateLimitType": "ORDERS",
    "interval": "DAY",
    "intervalNum": 1,
    "limit": 20000,
    "count": 0
  }
]

GET /api/v2/rateLimit/order

Displays the user's current order count usage for all intervals.

Parameters:

Name Type Mandatory Description
recvWindow LONG NO The value cannot be greater than 60000
timestamp LONG YES

Data Source: Memory

User Data Streams

LISTEN KEY (SPOT)

Create a ListenKey (USER_STREAM)

Response:


{
    "userId": 1,
    "listenKey": "pqia91ma19a5s61cv6a81va65sdf19v8a65a1a5s61cv6a81va65sdf19v8a65a1"
}

POST /api/v2/userDataStream

Start a new user data stream. The stream will close after 60 minutes unless a keepalive is sent. If the account has an active listenKey, that listenKey will be returned and its validity will be extended for 60 minutes.

Parameters:

NONE

Data Source: Memory

Ping/Keep-alive a ListenKey (USER_STREAM)

Response:


{
     "userId": 1,
    "listenKey": "pqia91ma19a5s61cv6a81va65sdf19v8a65a1a5s61cv6a81va65sdf19v8a65a1"
}

PUT /api/v2/userDataStream

Keepalive a user data stream to prevent a time out. User data streams will close after 60 minutes. It's recommended to send a ping about every 30 minutes.

>

Parameters:

Name Type Mandatory Description
listenKey STRING YES

Data Source: Memory

Close a ListenKey (USER_STREAM)

Response:

{}

DELETE /api/v2/userDataStream

Close out a user data stream.

Parameters:

Name Type Mandatory Description
listenKey STRING YES

Data Source: Memory

LISTEN KEY (MARGIN)

Create a ListenKey (USER_STREAM)

Response:

{"listenKey":  "T3ee22BIYuWqmvne0HNq2A2WsFlEtLhvWCtItw6ffhhdmjifQ2tRbuKkTHhr"}

POST /sapi/v1/userDataStream

Parameters:

NONE

Ping/Keep-alive a ListenKey (USER_STREAM)

Response:

{}

PUT /sapi/v1/userDataStream

Parameters:

Name Type Mandatory Description
listenKey STRING YES

Close a ListenKey (USER_STREAM)

Response:

{}

DELETE /sapi/v1/userDataStream

Parameters:

Name Type Mandatory Description
symbol STRING YES

Ping/Keep-alive a Listen Key (USER_STREAM)

Response:

{}

PUT /sapi/v1/userDataStream/isolated

Parameters:

Name Type Mandatory Description
symbol STRING YES
listenKey STRING YES

Close a ListenKey (USER_STREAM)

Response:

{}

DELETE /sapi/v1/userDataStream/isolated

Parameters:

Name Type Mandatory Description
symbol STRING YES
listenKey STRING YES

Payload: Account Update

outboundAccountPosition is sent any time an account balance has changed and contains the assets that were possibly changed by the event that generated the balance change.

Payload:

{
  "e": "outboundAccountPosition", //Event type
  "E": 1564034571105,             //Event Time
  "u": 1564034571073,             //Time of last account update
  "B": [                          //Balances Array
    {
      "a": "ETH",                 //Asset
      "f": "10000.000000",        //Free
      "l": "0.000000"             //Locked
    }
  ]
}

Payload: Balance Update

Balance Update occurs during the following:

Payload

{
  "e": "balanceUpdate",         //Event Type
  "E": 1573200697110,           //Event Time
  "a": "BTC",                   //Asset
  "d": "100.00000000",          //Balance Delta
  "T": 1573200697068            //Clear Time
}

Payload: Order Update

Orders are updated with the executionReport event.

Check the Public API Definitions and below for relevant enum definitions.

Average price can be found by doing Z divided by z.

Payload:

{
  "e": "executionReport",        // Event type
  "E": 1499405658658,            // Event time
  "s": "ETH/BTC",                 // Symbol
  "c": "mUvoqJxFIILMdfAW5iGSOW", // Client order ID
  "S": "BUY",                    // Side
  "o": "LIMIT",                  // Order type
  "f": "GTC",                    // Time in force
  "q": "1.00000000",             // Order quantity
  "p": "0.10264410",             // Order price
  "P": "0.00000000",             // Stop price
  "d": 4,                        // Trailing Delta; This is only visible if the order was a trailing stop order.
  "F": "0.00000000",             // Iceberg quantity
  "g": -1,                       // OrderListId
  "C": "",                       // Original client order ID; This is the ID of the order being canceled
  "x": "NEW",                    // Current execution type
  "X": "NEW",                    // Current order status
  "r": "NONE",                   // Order reject reason; will be an error code.
  "i": 4293153,                  // Order ID
  "l": "0.00000000",             // Last executed quantity
  "z": "0.00000000",             // Cumulative filled quantity
  "L": "0.00000000",             // Last executed price
  "n": "0",                      // Commission amount
  "N": null,                     // Commission asset
  "T": 1499405658657,            // Transaction time
  "t": -1,                       // Trade ID
  "I": 8641984,                  // Ignore
  "w": true,                     // Is the order on the book?
  "m": false,                    // Is this trade the maker side?
  "M": false,                    // Ignore
  "O": 1499405658657,            // Order creation time
  "Z": "0.00000000",             // Cumulative quote asset transacted quantity
  "Y": "0.00000000",             // Last quote asset transacted quantity (i.e. lastPrice * lastQty)
  "Q": "0.00000000",             // Quote Order Qty
  "j": 1,                        // Strategy ID; This is only visible if the strategyId parameter was provided upon order placement
  "J": 1000000                   // Strategy Type; This is only visible if the strategyType parameter was provided upon order placement
}

Execution types:

Payload

{
  "e": "listStatus",                //Event Type
  "E": 1564035303637,               //Event Time
  "s": "ETH/BTC",                    //Symbol
  "g": 2,                           //OrderListId
  "c": "OCO",                       //Contingency Type
  "l": "EXEC_STARTED",              //List Status Type
  "L": "EXECUTING",                 //List Order Status
  "r": "NONE",                      //List Reject Reason
  "C": "F4QN4G8DlFATFlIUQ0cjdD",    //List Client Order ID
  "T": 1564035303625,               //Transaction Time
  "O": [                            //An array of objects
    {
      "s": "ETH/BTC",                //Symbol
      "i": 17,                      // orderId
      "c": "AJYsMjErWJesZvqlJCTUgL" //ClientOrderId
    },
    {
      "s": "ETH/BTC",
      "i": 18,
      "c": "bfYPSQdLoqAJeNrOr9adzq"
    }
  ]
}