Introduction

Scroll down for code samples, example requests and responses. Select a language for code samples from the tabs above or the mobile navigation menu.

CoinList Pro API v1.3.0

The CoinList Pro API suite includes both REST and WebSocket endpoints that allow unauthenticated, public access to CoinList market data (quotes, auction results, order books, and symbol metadata) as well as private, authenticated access to trader orders, balances, and notifications.

General

Matching Engine

CoinList Pro's matching engine is based on the concept of frequent batch auctions. Order inserts, cancels, and modifies are timestamped by the API gateway and will be effected in the next auction following that timestamp.

Gateway Timestamps

Each request sent from a REST or WebSocket client to the CoinList Pro API Gateway will receive a timestamp. This timestamp will be returned to the client through the REST response body or WebSocket feed received message. It is important to note the timestamp at which the CoinList Pro API Gateway received your order operation requests, as that is the timestamp that will be honored by the discrete-time batch auctions. An example of a situation where the timestamp is crucial in understanding the logical operations of the matching engine is described below.

"Fills-After-Cancels"

Because CoinList Pro blends "real-time" order operations with discrete-time auction periods, there are some situations that can occur that will be unfamiliar to traders used to traditional continuous matching engines. One example of this is the possible receipt of a filled message after a canceled message. Here's a situation where this could occur:

1. A trader places an order timestamped at 00:00:01.500.

2. The trader cancels that order and their request is timestamped at 00:00:02.001.

3. The 00:00:02 auction is computed at 00:00:02.050. This auction includes this order, as it was canceled after the logical end time of the auction.

4. The trader receives a canceled message with timestamp 00:00:02.001.

5. The trader receives a filled message with timestamp 00:00:02.000 (the logical end time of the 00:00:02 auction in which the order was filled).

This example demonstrates a possibly unintuitive interaction between real-time order operations and the batch auction series computed over discrete time periods. API consumers should always use the timestamp of messages - and not the time or order messages were received - to deduce the logical sequence of CoinList Pro market behavior.

Self-Trade Prevention

Two orders from the same trader never fill one another. When a user has orders on both sides of an auction, any overlapping orders (i.e. bids above the user's lowest ask and asks below the user's highest bid) will be handled by the self-trade prevention strategy specified for the newest order. When placing an order, you may specify the one of the following self-trade prevention strategies:

• Keep Newest (default) (keep-newest) When self-crossing orders are detected, the newest orders of the crossing set are kept and any orders that cross with them are excluded from participating in the auction. See below for what happens to the excluded orders.

• Keep Oldest (keep-oldest) When self-crossing orders are detected, the oldest orders of the crossing set are kept and any orders that cross with them are excluded from participating in the auction. See below for what happens to the excluded orders.

• Cancel All (cancel-all) When self-crossing orders are detected, the entire set of crossing orders are rejected and do not participate in the auction. The rest of the user's (non-crossing) orders are not affected.

When orders are excluded from an auction they will be rejected and not eligible to participate in future auctions unless all three of the following conditions are met: 1) the excluded order was a limit order, 2) the order it was across from was a market order, and 3) the auction crosses at a price that would not have filled the limit order. In that case the limit order is retained in the order book and is eligible to participate in future auctions.

Price Determination

If there is a range of prices that would yield the same level of transacted volume in an auction, the execution price will be the price in that range closest to the last trade price (or the last trade price itself, if it is in the range). If there is no last trade price, the midpoint price of the crossing orders is chosen.

Examples

• User A places a buy order for 1 BTC at 100 USD. User B places a sell order for 1 BTC at 80 USD. The last auction with volume crossed at a price of 90 USD. Users A and B will be filled at 90 USD, as that price satisfies both limit conditions and is closest to the last trade price.

• User A places a buy order for 1 BTC at 100 USD. User B places a sell order for 1 BTC at 80 USD. The last auction with volume crossed at a price of 50 USD. Users A and B will be filled at 80 USD, as that price satisfies both limit conditions and is closest to the last trade price.

Indicative Auctions

Before coming back form an outage, we'll run indicative auctions for some time before opening up trading. (This period is generally 10 minutes but may be adjusted based on the quality of the order book.) During this time, traders will be able to modify orders, but there will be no crosses and thus no fills. Auction results are computed and and transmitted over the auctions WebSocket channel but they will be indicative-only and fills will not be recorded. During a market's indicative period, the order book will be distributed over the level2 and it may at times be crossed.

Dark Indicative Auctions

During the launch of some pairs, CoinList Pro may announce that the indicative period will not include order book information beyond best bid and ask (level 1) and thus be "dark" (as opposed to "lit"). During dark indicative auctions, the level2 channel will return an empty snapshot (including a is_dark_period flag in the data object) and the /symbol/{symbol}/book route will return an empty book.

Specifying Orders

Lifecycle

The response from POST /v1/orders will include the CoinList Pro order_id (a uuid) that can be used to reference the order in future calls as well as the timestamp the order was received by the CoinList Pro API gateway.

received orders have been received by the gateway and are being checked for acceptance by the clearing house.

accepted orders have been accepted by the CoinList Pro clearing house and will be included in the next auction. Orders in this state may have been partially filled. There is no separate filled state, besides done below.

rejected orders have been rejected by the CoinList Pro clearing house due to a lack of funds to cover the asset hold required to open the order or restrictions in-place (like self-trading prevention). Orders in this state may have fills as an order may transition from accepted to rejected in some scenarios. Orders that were received and immediately rejected are not recorded and are not retrievable by CoinList Pro API queries.

canceled orders have been canceled by the user or by CoinList (possibly after some quantity has been filled).

done orders have been either completely filled or are no longer active (but were not canceled).

Order Types

Each order has a type which specifies how it is executed by the matching engine. The order type is always a required field, and must be one of the following values.

Orders of all types may be partially filled. If an order is not completely filled in one auction, it will live on until it is either completely filled or canceled by the user.

Market

A market order is an order to execute immediately at the current market price. The order must include a side (buy or sell) and a size indicating the quantity.

The order is filled at the crossing price of the next auction(s) with available liquidity, and will rest on the book over multiple auctions until filled or canceled.

Note that unlike limit orders, market orders provide no price guarantees. Further, in cases where market moves substantially or if the market order trades across several levels of the book, it's important to understand that all trades in that auction pay the same crossing price.

Limit

A limit order is an order to execute at or better than a specified price. The order must include a side (buy or sell) and a size indicating the quantity.

The order is filled at the crossing price of the next auction(s) with available liquidity AND in which the crossing price is equal to or better than the order price. This guarantees the maximum price the order may trade at, but may result in the order taking a long time to fill, filling only partially, or even failing to fill at all.

Stop Market / Limit

A stop_market or stop_limit order is an instruction to add a market or limit order to the book once the trigger price has crossed the stop_price. The order must include a side and size (and in the case of a stop limit, a price) which describe the order to be added once the stop is triggered. In addition, the order must include a stop_price which indicates the price at which to trigger the stop. The stop may be configured to trigger on last trade or underlying index price using the stop_trigger property.

Stop orders rest in the matching engine until an auction crosses at a price 'outside' the stop_price:

• buy - the stop triggers when the trigger price is greater than or equal to the stop_price
• sell - the stop triggers when the trigger price is less than or equal to the stop_price

Immediately following the auction which crosses the stop_price, the stop order is converted to a regular market or limit order using the included side and size. This order becomes available for execution in the first auction following the one which triggered the stop. The order will incur the standard fees, as any order inserted at the time of the trigger would.

While it is untriggered a stop order is invisible, and is not included in the book. Once it is triggered it becomes visible (as it is now a normal order).

Note that the time priority of the order is the time at which it was triggered, rather than the time at which the stop was last updated.

Trailing Stop

A stop_market or stop_limit order may be specified with either a fixed or percentage trailing value (using the peg_price_type and peg_offset_value order properties). For example, on a stop_market sell order a $-100 offset value will have the effect of setting the stop price $100 below the trigger price (specified as with a regular stop order using the stop_trigger property.) Note the stop price will only update as the market moves away from the stop price, not towards it. This has the effect of moving the stop price of a stop sell order up along with the market, but keeps it constant as the price falls towards the stop (and vice-versa for a stop buy order.) Just as with a normal stop, the order must include a side and size (and in the case of a stop limit, a price) which describe the order to be added once the stop is triggered. A trailing stop order must not include a stop_price as it will be set relative to the peg.

Take Profit Market / Limit

A take_market or take_limit order is the same as a stop market or limit order, but with the trigger directions reversed. That is:

• buy - the take profit order triggers when the trigger price is less than or equal to the stop_price
• sell - the take profit order triggers when the trigger price is greater than or equal to the stop_price

Conditions

We do not support any special order conditions at this time. All orders are considered good-til-canceled (GTC) orders.

Price

Prices must always be specified in the quote currency of the symbol and in increments of the symbol's minimum price increment (tick size). Symbol metadata is available from the list symbols route. Note that prices should always be specified as a string.

Quantity

Order sizes in the CoinList Pro API are always unsigned; the side specifies whether the order quantity should represent a buy or a sell. The maximum precision of all quantities is 1E-4 (meaning the smallest quantity increment is 0.0001). The unit of all order quantities is the symbol's base currency. Symbol metadata is available from the list symbols route. Note that quantities should always be specified as a string with four decimal places.

Holds

We will place a hold on your asset balance in the amount required to back all active orders plus applicable transaction fees. The hold for an order will be lifted as soon as that order is filled, partially filled, or canceled.

Price Bands

To protect against order entry errors, limit orders will be rejected if their limit price is 5% beyond the reference price and they would cross in the previous auction (execute immediately). The reference price is defined as the crossing price of the last auction, if there was a cross, and the impact mid ("fair price") if not. See Help & Support for definition of the fair price.

Similarly, market orders have an implicit limit price of 5% beyond the reference price. This is to prevent a trader inserting market orders from unintended slippage.

Symbols

Symbols on CoinList Pro are designated by ids like BTC-USD. This id describes a spot market with base currency code BTC and quote currency code USD.

Symbols for perpetual futures contracts are designated by ids like BTC-PERP, where BTC refers to the underlying asset and PERP denotes that the symbol refers to a perpetual swap.

Requests

CoinList Pro REST API requests and responses are all application/json content type and follow standard HTTP response status codes.

Rate Limits

There are a few different request limits to be aware of:

• Unauthenticated requests to the CoinList Pro REST API are limited to 1000 requests per 5 minutes.
• Authenticated requests to the CoinList Pro REST API are also currently limited to 1000 requests per 5 minutes, but may be raised in the future.
• WebSocket connections are limited to 40 per 5 minutes.
• Upstream WebSocket messages (subscriptions and trading operations) consume from the same rate limits as REST requests.

All request limiters refill continuously. If you breach a request limit, you will receive an HTTP response with code 429: Too Many Requests. If you're sending a WebSocket message, you'll receive a message with "type": "error" and a message field letting you know details of the breach.

Note that you may call public, unauthenticated REST endpoints using authenticated requests in order to use the higher rate limit.

The following informational HTTP headers are included with all REST responses:

The CoinList Pro REST API Gateway also has DDOS protections in-place. If your requests are being limited by this system, you will receive an HTTP response with code 403: Forbidden.

Bulk Order Operations

To encourage the use of bulk order create, modify, and delete operations (over both REST and WebSocket), these operations contribute to rate limit usage at a reduced rate. A bulk order operation will use tokens at a rate of ceil(# of orders / 2). For example, placing 3 orders in one bulk message is treated as 2 messages. Placing 5 orders is treated as 3.

Errors

Errors and bad requests will result in HTTP 4xx status codes. The response body will also contain message and message_code parameters with more details.

WebSocket messages may contain errors, as well, with message and message_code (and usually message_details) included in the data property in the message.

There is a list of possible message_code values here.

Success

Successful responses will return HTTP status code 200 and may also contain a body.

Pagination

Requests for /orders, /fills, /accounts/{trader_id}/ledger, and /symbols/{symbol}/auctions return arrays and are paginated using cursor pagination (with ISO timestamps used as cursors). You may supply pagination parameters start_time, end_time, descending, and count as query parameters to these endpoints. Chronologically sorted pages of 200 items are retuned, by default. You may specify a larger page size (up to 500 items) and reverse chronological order (newest first) by specifying the count and descending query parameters respectively.

If descending = false (the default), then your results will start at start_time (or if unspecified, the beginning of time) and stop at end_time (or until the maximum page size is reached). Alternatively, if descending = true, then your results will start at end_time (or if unspecified, the current time) and stop at start_time (or until the maximum page size is reached).

Types

Numbers

Decimal numbers will always be returned from CoinList Pro REST and WebSocket APIs as strings. This is required in order to preserve precision across various client-side languages and platforms. When consuming a string-valued decimal number from an API response, make sure to use a library that preserves floating-point precision (like BigNumber, in Java).

We recommend that decimal numbers in requests be submitted as strings, as well - though, our API will accept numbers as long as they are out beyond the precision requirements of the value being submitted.

Timestamps

All timestamps returned by CoinList Pro APIs will be in ISO 8601 format including milliseconds (2018-09-02T23:28:45.043Z).

Futures

CoinList Pro is excited to launch futures trading, starting with perpetual futures contracts.

Perpetual futures offer similar advantages to regular futures, but traders are allowed to hold positions indefinitely. These contracts track the spot price of the underlying asset closely through a mechanism involving the mark price and funding rates.

This product is in beta and the details here are subject to change.

Mark Price

The mark price is a fair price calculation used to prevent unfair liquidations and is derived from an average of spot prices across major exchanges and a decaying moving average of the difference between that spot price and the trading price of the perpetual future on CoinList Pro.

The mark price is calculated as:

Mark Price = Clamp(Index Price + EMA(Impact Mid - Index Price))

where EMA denotes an expotential moving average with a period of 10s and Clamp limits the range of Mark Price to within 0.5% of the Index Price.

Funding Rate

The funding rate is a periodic payment exchanged between traders holding long and short positions in a perpetual swap contract.

When the contract price is above the spot price, the longs pay the shorts, and vice versa. This mechanism helps to constrain the contract price to the underlying market value of the asset.

The funding rate is calculated every minute as a Time-Weighted Moving Average (TWAP) of the Premium Rate over the last 8 hours as follows

Funding Rate = TWAP(Premium Rate - Interest Rate)

and

Premium Rate = (Mark Price - Index Price) / Index Price

The Index Price represents the underlying spot price and is based on a combination of price data from multiple sources. Currently, the Interest Rate is set at 0%.

Funding payments are settled at a frequency of every 8 hours at 04:00 (UTC), 12:00 (UTC), and 20:00 (UTC).

The payments are calculated based on the nominal value of your position and settled in USDT:

Funding Fee (in USDT) = Funding Rate x Nominal Position Value (in USDT)

Trader API

The CoinList Pro REST API allows private (authenticated) access to your:

• balances
• orders
• fills
• treasury (deposits / withdrawals)
• trading accounts

REST API ENDPOINT URL
https://trade-api.coinlist.co/v1

Authentication

There are two methods of authentication supported by the CoinList Pro API REST endpoints:

• Session-based Authentication
• API Key Authentication

Session-based Authentication

This form of authentication is used by the official web and mobile CoinList Pro clients. It is not intended for third-party users of the API. To use this method, you'll need to pass the clpsid and X-Trader-Id-Token headers in every REST request and WebSocket connection attempt.

API Key Authentication

This is the recommended form of authentication for CoinList Pro API users. To use this form of authentication, you must supply three parameters with every REST request:

• CL-ACCESS-KEY

The API key as a string.

• CL-ACCESS-SIG

The base64 encoded signature (see Signing a Message below).

• CL-ACCESS-TIMESTAMP

The timestamp of your request. This must be the number of integer seconds since the Unix Epoch in UTC.

All request bodies should have content type application/json and be valid JSON.

Signing a Message

var crypto = require('crypto');

var secret = '<MY SECRET>';

var timestamp = Math.round(Date.now() / 1000);
var path = '/v1/orders';

var body = JSON.stringify({
  symbol: 'BTC-USD',
  size: '1.0125',
  price: '6500.00',
  type: 'limit',
});

var method = 'POST';

// create the prehash string by concatenating required parts
var what = timestamp + method + path + body;

// decode the base64 secret
var key = Buffer.from(secret, 'base64');

// create a sha256 hmac with the secret
var hmac = crypto.createHmac('sha256', key);

// sign the require message with the hmac
// and finally base64 encode the result
return hmac.update(what).digest('base64');

The CL-ACCESS-SIG header is generated by creating a sha256 HMAC using the base64-decoded secret key on the prehash string timestamp + HTTP method + path + body (where '+' represents string concatenation) and base64-encode the output. The timestamp value is the same as the CL-ACCESS-TIMESTAMP header.

The body is the request body string or omitted if there is no request body (typically for GET requests).

Note:

• The HTTP method should be UPPER CASE.
• Do not include a newline at the end of your prehash string.
• Include the /v1 prefix in path in your prehash string.
• If the body is '{}', do not include it in the signature. (Treat it as an empty string.)
• You must base64-encode the signature (the output of the sha256 HMAC).

Accounts

List Fees

GET /fees

Get fee schedules for all markets, possibly specific to the currently authenticated entity and account.

Example responses

200 Response

{
  "fees_by_symbols": {
    "BTC-USD,ETH-USD": {
      "base": {
        "fees": {
          "maker": 0.0035,
          "taker": 0.005
        },
        "floors": {
          "maker": 0.0035,
          "taker": 0.005
        }
      },
      "volume_tier_1": {
        "fees": {
          "maker": 0.0035,
          "taker": 0.005
        },
        "floors": {
          "maker": 0.0035,
          "taker": 0.005
        }
      }
    }
  }
}

Responses

Response Schema

Status Code 200

List Accounts

GET /accounts

Get a list of all trading accounts for the current user.

Example responses

200 Response

{
  "accounts": [
    {
      "trader_id": "b18507ce-7d55-4bf1-b12a-0ccca5b90936",
      "name": "string"
    }
  ]
}

Responses

Response Schema

Status Code 200

Get Account Summary

GET /accounts/{trader_id}

Get balance details for a trading account including asset balances, current active-order balance holds, and net liquidation value.

Parameters

Example responses

200 Response

{
  "asset_balances": {
    "BTC": "0.00308696",
    "ETH": "20.000000000000000000"
  },
  "asset_holds": {
    "BTC": "0.00000000",
    "ETH": "1.000000000000000000"
  },
  "portfolio_value_usd": "string",
  "net_liquidation_value_usd": "string",
  "unrealized_pnl_usd": "string",
  "initial_margin_required_usd": "string",
  "liquidation_margin_required_usd": "string",
  "available_funds_usd": "string",
  "excess_liquidity_usd": "string"
}

Responses

Get Account Alias

GET /accounts/{trader_id}/alias

Get trading account alias for a given account.

Parameters

Example responses

200 Response

{
  "alias": "string",
  "is_real_name": true
}

Responses

Response Schema

Status Code 200

Update Account Alias

PUT /accounts/{trader_id}/alias

Get your account info including balances, margin requirements, and net liquidation value.

Body parameter

{
  "alias": "string"
}

Parameters

Example responses

200 Response

{
  "alias": "string"
}

Responses

Response Schema

Status Code 200

Get Account History

GET /accounts/{trader_id}/ledger

List ledger entries (transactions) on the trading account. Transactions either increase or decrease your balance in a specific asset. Examples of transactions are deposits, withdrawals, trades, and fee collection.

Parameters

Example responses

200 Response

{
  "transactions": [
    {
      "transaction_id": "0fec1e58-b197-4052-99cf-2218496c5482",
      "created_at": "2019-08-24T14:15:22Z",
      "asset": "string",
      "symbol": "string",
      "amount": "string",
      "type": "fee",
      "details": {}
    }
  ]
}

Responses

Get CoinList Wallets

GET /accounts/{trader_id}/wallets

Get the account's CoinList wallets and balances.

Parameters

Example responses

200 Response

[
  {
    "asset": "string",
    "balance": "string"
  }
]

Responses

Response Schema

Status Code 200

Get CoinList Wallet Ledger

GET /accounts/{trader_id}/wallet-ledger

List ledger entries (transactions) for one of the account's CoinList wallets.

Parameters

Example responses

200 Response

[
  {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "description": "string",
    "asset": "string",
    "amount": "string",
    "created_at": "2019-08-24T14:15:22Z"
  }
]

Responses

Response Schema

Status Code 200

Get Daily Account Summary

GET /accounts/{trader_id}/ledger-summary

Roll-up ledger entries (transactions) on a trader account to daily frequency and summarize by transaction type. See Get Account History for more information on the source data for this roll-up.

Parameters

Enumerated Values

Example responses

200 Response

{
  "summary": [
    {
      "date": "2019-08-24",
      "eod_balance": "string",
      "amounts": {
        "fee": "string",
        "xfer": "string",
        "swap": "string",
        "affil": "string",
        "other": "string"
      }
    }
  ]
}

Responses

Keys

List API Keys

GET /keys

Get a list of all API keys (but not secrets). Secrets are only returned at the time of key creation.

Example responses

200 Response

{
  "api_keys": {
    "key": "4adfe27e-63d3-45b9-8238-62b6ed6fdb5e",
    "read": true,
    "write": true,
    "transfer": true
  }
}

Responses

Response Schema

Status Code 200

Create API Key

POST /keys

Mint a new API key.

Body parameter

{
  "read": true,
  "write": true,
  "transfer": true
}

Parameters

Example responses

200 Response

{
  "trader_id": "b18507ce-7d55-4bf1-b12a-0ccca5b90936",
  "key": "4adfe27e-63d3-45b9-8238-62b6ed6fdb5e",
  "secret": "string",
  "read": true,
  "write": true,
  "transfer": true
}

Responses

Delete API Key

DELETE /keys/{key}

Revoke an existing API key.

Parameters

Example responses

200 Response

{
  "message": "string",
  "key": "4adfe27e-63d3-45b9-8238-62b6ed6fdb5e"
}

Responses

Response Schema

Status Code 200

Fills

List Fills

GET /fills

Returns all fills for the current trading account - in descending chronological order.

Parameters

Example responses

200 Response

{
  "fills": [
    {
      "symbol": "string",
      "auction_code": "string",
      "order_id": "93101167-9065-4b9c-b98b-5d789a3ed9fe",
      "quantity": "string",
      "fee": "string",
      "fee_type": "string",
      "price": "string",
      "logical_time": "2019-08-24T14:15:22Z"
    }
  ]
}

Responses

Orders

List Orders

GET /orders

Returns orders for the current trading account - in descending chronological order.

By default, GET /orders returns active orders. To return other statuses, pass the status query parameter. Note that you may return orders with multiple statuses, you may pass the status parameter multiple times.

Parameters

Example responses

200 Response

{
  "orders": [
    {
      "order_id": "93101167-9065-4b9c-b98b-5d789a3ed9fe",
      "client_id": "string",
      "symbol": "string",
      "type": "market",
      "side": "buy",
      "size": "string",
      "price": "string",
      "stop_price": "string",
      "stop_trigger": "mark",
      "self_trade_prevention": "keep-newest",
      "average_fill_price": "string",
      "fill_fees": "string",
      "size_filled": "string",
      "created_at": "2019-08-24T14:15:22Z",
      "epoch_timestamp": "2019-08-24T14:15:22Z",
      "post_only": true,
      "peg_price_type": "trailing-stop",
      "peg_offset_value": "string",
      "origin": "web",
      "status": "pending"
    }
  ]
}

Responses

Create New Order

POST /orders

You may specify a custom client id for your order by supplying the optional body parameter client_id. This can be any string up to 256 characters. This id is included in all orders messages sent to the client on the orders WebSocket channel (or in REST responses). This can be useful to allow API users to match CoinList Pro order ids with a custom id created on their end.

Note that you may also submit orders through the CoinList Pro WebSocket Feed. This may be a better option due to the ability to keep a persistent connection open and the rate limits enforced on CoinList Pro REST endpoints.

For more information, see Specifying Orders.

Body parameter

{
  "client_id": "string",
  "symbol": "string",
  "type": "market",
  "side": "buy",
  "size": "string",
  "price": "string",
  "stop_price": "string",
  "stop_trigger": "mark",
  "self_trade_prevention": "keep-newest",
  "post_only": true,
  "peg_price_type": "trailing-stop",
  "peg_offset_value": "string",
  "origin": "web"
}

Parameters

Example responses

202 Response

{
  "message": "string",
  "timestamp": "2019-08-24T14:15:22Z",
  "order": {
    "symbol": "string",
    "type": "market",
    "side": "buy",
    "size": "string",
    "price": "string",
    "stop_price": "string",
    "stop_trigger": "mark",
    "self_trade_prevention": "keep-newest",
    "post_only": true,
    "peg_price_type": "trailing-stop",
    "peg_offset_value": "string",
    "origin": "web",
    "client_id": "string",
    "order_id": "93101167-9065-4b9c-b98b-5d789a3ed9fe",
    "trader_id": "b18507ce-7d55-4bf1-b12a-0ccca5b90936"
  }
}

Responses

Cancel All Orders

DELETE /orders

Note that you may also cancel orders through the CoinList Pro WebSocket Feed. This may be a better option due to the ability to keep a persistent connection open and the rate limits enforced on CoinList Pro REST endpoints.

Parameters

Example responses

202 Response

{
  "message": "string",
  "timestamp": "2019-08-24T14:15:22Z"
}

Responses

Get Specific Order (by id)

GET /orders/{order_id}

Parameters

Example responses

200 Response

{
  "order_id": "93101167-9065-4b9c-b98b-5d789a3ed9fe",
  "client_id": "string",
  "symbol": "string",
  "type": "market",
  "side": "buy",
  "size": "string",
  "price": "string",
  "stop_price": "string",
  "stop_trigger": "mark",
  "self_trade_prevention": "keep-newest",
  "average_fill_price": "string",
  "fill_fees": "string",
  "size_filled": "string",
  "created_at": "2019-08-24T14:15:22Z",
  "epoch_timestamp": "2019-08-24T14:15:22Z",
  "post_only": true,
  "peg_price_type": "trailing-stop",
  "peg_offset_value": "string",
  "origin": "web",
  "status": "pending"
}

Responses

Modify Existing Order

PATCH /orders/{order_id}

You may modify the type, size, price, stop_price, and stop_trigger of an order. Your modified order will not retain the time-priority of the original order. Your order will retain the same order id.

If you're listening on the orders WebSocket channel for updates, you'll receive a modify-received message continaing the timestamp the CoinList Pro API Gateway received the modify request and a subsequent accepted message once your order is ready to be included in the next auction (or modify-rejected if your modification could not be applied). If your modification is rejected, the unmodified order will remain active.

If you update an order's size to a size equal to or less than the current sizeFilled, your request will be processed as a cancel.

Note that you may also modify orders through the CoinList Pro WebSocket Feed. This may be a better option due to the ability to keep a persistent connection open and the rate limits enforced on CoinList Pro REST endpoints.

Body parameter

{
  "type": "market",
  "side": "buy",
  "size": "string",
  "price": "string",
  "stop_price": "string",
  "stop_trigger": "mark",
  "post_only": true,
  "peg_price_type": "trailing-stop",
  "peg_offset_value": "string",
  "origin": "web"
}

Parameters

Example responses

202 Response

{
  "message": "string",
  "timestamp": "2019-08-24T14:15:22Z",
  "order": {
    "symbol": "string",
    "type": "market",
    "side": "buy",
    "size": "string",
    "price": "string",
    "stop_price": "string",
    "stop_trigger": "mark",
    "self_trade_prevention": "keep-newest",
    "post_only": true,
    "peg_price_type": "trailing-stop",
    "peg_offset_value": "string",
    "origin": "web",
    "client_id": "string",
    "order_id": "93101167-9065-4b9c-b98b-5d789a3ed9fe",
    "trader_id": "b18507ce-7d55-4bf1-b12a-0ccca5b90936"
  }
}

Responses

Cancel Specific Order (by id)

DELETE /orders/{order_id}

Note that you may also cancel orders through the CoinList Pro WebSocket Feed. This may be a better option due to the ability to keep a persistent connection open and the rate limits enforced on CoinList Pro REST endpoints.

Parameters

Example responses

202 Response

{
  "message": "string",
  "timestamp": "2019-08-24T14:15:22Z"
}

Responses

Dead Man's Switch (Auto-Cancel)

POST /orders/cancel-all-after

A "dead man's switch" (or auto-cancel functionality) can help prevent unexpected fills during a network disconnect or other system issue. This optional feature lets you set a timeout by calling this endpoint (or by sending an equivalent WebSocket message) that starts a timer for a specifed number of milliseconds. If you do not call this endpoint again before the timer runs out, all your orders will be canceled.

Note that all the orders for the callers account will be canceled, not only those that were created recently or created from the same IP.

Set the timeout to 0 to cancel the timer and keep your orders alive.

Body parameter

{
  "timeout": 0
}

Parameters

Example responses

default Response

{
  "message": "string",
  "message_code": "string",
  "message_details": {}
}

Responses

Reports

List Report Requests

GET /reports

Get a list of all reports requested for the current trading account, including a link to the report.

Parameters

Example responses

200 Response

{
  "reports": {
    "report_id": "5ed7905a-4735-4cf7-b1ab-521e066fb971",
    "created_at": "2019-08-24T14:15:22Z",
    "expires_at": "2019-08-24T14:15:22Z",
    "report_type": "account",
    "params": {},
    "state": "pending",
    "url": "string"
  }
}

Responses

Response Schema

Status Code 200

Enumerated Values

Request Report

POST /reports

Request a new fills or account report (CSV)

Body parameter

{
  "report_type": "account",
  "params": {}
}

Parameters

Enumerated Values

Example responses

202 Response

{
  "report_id": "5ed7905a-4735-4cf7-b1ab-521e066fb971"
}

Responses

Response Schema

Status Code 202

Balances

List Balances

GET /balances

Returns balance details for the current trading account including asset balances, current active-order balance holds, and net liquidation value.

Example responses

200 Response

{
  "asset_balances": {
    "BTC": "0.00308696",
    "ETH": "20.000000000000000000"
  },
  "asset_holds": {
    "BTC": "0.00000000",
    "ETH": "1.000000000000000000"
  },
  "portfolio_value_usd": "string",
  "net_liquidation_value_usd": "string",
  "unrealized_pnl_usd": "string",
  "initial_margin_required_usd": "string",
  "liquidation_margin_required_usd": "string",
  "available_funds_usd": "string",
  "excess_liquidity_usd": "string"
}

Responses

Transfers

List Transfers

GET /transfers

List transfers on the account. Transfers are either deposits and withdrawals and includes pending, confirmed, and canceled operations. This route only returns transfers between CoinList.co and CoinList Pro. It does not return external deposits or withdrawals.

Parameters

Example responses

200 Response

{
  "transfers": [
    {
      "transfer_id": "d4a2d8dd-7def-4545-a062-761683b9aa05",
      "created_at": "2019-08-24T14:15:22Z",
      "canceled_at": "2019-08-24T14:15:22Z",
      "confirmed_at": "2019-08-24T14:15:22Z",
      "asset": "string",
      "amount": "string",
      "status": "pending"
    }
  ]
}

Responses

Transfer Funds From Pro to Wallet

POST /transfers/to-wallet

Transfer funds from CoinList Pro trading account to CoinList wallet.

Body parameter

{
  "asset": "string",
  "amount": "string"
}

Parameters

Example responses

200 Response

{
  "transfer_id": "d4a2d8dd-7def-4545-a062-761683b9aa05"
}

Responses

Response Schema

Status Code 200

Transfer Funds From Wallet to Pro

POST /transfers/from-wallet

Transfer funds from CoinList wallet to CoinList Pro trading account.

Body parameter

{
  "asset": "string",
  "amount": "string"
}

Parameters

Example responses

200 Response

{
  "transfer_id": "d4a2d8dd-7def-4545-a062-761683b9aa05"
}

Responses

Response Schema

Status Code 200

Transfer Funds Between Entities

POST /transfers/internal-transfer

Transfer funds from one entity trading account to another within the same user account.

Body parameter

{
  "from_trader_id": "string",
  "to_trader_id": "string",
  "asset": "string",
  "amount": "string"
}

Parameters

Example responses

400 Response

{
  "message": "string",
  "message_code": "string",
  "message_details": {}
}

Responses

Request Withdrawal from Wallet

POST /transfers/withdrawal-request

Request a withdrawal from CoinList wallet. (Disabled by default. Contact us to apply for an exception.)

Body parameter

{
  "asset": "string",
  "amount": "string",
  "destination_address": "string"
}

Parameters

Example responses

200 Response

{
  "transfer_id": "d4a2d8dd-7def-4545-a062-761683b9aa05"
}

Responses

Response Schema

Status Code 200

Orders (Bulk)

Create New Orders

POST /orders/bulk

See the non-bulk Create New Order operation for details.

Note that you may also bulk create orders through the CoinList Pro WebSocket Feed. This may be a better option due to the ability to keep a persistent connection open and the rate limits enforced on CoinList Pro REST endpoints.

Body parameter

[
  {
    "client_id": "string",
    "symbol": "string",
    "type": "market",
    "side": "buy",
    "size": "string",
    "price": "string",
    "stop_price": "string",
    "stop_trigger": "mark",
    "self_trade_prevention": "keep-newest",
    "post_only": true,
    "peg_price_type": "trailing-stop",
    "peg_offset_value": "string",
    "origin": "web"
  }
]

Parameters

Example responses

202 Response

{
  "message": "string",
  "timestamp": "2019-08-24T14:15:22Z",
  "order_ids": [
    "497f6eca-6276-4993-bfeb-53cbbbba6f08"
  ]
}

Responses

Modify Existing Orders

PATCH /orders/bulk

See the non-bulk Modify Existing Order operation for details.

Note that you may also bulk modify orders through the CoinList Pro WebSocket Feed. This may be a better option due to the ability to keep a persistent connection open and the rate limits enforced on CoinList Pro REST endpoints.

Body parameter

[
  {
    "type": "market",
    "side": "buy",
    "size": "string",
    "price": "string",
    "stop_price": "string",
    "stop_trigger": "mark",
    "post_only": true,
    "peg_price_type": "trailing-stop",
    "peg_offset_value": "string",
    "origin": "web",
    "order_id": "93101167-9065-4b9c-b98b-5d789a3ed9fe"
  }
]

Parameters

Example responses

202 Response

{
  "message": "string",
  "timestamp": "2019-08-24T14:15:22Z",
  "order_ids": [
    "497f6eca-6276-4993-bfeb-53cbbbba6f08"
  ]
}

Responses

Cancel Specific Orders

DELETE /orders/bulk

See the non-bulk Cancel Specific Order operation for details.

Note that you may also bulk cancel orders through the CoinList Pro WebSocket Feed. This may be a better option due to the ability to keep a persistent connection open and the rate limits enforced on CoinList Pro REST endpoints.

Body parameter

[
  "497f6eca-6276-4993-bfeb-53cbbbba6f08"
]

Parameters

Example responses

202 Response

{
  "message": "string",
  "timestamp": "2019-08-24T14:15:22Z"
}

Responses

Market Data API

The CoinList Pro Market Data REST API allows public (unauthenticated) access to:

• symbol metadata
• order book snapshots and latest quotes
• current and historical auction results
• price and volume timeseries data

REST API ENDPOINT URL
https://trade-api.coinlist.co/v1

Symbols

List Symbols

GET /symbols

Get symbols and metadata for all active markets on CoinList Pro.

Example responses

200 Response

{
  "symbols": [
    {
      "symbol": "string",
      "series_code": "string",
      "index_code": "string",
      "type": "spot",
      "list_time": "2019-08-24T14:15:22Z",
      "base_currency": "string",
      "quote_currency": "string",
      "minimum_size_increment": "string",
      "minimum_price_increment": "string",
      "minimum_size": "string"
    }
  ]
}

Responses

Get Symbol Summaries

GET /symbols/summary

Get recent performance data for all active markets on CoinList Pro.

Example responses

200 Response

{
  "property1": {
    "type": "string",
    "last_price": "string",
    "lowest_ask": "string",
    "highest_bid": "string",
    "last_trade": {
      "price": "string",
      "volume": "string",
      "imbalance": "string",
      "logical_time": "2019-08-24T14:15:22Z",
      "auction_code": "string"
    },
    "volume_base_24h": "string",
    "volume_quote_24h": "string",
    "price_change_percent_24h": "string",
    "highest_price_24h": "string",
    "lowest_price_24h": "string"
  },
  "property2": {
    "type": "string",
    "last_price": "string",
    "lowest_ask": "string",
    "highest_bid": "string",
    "last_trade": {
      "price": "string",
      "volume": "string",
      "imbalance": "string",
      "logical_time": "2019-08-24T14:15:22Z",
      "auction_code": "string"
    },
    "volume_base_24h": "string",
    "volume_quote_24h": "string",
    "price_change_percent_24h": "string",
    "highest_price_24h": "string",
    "lowest_price_24h": "string"
  }
}

Responses

Response Schema

Status Code 200

Get Specific Symbol

GET /symbols/{symbol}

Get symbol metadata.

Parameters

Example responses

200 Response

{
  "symbol": "string",
  "series_code": "string",
  "index_code": "string",
  "type": "spot",
  "list_time": "2019-08-24T14:15:22Z",
  "base_currency": "string",
  "quote_currency": "string",
  "minimum_size_increment": "string",
  "minimum_price_increment": "string",
  "minimum_size": "string"
}

Responses

Get Symbol Summary

GET /symbols/{symbol}/summary

Get a summary of recent performance for a given symbol

Parameters

Example responses

200 Response

{
  "type": "string",
  "last_price": "string",
  "lowest_ask": "string",
  "highest_bid": "string",
  "last_trade": {
    "price": "string",
    "volume": "string",
    "imbalance": "string",
    "logical_time": "2019-08-24T14:15:22Z",
    "auction_code": "string"
  },
  "volume_base_24h": "string",
  "volume_quote_24h": "string",
  "price_change_percent_24h": "string",
  "highest_price_24h": "string",
  "lowest_price_24h": "string"
}

Responses

Order Books

Get Order Book (Level 2)

GET /symbols/{symbol}/book

Get the full, price-aggregated order book for a symbol.

Parameters

Example responses

200 Response

{
  "after_auction_code": "string",
  "logical_time": "2019-08-24T14:15:22Z",
  "call_time": "2019-08-24T14:15:22Z",
  "bids": [
    [
      "7216.00000000",
      "1202.3046"
    ]
  ],
  "asks": [
    [
      "7216.00000000",
      "1202.3046"
    ]
  ]
}

Responses

Get Quote (Level 1)

GET /symbols/{symbol}/quote

Get the latest quote data including last trade, best bid, and best ask

Parameters

Example responses

200 Response

{
  "last_trade": {
    "price": "string",
    "volume": "string",
    "imbalance": "string",
    "logical_time": "2019-08-24T14:15:22Z",
    "auction_code": "string"
  },
  "quote": {
    "bid": "string",
    "bid_size": "string",
    "ask": "string",
    "ask_size": "string"
  },
  "after_auction_code": "string",
  "logical_time": "2019-08-24T14:15:22Z",
  "call_time": "2019-08-24T14:15:22Z"
}

Responses

Auctions

Get Candles

GET /symbols/{symbol}/candles

Get historic price data (OHLC) for a symbol.

This method returns price data over the specified period, aggregated into intervals specified by granularity. Requests may specify both start and end time, either start or end time alone, or neither (in which case the most recent data is returned).

Indicative results are not included in candles unless the contract is currently inside an indicative auction period. Within an indicative auction period, candles will include reuslts of indicative auctions (remember, there are no fills during the indicative period) but candles before the indicative period start are temporarily unavailable.

The maximum number of intervals is 300. Requests for more data will succeed, but results are limited to the last 300 intervals based on the requested times.

Candles are returned as tuples in the form [time, open, high, low, close, volume, index_close].

Parameters

Enumerated Values

Example responses

200 Response

{
  "candles": [
    [
      "2012-01-01 01:23:45Z",
      "99.00",
      "100.00",
      "95.00",
      "96.00",
      "1000.0000",
      "96.23"
    ]
  ]
}

Responses

List Auctions

GET /symbols/{symbol}/auctions

Returns historical, complete auctions for the given symbol - in descending chronological order. Indicative auctions are not included.

Parameters

Example responses

200 Response

[
  {
    "auction_code": "string",
    "symbol": "string",
    "price": "string",
    "volume": "string",
    "imbalance": "string",
    "logical_time": "2019-08-24T14:15:22Z",
    "call_time": "2019-08-24T14:15:22Z"
  }
]

Responses

Get Auction Results

GET /symbols/{symbol}/auctions/{auction_code}

Get auction results for a specific (historical) auction.

Parameters

Example responses

200 Response

{
  "auction_code": "string",
  "symbol": "string",
  "price": "string",
  "volume": "string",
  "imbalance": "string",
  "logical_time": "2019-08-24T14:15:22Z",
  "call_time": "2019-08-24T14:15:22Z"
}

Responses

Other APIs

System

Get System Time

GET /time

Retrieve the current system time used by the API servers. This is useful for detecting clock skew between CoinList and your local system.

Example responses

200 Response

{
  "epoch": 0,
  "iso": "2019-08-24T14:15:22Z"
}

Responses

Get User Info

GET /user

Returns user info including referral stats.

Example responses

200 Response

{
  "affiliate_info": {
    "referral_count": 0,
    "referral_code": "string"
  }
}

Responses

Response Schema

Status Code 200

List Supported Assets

GET /assets

Retrieve the list of assets supported by CoinList Pro.

Example responses

200 Response

{
  "assets": [
    {
      "asset": "string",
      "is_transferable": true,
      "is_visible": true,
      "index_code": "string",
      "decimal_places": "string"
    }
  ]
}

Responses

Credits

Get trader's credits

GET /credits

Get the credits details for the current user.

Example responses

200 Response

{
  "credits": {
    "BTC": "1.00",
    "ETH": "20.00"
  },
  "tokenBalances": {
    "BTC": "1.00",
    "ETH": "20.00"
  },
  "tokenEquities": {
    "BTC": "1.00",
    "ETH": "20.00"
  },
  "tokenDiscountFactors": {
    "property1": "string",
    "property2": "string"
  },
  "equityToCreditsRatio": 0,
  "equityToCreditsStatus": "NO_CREDITS"
}

Responses

Response Schema

Status Code 200

Enumerated Values

Positions

List Positions

GET /positions

Parameters

Example responses

200 Response

{
  "positions": [
    {
      "trader_id": "b18507ce-7d55-4bf1-b12a-0ccca5b90936",
      "contract_code": "string",
      "quantity": "string",
      "marking_price": "string",
      "marking_time": "string",
      "average_entry_price": "string",
      "open_pl": "string",
      "day_closed_pl": "string",
      "day_realized_average_entry_price": "string",
      "day_realtive_closed_pl": "string",
      "day_relative_to_date": "string",
      "est_liquidation_price": "string"
    }
  ]
}

Responses

Competitions

Get Global Leaderboard

GET /leaderboard

Retrieve CoinList Trade global leaderboards.

Example responses

200 Response

{
  "pl_notional": [
    {
      "alias": "string",
      "value": "string",
      "is_real_name": true
    }
  ],
  "pl_notional_per_contract": {
    "BTC-PERP": [
      {
        "alias": "string",
        "value": "string",
        "is_real_name": true
      }
    ]
  },
  "fees_net": [
    {
      "alias": "string",
      "value": "string",
      "is_real_name": true
    }
  ]
}

Responses

Response Schema

Status Code 200

Get Affiliate Referral Code

GET /affiliate/{competition_code}

Get referral code of competition creator by competition code.

Parameters

Example responses

200 Response

{
  "affiliate_info": {
    "referral_code": "string"
  }
}

Responses

Response Schema

Status Code 200

Get Competition

GET /competition/{competition_id}

Get metadata and leaderboard for a given competition.

Parameters

Example responses

200 Response

{
  "competition": {
    "competition_id": "string",
    "label": "string",
    "created_at": "2019-08-24T14:15:22Z",
    "start_date": "2019-08-24T14:15:22Z",
    "end_date": "2019-08-24T14:15:22Z",
    "leaderboard": [
      {
        "alias": "string",
        "is_eligible": true,
        "percent_change": "string",
        "sharpe_ratio": "string",
        "trade_count": "string",
        "trade_volume": "string",
        "time_series": [
          {
            "created_at": "2019-08-24T14:15:22Z",
            "percent_change": "string"
          }
        ]
      }
    ]
  }
}

Responses

Response Schema

Status Code 200

Get Competitions

GET /accounts/{trader_id}/competitions

Get a list of competitions associated with a given trader account.

Parameters

Example responses

200 Response

{
  "competitions": [
    {
      "competition_id": "string",
      "label": "string",
      "code": "string",
      "start_date": "2019-08-24T14:15:22Z",
      "end_date": "2019-08-24T14:15:22Z"
    }
  ]
}

Responses

Join Competition

POST /accounts/{trader_id}/competitions

Join a competition using the provided competition code.

Body parameter

{
  "code": "string"
}

Parameters

Example responses

200 Response

{
  "competition": {
    "competition_id": "string",
    "label": "string",
    "code": "string",
    "start_date": "2019-08-24T14:15:22Z",
    "end_date": "2019-08-24T14:15:22Z"
  }
}

Responses

Response Schema

Status Code 200

Create Competition

POST /accounts/{trader_id}/create-competition

Create a new competition

Body parameter

{
  "label": "string",
  "code": "string",
  "slug": "string",
  "start_date": "2019-08-24T14:15:22Z",
  "end_date": "2019-08-24T14:15:22Z",
  "auto_join": true,
  "is_public": true
}

Parameters

Example responses

200 Response

{
  "competition": {
    "competition_id": "string",
    "label": "string",
    "code": "string",
    "start_date": "2019-08-24T14:15:22Z",
    "end_date": "2019-08-24T14:15:22Z"
  }
}

Responses

Response Schema

Status Code 200