NAV
Node.js Python

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:

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

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:

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:

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.

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:

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:

Header Description
x-ratelimit-limit Current request limit
x-ratelimit-remaining Requests remaining in this limit
x-ratelimit-reset UNIX timestamp (seconds) at which you'll have enough requests available to retry this request
x-ratelimit-retry-after Number of seconds to wait before retrying (only sent if rejected)

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).

Trader API

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

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

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:

The API key as a string.

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

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:

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

Status Meaning Description Schema
200 OK An object containing fee schedules by symbol Inline
default Default unexpected error Error

Response Schema

Status Code 200

Name Type Required Description
» fees_by_symbols object false none
»» additionalProperties string false none

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

Status Meaning Description Schema
200 OK An object containing an array of trading accounts Inline
default Default unexpected error Error

Response Schema

Status Code 200

Name Type Required Description
» accounts [object] false none
»» trader_id string(uuid) false The trader account id (uuid)
»» name string false The name of this trading account

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

Parameter In Type Required Description
trader_id path string(uuid) true none

Example responses

200 Response

{
  "asset_balances": {
    "BTC": "0.00308696",
    "ETH": "20.000000000000000000"
  },
  "asset_holds": {
    "BTC": "0.00000000",
    "ETH": "1.000000000000000000"
  },
  "net_liquidation_value_usd": "string"
}

Responses

Status Meaning Description Schema
200 OK A summary of the current state of this account AccountSummary
403 Forbidden Unauthorized None
default Default unexpected error Error

Get Account Alias

GET /accounts/{trader_id}/alias

Get trading account alias for a given account.

Parameters

Parameter In Type Required Description
trader_id path string(uuid) true none

Example responses

200 Response

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

Responses

Status Meaning Description Schema
200 OK Success Inline
403 Forbidden Unauthorized None
default Default unexpected error Error

Response Schema

Status Code 200

Name Type Required Description
» alias string false The trading account's alias
» is_real_name boolean false True if the user set the alias themselves; False if it was randomly assigned

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

Parameter In Type Required Description
trader_id path string(uuid) true none
body body object true none
» alias body string false The new trading account alias

Example responses

200 Response

{
  "alias": "string"
}

Responses

Status Meaning Description Schema
200 OK Success Inline
403 Forbidden Unauthorized None
default Default unexpected error Error

Response Schema

Status Code 200

Name Type Required Description
» alias string false The new trading account alias

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

Parameter In Type Required Description
trader_id path string(uuid) true none
start_time query string(date-time) false Start date-time for results (inclusive; filter on created_at)
end_time query string(date-time) false End date-time for results (inclusive; filter on created_at)
descending query boolean false If true, sort newest results first (default false)
count query integer false Maximum item count per page (default 200; max 500)

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

Status Meaning Description Schema
200 OK An object containing an array of transactions. TransactionHistory
403 Forbidden Unauthorized None
default Default unexpected error Error

Get CoinList Wallets

GET /accounts/{trader_id}/wallets

Get the account's CoinList wallets and balances.

Parameters

Parameter In Type Required Description
trader_id path string(uuid) true none
token_code query string false Token code to get wallet balance for

Example responses

200 Response

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

Responses

Status Meaning Description Schema
200 OK An object containing an array of wallet records. Inline
400 Bad Request Bad Request Error
default Default unexpected error Error

Response Schema

Status Code 200

Name Type Required Description
anonymous [Wallet] false none
» Wallet Wallet false none
»» asset string false The identifier for the wallet's asset on CoinList Pro (e.g. BTC)
»» balance string(decimal) false The the available balance of the wallet

Get CoinList Wallet Ledger

GET /accounts/{trader_id}/wallet-ledger

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

Parameters

Parameter In Type Required Description
trader_id path string(uuid) true none
asset query string true Asset to list transactions for
count query integer false Maximum item count per page (default 200; max 500)
page query integer false The page of items to list (default 1)

Example responses

200 Response

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

Responses

Status Meaning Description Schema
200 OK An object containing an array of wallet transactions. Inline
400 Bad Request Bad Request Error
default Default unexpected error Error

Response Schema

Status Code 200

Name Type Required Description
anonymous [WalletLedgerEntry] false none
» WalletLedgerEntry WalletLedgerEntry false none
»» id string(uuid) false The identifier for the ledger entry.
»» description string false A description of the transaction.
»» asset string false The asset whose balance is affected by the transaction. (ex. BTC)
»» amount string(decimal) false The value of the transaction (balance delta).
»» created_at string(date-time) false The time the transaction was initiated.

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

Parameter In Type Required Description
trader_id path string(uuid) true none
format query string false none

Enumerated Values

Parameter Value
format json
format csv

Example responses

200 Response

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

Responses

Status Meaning Description Schema
200 OK An object containing an array of daily transaction summaries. DailyTransactionHistory
400 Bad Request Bad Request Error
default Default unexpected error Error

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

Status Meaning Description Schema
200 OK An object containing an array of keys Inline
default Default unexpected error Error

Response Schema

Status Code 200

Name Type Required Description
» api_keys object false none
»» key string(uuid) false The API key
»» read boolean false Can this API key read private account data?
»» write boolean false Can this API key insert / modify orders?
»» transfer boolean false Can this API key transfer / withdraw funds?

Create API Key

POST /keys

Mint a new API key.

Body parameter

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

Parameters

Parameter In Type Required Description
body body object true API key options
» read body boolean true Can this API key read private account data?
» write body boolean true Can this API key insert / modify orders?
» transfer body boolean true Can this API key transfer / withdraw funds?

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

Status Meaning Description Schema
200 OK New API key pair ApiKeyPair
default Default unexpected error Error

Delete API Key

DELETE /keys/{key}

Revoke an existing API key.

Parameters

Parameter In Type Required Description
key path string(uuid) true none

Example responses

200 Response

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

Responses

Status Meaning Description Schema
200 OK Key revocation result Inline
default Default unexpected error Error

Response Schema

Status Code 200

Name Type Required Description
» message string false Key revoked message
» key string(uuid) false Deleted API key

Fills

List Fills

GET /fills

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

Parameters

Parameter In Type Required Description
symbol query string false symbol to list fills for
order_id query string(uuid) false order to list fills for
start_time query string(date-time) false Start date-time for results (inclusive; filter on logical_time)
end_time query string(date-time) false End date-time for results (inclusive; filter on logical_time)
descending query boolean false If true, sort newest results first (default false)
count query integer false Maximum item count per page (default 200; max 500)

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

Status Meaning Description Schema
200 OK An object containing an array of fills Fills
default Default unexpected error Error

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

Parameter In Type Required Description
symbol query string false Symbol to list orders for
status query string false Order status to filter by
start_time query string(date-time) false Start date-time for results (inclusive; filter on epoch_timestamp)
end_time query string(date-time) false End date-time for results (inclusive; filter on epoch_timestamp)
descending query boolean false If true, sort newest results first (default false)
count query integer false Maximum item count per page (default 200; max 500)

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": "last",
      "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

Status Meaning Description Schema
200 OK An object containing an array of orders Orders
default Default unexpected error Error

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": "last",
  "self_trade_prevention": "keep-newest",
  "post_only": true,
  "peg_price_type": "trailing-stop",
  "peg_offset_value": "string",
  "origin": "web"
}

Parameters

Parameter In Type Required Description
body body NewOrder true The order to create

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": "last",
    "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

Status Meaning Description Schema
202 Accepted New order request received NewOrderRequestReceived
default Default unexpected error Error

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

Parameter In Type Required Description
symbol query string false Symbol to cancel orders for

Example responses

202 Response

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

Responses

Status Meaning Description Schema
202 Accepted Request received message RequestReceived
default Default unexpected error Error

Get Specific Order (by id)

GET /orders/{order_id}

Parameters

Parameter In Type Required Description
order_id path string(uuid) true Order to retrieve

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": "last",
  "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

Status Meaning Description Schema
200 OK An order Order
default Default unexpected error Error

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": "last",
  "post_only": true,
  "peg_price_type": "trailing-stop",
  "peg_offset_value": "string",
  "origin": "web"
}

Parameters

Parameter In Type Required Description
order_id path string(uuid) true Order to modify
body body ModifiedOrder true Order fields to modify

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": "last",
    "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

Status Meaning Description Schema
202 Accepted Modify order request received NewOrderRequestReceived
default Default unexpected error Error

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

Parameter In Type Required Description
order_id path string(uuid) true Order to cancel

Example responses

202 Response

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

Responses

Status Meaning Description Schema
202 Accepted Request received message RequestReceived
default Default unexpected error Error

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

Parameter In Type Required Description
body body object true none
» timeout body integer true Requested timeout in milliseconds (or 0 to cancel timer)

Example responses

default Response

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

Responses

Status Meaning Description Schema
200 OK OK None
default Default unexpected error Error

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

Parameter In Type Required Description
count query integer false Maximum item count per page (default 200; max 500)

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

Status Meaning Description Schema
200 OK An object containing an array of report requests Inline
default Default unexpected error Error

Response Schema

Status Code 200

Name Type Required Description
» reports object false none
»» report_id string(uuid) false The unique id of the report request
»» created_at string(date-time) false Creation time of the report request
»» expires_at string(date-time) false After this time, the report URL will no longer be accessible
»» report_type string false Type of report requested (can be either account or fills)
»» params object false Report-specific collection of parameters
»» state string false Current status of this request
»» url string false Preauthed link to the report

Enumerated Values

Property Value
report_type account
report_type fills
state pending
state working
state ready

Request Report

POST /reports

Request a new fills or account report (CSV)

Body parameter

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

Parameters

Parameter In Type Required Description
body body object true Report parameters
» report_type body string true Type of report requested (can be either account or fills)
» params body object true Report-specific collection of parameters

Enumerated Values

Parameter Value
» report_type account
» report_type fills

Example responses

202 Response

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

Responses

Status Meaning Description Schema
202 Accepted New report request Inline
default Default unexpected error Error

Response Schema

Status Code 202

Name Type Required Description
» report_id string(uuid) true The unique id of the report request

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"
  },
  "net_liquidation_value_usd": "string"
}

Responses

Status Meaning Description Schema
200 OK An object containing balance details Balances
default Default unexpected error Error

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

Parameter In Type Required Description
start_time query string(date-time) false Start date-time for results (inclusive; filter on created_at)
end_time query string(date-time) false End date-time for results (inclusive; filter on created_at)
descending query boolean false If true, sort newest results first (default false)
count query integer false Maximum item count per page (default 200; max 500)

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

Status Meaning Description Schema
200 OK An object containing an array of transfers. TransferHistory
403 Forbidden Unauthorized None
default Default unexpected error Error

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

Parameter In Type Required Description
body body transferToWalletBody true none
» asset body string false The asset to transfer (e.g. BTC)
» amount body string(decimal) false The value of the transfer (in quantity)

Example responses

200 Response

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

Responses

Status Meaning Description Schema
200 OK Transfer request processed Inline
400 Bad Request Transfer request denied Error
403 Forbidden Unauthorized None
default Default unexpected error Error

Response Schema

Status Code 200

Name Type Required Description
» transfer_id string(uuid) false The transfer id of the new request

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

Parameter In Type Required Description
body body transferToWalletBody true none
» asset body string false The asset to transfer (e.g. BTC)
» amount body string(decimal) false The value of the transfer (in quantity)

Example responses

200 Response

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

Responses

Status Meaning Description Schema
200 OK Transfer request processed Inline
400 Bad Request Transfer request denied Error
403 Forbidden Unauthorized None
default Default unexpected error Error

Response Schema

Status Code 200

Name Type Required Description
» transfer_id string(uuid) false The transfer id of the new request

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": "1f494ace-b3ed-4324-b202-55526ed06381",
  "to_trader_id": "d32c7a40-cc24-44b0-8597-f9edb3da989f",
  "asset": "string",
  "amount": "string"
}

Parameters

Parameter In Type Required Description
body body object true none
» from_trader_id body string(uuid) false The source trader account id (uuid)
» to_trader_id body string(uuid) false The destination trader account id (uuid)
» asset body string false The asset to transfer (ex. BTC)
» amount body string(decimal) false The value of the transfer (in quantity)

Example responses

400 Response

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

Responses

Status Meaning Description Schema
200 OK Transfer request processed None
400 Bad Request Transfer request denied Error
403 Forbidden Unauthorized None
default Default unexpected error Error

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

Parameter In Type Required Description
body body object true none
» asset body string true The asset to withdraw. (e.g. BTC)
» amount body string(decimal) true The value of the withdrawal (in quantity).
» destination_address body string false The blockchain address to withdraw to.

Example responses

200 Response

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

Responses

Status Meaning Description Schema
200 OK Withdrawal request received Inline
400 Bad Request Withdrawal request denied Error
403 Forbidden Unauthorized None
default Default unexpected error Error

Response Schema

Status Code 200

Name Type Required Description
» transfer_id string(uuid) false The transfer id of the new request

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": "last",
    "self_trade_prevention": "keep-newest",
    "post_only": true,
    "peg_price_type": "trailing-stop",
    "peg_offset_value": "string",
    "origin": "web"
  }
]

Parameters

Parameter In Type Required Description
body body array[object] true Orders to create

Example responses

202 Response

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

Responses

Status Meaning Description Schema
202 Accepted New order requests received NewOrderRequestsReceived
default Default unexpected error Error

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": "last",
    "post_only": true,
    "peg_price_type": "trailing-stop",
    "peg_offset_value": "string",
    "origin": "web",
    "order_id": "93101167-9065-4b9c-b98b-5d789a3ed9fe"
  }
]

Parameters

Parameter In Type Required Description
body body array[any] true Order modifications

Example responses

202 Response

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

Responses

Status Meaning Description Schema
202 Accepted Modify order request received NewOrderRequestsReceived
default Default unexpected error Error

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

Parameter In Type Required Description
body body array[string] true Orders to cancel

Example responses

202 Response

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

Responses

Status Meaning Description Schema
202 Accepted Request received message RequestReceived
default Default unexpected error Error

Market Data API

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

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

Status Meaning Description Schema
200 OK An object containing an array of symbol metadata Symbols
default Default unexpected error Error

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

Status Meaning Description Schema
200 OK An object containing all active symbols' recent performance Inline
default Default unexpected error Error

Response Schema

Status Code 200

Name Type Required Description
» SymbolSummary SymbolSummary false none
»» type string false none
»» last_price string(decimal) false none
»» lowest_ask string(decimal) false none
»» highest_bid string(decimal) false none
»» last_trade object false Info about the latest auction with volume
»»» price string(decimal) false The price of the last auction with volume
»»» volume string(decimal) false The quantity crossed in the last auction with volume
»»» imbalance string(decimal) false The quantity leftover that would have crossed in the auction had there have been quantity available on the other side.
»»» logical_time string(date-time) false The logical time of the last auction with volume
»»» auction_code string false The auction code of the last auction with volume
»» volume_base_24h string(decimal) false 24h rolling volume (in base currency; same unit as the symbol's size or quantity)
»» volume_quote_24h string(decimal) false 24h rolling volume (in quote currency; same unit as the symbol's price)
»» price_change_percent_24h string(decimal) false none
»» highest_price_24h string(decimal) false none
»» lowest_price_24h string(decimal) false none

Get Specific Symbol

GET /symbols/{symbol}

Get symbol metadata.

Parameters

Parameter In Type Required Description
symbol path string true none

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

Status Meaning Description Schema
200 OK A symbol Symbol
default Default unexpected error Error

Get Market Summary

GET /symbols/{symbol}/summary

Get a summary of recent market performance for a given symbol

Parameters

Parameter In Type Required Description
symbol path string true none

Example responses

200 Response

{
  "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"
}

Responses

Status Meaning Description Schema
200 OK The market's recent performance MarketSummary
default Default unexpected error Error

Order Books

Get Order Book (Level 2)

GET /symbols/{symbol}/book

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

Parameters

Parameter In Type Required Description
symbol path string true none

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

Status Meaning Description Schema
200 OK The latest order book snapshot Book
default Default unexpected error Error

Get Quote (Level 1)

GET /symbols/{symbol}/quote

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

Parameters

Parameter In Type Required Description
symbol path string true none

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

Status Meaning Description Schema
200 OK The symbol's latest last trade and quote information Quote
default Default unexpected error Error

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

Parameter In Type Required Description
symbol path string true none
field_name query string false none
start_time query string(date-time) false none
end_time query string(date-time) false none
granularity query string false none
format query string false none

Enumerated Values

Parameter Value
field_name price
field_name index_price
field_name fair_price
field_name mark_price
field_name best_ask
field_name best_bid
granularity 1m
granularity 5m
granularity 30m
format json
format csv

Example responses

200 Response

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

Responses

Status Meaning Description Schema
200 OK Aggregated OHLC data for the symbol Candles
default Default unexpected error Error

List Auctions

GET /symbols/{symbol}/auctions

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

Parameters

Parameter In Type Required Description
symbol path string true The symbol to list auctions for
min_volume query string(decimal) false Return auctions with greater than or equal to this trade volume
start_time query string(date-time) false Start date-time for results (inclusive; filter on logical_time)
end_time query string(date-time) false End date-time for results (inclusive; filter on logical_time)
descending query boolean false If true, sort newest results first (default false)
count query integer false Maximum item count per page (default 200; max 500)

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

Status Meaning Description Schema
200 OK A list of auctions Auctions
default Default unexpected error Error

Get Auction Results

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

Get auction results for a specific (historical) auction.

Parameters

Parameter In Type Required Description
auction_code path string true none

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

Status Meaning Description Schema
200 OK An auction Auction
default Default unexpected error Error

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

Status Meaning Description Schema
200 OK the current system time Time
default Default unexpected error Error

Get User Info

GET /user

Returns user info including referral stats.

Example responses

200 Response

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

Responses

Status Meaning Description Schema
200 OK User account info. Inline
default Default unexpected error Error

Response Schema

Status Code 200

Name Type Required Description
» affiliate_info object false none
»» referral_count integer false Number of users that have registered using your referral code.
»» referral_code string false Your unique referral code.

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

Status Meaning Description Schema
200 OK assets supported Assets
default Default unexpected error Error

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

Status Meaning Description Schema
200 OK An object containing the details of the credits Inline
default Default unexpected error Error

Response Schema

Status Code 200

Name Type Required Description
» credits object false The trader's credit.
»» additionalProperties string false none
» tokenBalances object false The trader's token balances.
»» additionalProperties string false none
» tokenEquities object false The trader's token equity.
»» additionalProperties string false none
» tokenDiscountFactors object false The discount used for calculte trader's equity value
»» additionalProperties string false none
» equityToCreditsRatio number false The trader's overall equity-to-credit ratio.
» equityToCreditsStatus string false The status of trader's credit.

Enumerated Values

Property Value
equityToCreditsStatus NO_CREDITS
equityToCreditsStatus OK
equityToCreditsStatus NEAR_LIMIT
equityToCreditsStatus OVER_LEVERAGED

Positions

List Positions

GET /positions

Parameters

Parameter In Type Required Description
contract_code query string false contract to list positions for

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"
    }
  ]
}

Responses

Status Meaning Description Schema
200 OK An object containing an array of positions Positions
default Default unexpected error Error

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

Status Meaning Description Schema
200 OK A collection of various global leaderboards. Inline
default Default unexpected error Error

Response Schema

Status Code 200

Name Type Required Description
» pl_notional [object] false none
»» alias string false Trading account alias
»» value string(decimal) false Metric value
»» is_real_name boolean false True if the user set the alias themselves; False if it was randomly assigned
» pl_notional_per_contract object false A list of accounts per active contract in order of highest P&L change in that contract (in notional value) to smallest
»» BTC-PERP [object] false none
» fees_net [object] false none

Get Affiliate Referral Code

GET /affiliate/{competition_code}

Get referral code of competition creator by competition code.

Parameters

Parameter In Type Required Description
competition_code path string true none

Example responses

200 Response

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

Responses

Status Meaning Description Schema
200 OK Affiliate referral code associated with this competition's creator. Inline
404 Not Found Competition not found None
default Default unexpected error Error

Response Schema

Status Code 200

Name Type Required Description
» affiliate_info object false none
»» referral_code string false Competition creator's affiliate referral code.

Get Competition

GET /competition/{competition_id}

Get metadata and leaderboard for a given competition.

Parameters

Parameter In Type Required Description
competition_id path string true none
contract_code query string false none

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

Status Meaning Description Schema
200 OK Metadata and leaderboard for this competition. Inline
404 Not Found Competition id not found None
default Default unexpected error Error

Response Schema

Status Code 200

Name Type Required Description
» competition Competition false none
»» competition_id string false An identifier which uniquely identifies this Competition
»» label string false Given name for the competition
»» created_at string(date-time) false Date and time the competition was created
»» start_date string(date-time) false Date and time the competition will begin or has begun
»» end_date string(date-time) false Date and time the competition will end or has ended
»» leaderboard [CompetitionRankLevel] false List of accounts participating in this competition in order of highest percent change to net liquidation value to smallest
»»» AccountRankLevel CompetitionRankLevel false none
»»»» alias string false Trading account alias
»»»» is_eligible boolean false True if the trader is eligible to place on the leaderboard
»»»» percent_change string(decimal) false Percentage change in the total value of the account (balance + unrealized profit) since the trader joined the competition
»»»» sharpe_ratio string(decimal) false Sharpe ratio of the trader's percent change in the total value of the account since the trader joined the competition
»»»» trade_count string(decimal) false Number of trades made by the account since the trader joined the competition
»»»» trade_volume string(decimal) false Total trade volume of the account since the trader joined the competition
»»»» time_series [object] false Set of percent changes in the total value of the account since the trader joined the competition, taken 5 minutes apart
»»»»» created_at string(date-time) false Effective date and time of the percent change in the total value of the account since the trader joined the competition
»»»»» percent_change string(decimal) false Percentage change in the total value of the account since the trader joined the competition

Get Competitions

GET /accounts/{trader_id}/competitions

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

Parameters

Parameter In Type Required Description
trader_id path string(uuid) true none

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

Status Meaning Description Schema
200 OK Success CompetitionsList
403 Forbidden Unauthorized None
default Default unexpected error Error

Join Competition

POST /accounts/{trader_id}/competitions

Join a competition using the provided competition code.

Body parameter

{
  "code": "string"
}

Parameters

Parameter In Type Required Description
trader_id path string(uuid) true none
body body object true none
» code body string false Competition code

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

Status Meaning Description Schema
200 OK Success Inline
403 Forbidden Unauthorized None
404 Not Found Competition code not found None
default Default unexpected error Error

Response Schema

Status Code 200

Name Type Required Description
» competition CompetitionSummary false none
»» competition_id string false An identifier which uniquely identifies this Competition
»» label string false Given name for the competition
»» code string false A unique code that can be used to join this competition as a participant.
»» start_date string(date-time) false Date and time the competition will begin or has begun
»» end_date string(date-time) false Date and time the competition will end or has ended

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

Parameter In Type Required Description
trader_id path string(uuid) true none
body body object true none
» label body string false Competition name
» code body string false Competition join code
» slug body string false Competition URL slug (ex. /competition/{your_slug})
» start_date body string(date-time) false Competition start date
» end_date body string(date-time) false Competition end date
» auto_join body boolean false none
» is_public body boolean false Set to true to permit public listing of this competition and to allow any trader to join this competition without an invite link

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

Status Meaning Description Schema
200 OK Success Inline
403 Forbidden Unauthorized None
default Default unexpected error Error

Response Schema

Status Code 200

Name Type Required Description
» competition CompetitionSummary false none
»» competition_id string false An identifier which uniquely identifies this Competition
»» label string false Given name for the competition
»» code string false A unique code that can be used to join this competition as a participant.
»» start_date string(date-time) false Date and time the competition will begin or has begun
»» end_date string(date-time) false Date and time the competition will end or has ended

WebSocket Feed

The CoinList Pro WebSocket feed provides real-time order, fill, balance, and market data updates. All messages sent and received over the socket will be in JSON format and follow a standard schema. Messages will always contain a type property and the channel or channels they are applicable to. They may also contain the symbol or symbols that they pertain to. Trading is also possible through the WebSocket API.

WebSocket connections and upstream messages (subscriptions and trading operations) are rate limited as described in the Rate Limits section above.

WEBSOCKETS FEED URL
wss://trade-api.coinlist.co

Subscriptions

You can subscribe and unsubscribe from channels (with options to listen for changes only to specific symbols - or to listen for updates to all symbols) by sending subscription messages to the socket. After processing any subscription or un-subscription requests, we'll send a message with type subscriptions giving you a list of your current subscriptions.

Subscription messages consume from your request limit as described in the Rate Limits section above.

Subscribe

Subscribe (specific symbols)

{
    "type": "subscribe",
    "symbols": ["BTC-USD"],
    "channels": ["auctions"]
}

Subscribe (all symbols; authenticated)

{
    "type": "subscribe",
    "symbols": [],
    "channels": ["orders"],
    "key": "...",
    "sig": "...",
    "timestamp": "..."
}

Unsubscribe (all symbols)

{
    "type": "unsubscribe",
    "symbols": [],
    "channels": ["orders"]
}

To subscribe to a channel, send a message with type subscribe, per the example here. If the channel is private, you'll need to send authentication fields per the Authentication section below.

To subscribe to all symbols, leave the symbols list empty.

Unsubscribe

To unsubscribe from a channel, send the same message with type unsubscribe. To unsubscribe from all symbols, send an empty list. To unsubscribe from all channels, send an empty list.

Authentication (Private)

Private (authenticated) channels require a signed subscribe message. To subscribe to a private channel, send the subscribe message as usual, but also pass in key, sig, and timestamp fields as if you were signing a request (with empty body) to GET /v1/user/verify.

You may also authenticate by signing the initial HTTP upgrade request in the same manner you would sign other REST calls as described here. If you do this, you do not need to send any auth fields in your messages.

Note that any failed authentication attempts will close the socket.

Socket Health

Example message

{
  channel: "heartbeat",
  time: "2018-09-19T19:57:41.105Z"
}

Per the WebSocket standard, the CoinList Pro WebSocket API Gateway use the ping/pong opcodes to detected a dropped connection. We will send a ping opcode periodically to each open WebSocket connection to check to see if it is still alive. If we do not receive a pong opcode before the next check period, we will close the connection.

In addition to the transport-level check, we will send a message on the heartbeat channel every 3 seconds. A client can use a drop in heartbeat messages to signify a lost connection.

Channels

The following list of channels are available for subscription:

ticker Channel

Example messages

{
  channel: "ticker",
  type: "snapshot",
  data: {
    symbol: "BTC-USD",
    last_trade: {
      price: "7500.25",
      volume: "12.5478",
      imbalance: "-2.0000",
      logical_time: "2018-08-31T07:26:31.000Z",
      auction_code: "BTC-USD-2018-08-31T07:26:31.000Z"
    },
    quote: {
      ask: "7500.24",
      ask_size: "122.1218",
      bid: "7500.23",
      bid_size: "143.2843"
    },
    fair_price: "7500.23",
    index_price: "7500.50",
    dollarizer: "1.00000000",
    is_indicative: false,
    call_time: "2018-08-31T07:26:37.050Z",
    logical_time: "2018-08-31T07:26:37.000Z",
    after_auction_code: "BTC-USD-2018-08-31T07:26:37.000Z"
  }
}

{
  channel: "ticker",
  type: "update",
  data: {
    symbol: "BTC-USD",
    last_trade: {
      price: "7500.25",
      volume: "12.5478",
      imbalance: "-2.0000",
      logical_time: "2018-08-31T07:26:31.000Z",
      auction_code: "BTC-USD-2018-08-31T07:26:31.000Z"
    },
    quote: {
      ask: "7500.24",
      ask_size: "122.1218",
      bid: "7500.23",
      bid_size: "143.2843"
    },
    fair_price: "7500.23",
    index_price: "7500.50",
    dollarizer: "1.00000000",
    is_indicative: false,
    call_time: "2018-08-31T07:26:37.050Z",
    logical_time: "2018-08-31T07:26:37.000Z",
    after_auction_code: "BTC-USD-2018-08-31T07:26:37.000Z"
  }
}

{
  channel: "ticker",
  type: "update",
  data: {
    symbol: "BTC-USD",
    last_trade: {
      price: "7500.25",
      volume: "12.5478",
      imbalance: "-2.0000",
      logical_time: "2018-08-31T07:26:31.000Z",
      auction_code: "BTC-USD-2018-08-31T07:26:31.000Z"
    },
    quote: {
      ask: "7500.24",
      ask_size: "122.1218",
      bid: "7505.23",
      bid_size: "143.2843"
    },
    fair_price: "7502.74",
    index_price: "7500.50",
    dollarizer: "1.00000000",
    is_indicative: true,
    indicative_price: "7501.75",
    indicative_volume: "2.2198",
    call_time: "2018-08-31T07:26:37.050Z",
    logical_time: "2018-08-31T07:26:37.000Z",
    after_auction_code: "BTC-USD-2018-08-31T07:26:37.000Z"
  }
}

The ticker channel notifies you of every new auction price and quote update for CoinList Pro symbols using our frequent batch auction matching engine.

During a market's indicative period, ticker messages will include is_indicative inside the data object. Prices and quotes will be updated, but last_trade will not be updated during an indicative period as there are no crosses. Instead, an indicative_price and indicative_volume will be included. Note, if there is an indicative_price, it means the book is crossed and thus bid >= ask.

After subscribing to the channel, you'll receive a message of type snapshot that contains last_trade data including price, volume (in quantity), and time as well as quote data including best bid, best ask, and sizes. You'll also receive the latest fair price and index price. Upon subsequent auctions or trades occurring in the market, you'll receive messages of type update to notify you of the new last trade, quote, and price data. The snapshot and update messages will always contain the same properties.

level2 Channel

Example messages

{
  channel: "level2",
  type: "snapshot",
  data: {
    symbol: "BTC-USD",
    bids: [[ "7500.00", "100.2341" ], [ "7500.01", "56.2151" ], ...],
    asks: [[ "7500.02", "12.4372" ], [ "7500.03", "32.1839" ], ...]
  }
}

{
  channel: "level2",
  type: "update",
  data: {
    symbol: "BTC-USD",
    after_auction_code: "BTC-USD-2018-09-03T19:57:41.000Z",
    changes: [
      [ "bid", "7500.00", "75.2341" ],
      [ "ask", "7500.02", "13.9372" ],
      [ "ask", "7500.03", "0" ]
    ]
  }
}

The level2 channel lets you keep up-to-date with the latest order book for a market.

After subscribing, you will receive a message of type snapshot that contains the entire order book including symbol, levels of bids (with [price, size] tuples), and levels of asks.

Subsequent updates will be of type update and contain a changes property that is an array of updated levels. Each element of the array is a [side, price, size] tuple where side is either bid or ask. Note that size is not a delta, it's the new size at that price level. A size of "0" indicates that the level is now empty and should be removed.

Note that you may receive another snapshot message containing the entire book at that time. After any snapshot, subsequent update messages will be deltas from the latest snapshot.

Note that during a market's indicative period, the book distributed over the level2 channel may be crossed.

auctions Channel

Example messages

{
  channel: "auctions",
  type: "complete",
  data: {
    symbol: "BTC-USD",
    auction_code: "BTC-USD-2019-01-16T05",
    price: "121.10",
    fairPrice: "121.12",
    indexPrice: "121.25",
    volume: "59.7337"
    call_time: "2019-01-16T05:57:47.113Z",
    logical_time: "2019-01-16T05:57:47.000Z"
  }
}

{
  channel: "auctions",
  type: "indicative",
  data: {
    symbol: "BTC-USD",
    auction_code: "BTC-USD-2019-01-16T05",
    price: "121.10",
    fairPrice: "121.12",
    indexPrice: "121.25",
    volume: "59.7337"
    call_time: "2019-01-16T05:57:47.113Z",
    logical_time: "2019-01-16T05:57:47.000Z"
  }
}

The auctions channel includes all auction results including price, volume, and imbalance. The message also includes the logical_time of the auction, which is the cutoff time for order timestamps to be included in the batch - and the call_time of the auction, which is the wall clock time that the auction was computed and market data was disseminated.

Note that type may be complete for regular auctions or indicative in the case of auctions during a market's indicative period.

orders Channel

Example messages

{
  channel: "orders",
  type: "snapshot",
  data: [
    {
      status: "accepted",
      symbol: "BTC-USD",
      order_id: "af8d7247-3b34-4a0d-bc15-12c9e706211c",
      type: "limit",
      side: "buy",
      size: "1.0000",
      size_filled: "0.0000",
      price: "7000.00",
      created_at: "2018-09-05T19:27:17.328Z",
      epoch_timestamp: "2018-09-05T19:27:17.328Z",
      origin: "web"
    },
    ...
  ]
}

{
  channel: "orders",
  type: "update"
  action: "received",
  data: {
    timestamp: "2018-08-03T16:24:07.249Z",
    symbol: "BTC-USD",
    order_id: "aac4e2f9-4998-4f4c-9c39-2124cef09bea",
    client_id: "My Order #5",
    type: "market",
    side: "buy",
    size: "43.2498",
    origin: "web"
  }
}

{
  channel: "orders",
  type: "update",
  action: "rejected",
  data: {
    status: "rejected",
    symbol: "BTC-USD",
    order_id: "72ca03a9-f9c2-4232-8220-e449523d3d1a",
    client_id: "My Order #6",
    type: "limit",
    side: "sell",
    size: "15.0000",
    price: "7529.39",
    message: "hold rejected due to lack of funds (new total hold of 100000.00 larger than available balance of 89824.00)",
    message_code: "ORDER_REJECT_FUNDS_LIMIT"
  }
}

{
  channel: "orders",
  type: "update",
  action: "accepted",
  data: {
    status: "accepted",
    symbol: "BTC-USD",
    order_id: "72ca03a9-f9c2-4232-8220-e449523d3d1a",
    client_id: "My Order #6",
    type: "limit",
    timestamp: "2018-09-03T19:57:41.000Z",
    epoch_timestamp: "2018-09-03T19:57:41.105Z",
    side: "sell",
    size: "15.0000",
    price: "7529.39",
    origin: "web"
  }
}

{
  channel: "orders",
  type: "update",
  action: "canceled",
  data: {
    status: "canceled",
    timestamp: "2018-09-06T22:25:20.000",
    epoch_timestamp: "2018-09-06T22:25:20.934Z",
    symbol: "BTC-USD",
    order_id: "72ca03a9-f9c2-4232-8220-e449523d3d1a",
    client_id: "My Order #6",
    type: "limit",
    side: "sell",
    size: "15.0000",
    size_filled: "7.5000",
    fill_fees: "1.25",
    price: "7529.39",
    origin: "web"
  }
}

{
  channel: "orders",
  type: "update",
  action: "cancel-rejected",
  data: {
    timestamp: "2018-09-06T22:25:20.934Z",
    order_id: "2604ee5a-695a-47c8-ba9d-c62e1c821b9c",
    message: "cancelation failed due to permissions or order status",
    message_code: "ORDER_REJECT_BAD_STATUS"
  }
}

{
  channel: "orders",
  type: "update",
  action: "filled",
  data: {
    status: "accepted",
    timestamp: "2018-09-03T19:57:41.000Z",
    epoch_timestamp: "2018-09-03T19:57:41.105Z",
    symbol: "BTC-USD",
    order_id: "06d9f411-f4b9-42f9-a239-9a8fb4b65c65",
    client_id: "My Order #7",
    type: "limit",
    side: "buy",
    price: "7000.00",
    size: "1.0000",
    size_filled: "0.5000",
    size_filled_delta: "0.5000",
    fill_price: "7000.00",
    fill_fees: "1.25",
    fill_fees_delta: "1.25",
    fee_type: "taker",
    average_fill_price: "7000.00",
    auction_code: "BTC-USD-2018-09-03T19:57:40.750Z",
    origin: "web"
  }
}

{
  channel: "orders",
  type: "update",
  action: "filled",
  data: {
    status: "done",
    timestamp: "2018-09-03T19:57:42.105Z",
    epoch_timestamp: "2018-09-03T19:57:41.105Z",
    symbol: "BTC-USD",
    order_id: "06d9f411-f4b9-42f9-a239-9a8fb4b65c65",
    client_id: "My Order #7",
    type: "limit",
    side: "buy",
    price: "7000.00",
    size: "1.0000",
    size_filled: "1.0000",
    size_filled_delta: "0.5000",
    fill_price: "7000.00",
    fill_fees: "2.50",
    fill_fees_delta: "1.25",
    fee_type: "taker",
    average_fill_price: "7000.00",
    auction_code: "BTC-USD-2018-09-03T19:57:41.000Z",
    origin: "web"
  }
}

{
  channel: "orders",
  type: "update",
  action: "triggered",
  data: {
    status: "accepted",
    timestamp: "2018-09-03T19:57:42.105Z",
    epoch_timestamp: "2018-09-03T19:57:42.405Z",
    symbol: "BTC-USD",
    order_id: "06d9f411-f4b9-42f9-a239-9a8fb4b65c65",
    client_id: "My Order #7",
    type: "market",
    side: "buy",
    size: "1.0000",
    origin: "web"
  }
}

The orders channel includes all state changes for a user's order set.

After subscribing to the channel, you'll receive a message of type snapshot that contains the latest status of each of the user's active orders. Upon subsequent order state changes (fills, cancellations, other status updates), you'll receive messages of type update to notify you of the new state.

Upon posting a new order (through REST API endpoint POST /orders), you will receive a message with action: received. This message will let you know the timestamp the CoinList Pro API gateway received your order (and will include a clientId, if one was supplied during order creation).

The timestamp supplied in messages across the orders channel will be the timestamp of the state change being reported. In the snapshot messages, the created_at time is the time the order first hit the CoinList Pro API gateway. That same timestamp would have been reported on the original action: "received" message.

Possible values for action:

balances Channel

Example messages

{
  channel: "balances",
  type: "snapshot",
  data: {
    asset_balances: {
      BTC: "10.000000"
    },
    asset_holds: {
      BTC: "1.000000"
    },
    net_liquidation_value_usd: "105237.526764"
  }
}

{
  channel: "balances",
  type: "update",
  data: {
    asset_balances: {
      BTC: "10.000000"
    },
    asset_holds: {
      BTC: "1.000000"
    },
    net_liquidation_value_usd: "105237.526764"
  }
}

The balances channel includes notifications for updated balances in your trading accounts including:

Descriptions of the various balance fields:

transfers Channel

Example messages

{
  channel: "transfers",
  type: "update",
  action: "requested",
  data: {
    trader_id: "af8d7247-3b34-4a0d-bc15-12c9e706211c",
    transfer_id: "72ca03a9-f9c2-4232-8220-e449523d3d1a",
    asset: "BTC",
    delta: "10.000000"
  }
}

{
  channel: "transfers",
  type: "update",
  action: "completed",
  data: {
    trader_id: "af8d7247-3b34-4a0d-bc15-12c9e706211c",
    transfer_id: "72ca03a9-f9c2-4232-8220-e449523d3d1a",
    transaction_id: "2604ee5a-695a-47c8-ba9d-c62e1c821b9c",
    asset: "BTC",
    delta: "10.000000"
  }
}

{
  channel: "transfers",
  type: "update",
  action: "canceled",
  data: {
    trader_id: "af8d7247-3b34-4a0d-bc15-12c9e706211c",
    transfer_id: "72ca03a9-f9c2-4232-8220-e449523d3d1a",
  }
}

The transfers channel includes notifications for requested, completed, and canceled deposits and withdrawals. Check the sign of the delta field to determine if the transfer is a deposit (positive) or a withdrawal (negative).

notifications Channel

Example messages

{
  channel: "notifications",
  type: "snapshot",
  data: [
    {
      trader_id: "40fb2b0a-c4eb-44cb-97b2-229af16b8b4a",
      notification_id: "bc4faa16-f58a-4de9-af86-d534300a4b02",
      notification_type: "order",
      action: "filled",
      timestamp: "2019-07-15T18:20:08.000Z",
      details: {
        symbol: "BTC-USD",
        order_id: "988ff946-d71e-46ea-a5f3-7e3a77492aa7",
        cost: "10800.50000000",
        price: "11340.50",
        side: "buy",
        size: "1.0000",
        size_filled: "1.0000",
        type: "market"
      },
      type: "info",
      subject: "Order filled",
      body: "Order 7492aa7 has been filled at 10800.50"
    }
  ]
}

{
  channel: "notifications",
  type: "update",
  data: {
    trader_id: "40fb2b0a-c4eb-44cb-97b2-229af16b8b4a",
    notification_id: "bc4faa16-f58a-4de9-af86-d534300a4b02",
    notification_type: "order",
    action: "accepted",
    timestamp: "2019-07-15T18:20:08.000Z",
    details: {
      symbol: "BTC-USD",
      order_id: "988ff946-d71e-46ea-a5f3-7e3a77492aa7",
      cost: "0.00000000",
      price: "11340.50",
      side: "buy",
      size: "1.0000",
      size_filled: "0.0000",
      type: "market"
    },
    type: "info",
    subject: "Order accepted",
    body: "Your market order to buy 1.0000 BTC-USD has been accepted."
  }
}

The notifications channel is a consolidated feed of private messages regarding orders, deposits, and withdrawals.

account Channel

Example messages

{
  channel: "account",
  type: "snapshot",
  data: {
    attributes: [
      {
        attribute: "deposit_match_usd",
        active_rewards: [
          { type: "deposit_match_usd", value: "100", expires_at: null }
        ]
      },
      {
        attribute: "volume_tier",
        tier: 1,
        next_tier_requirement: "10.00",
        granted_at: "2020-06-29T13:27:19.743Z",
        active_rewards: [],
      },
      {
        attribute: "fee_discount",
        granted_at: "2020-06-29T23:09:51.341Z",
        active_rewards: [
          {
            type: "fee_discount",
            expires_at "2020-09-27T23:09:51.341Z",
            maker_value: "0.5",
            taker_value: "0.5"
          }
        ]
      },
      {
        attribute: "badge_1",
        granted_at: "2020-06-29T13:27:19.743Z",
        active_rewards: [
          { type: "affiliate_payout", value: "0.25" }
        ],
      }
    ],
    timestamp: "2019-10-13T12:06:25Z",
    volume_details: {
      after_date: "2019-09-13T00:00:00Z",
      total_volume: "7.00"
    }
  }
}

{
  channel: "account",
  type: "update",
  data: {
    attributes: [
      {
        attribute: "deposit_match_usd",
        active_rewards: [
          { type: "deposit_match_usd", value: "100", expires_at: null }
        ]
      },
      {
        attribute: "volume_tier",
        tier: 1,
        next_tier_requirement: "10.00",
        granted_at: "2020-06-29T13:27:19.743Z",
        active_rewards: [],
      },
      {
        attribute: "fee_discount",
        granted_at: "2020-06-29T23:09:51.341Z",
        active_rewards: [
          {
            type: "fee_discount",
            expires_at "2020-09-27T23:09:51.341Z",
            maker_value: "0.5",
            taker_value: "0.5"
          }
        ]
      },
      {
        attribute: "badge_1",
        granted_at: "2020-06-29T13:27:19.743Z",
        active_rewards: [
          { type: "affiliate_payout", value: "0.25" }
        ],
      }
    ],
    timestamp: "2019-10-13T12:06:25Z",
    volume_details: {
      after_date: "2019-09-13T00:00:00Z",
      total_volume: "7.00"
    }
  }
}

The account channel reports active user-attributes and information about rewards that those attributes (i.e. volume tiers, deposit match offers, badges earned) have earned the user. This channel is specific to a user and not a specific entity trading account.

This channel also reports 30-day trailing volume details (used to determine the user's volume tier).

The snapshot and update messages have the same schema.

Trading

To perform trading operations over the CoinList Pro WebSocket feed, first subscribe to a special upstream channel named trading. You must include authentication fields in your subscription request, as described here. Do not pass any specific symbols in your subscription message; simply pass symbols: []. Once subscribed, you may perform the following order management tasks by sending messages with type: 'request' over your CoinList Pro WebSocket connection. Note that you will not receive any downstream messages on the trading channel; you must be subscribed to the orders channel to receive order insert/modify/cancel notifications.

Messages sent to the trading channel are rate limited as described in the Rate Limits section above.

Create Order

Example message (single create)

{
  channel: "trading",
  type: "request",
  action: "create-order",
  data: {
    symbol: "BTC-USD",
    client_id: "My Order #10",
    type: "limit",
    side: "buy",
    size: "10.0000",
    price: "6500.00"
  }
}

Example message (bulk create)

{
  channel: "trading",
  type: "request",
  action: "create-order",
  data: [{
    symbol: "BTC-USD",
    client_id: "My Order #10",
    type: "limit",
    side: "buy",
    size: "10.0000",
    price: "6500.00"
  }, {
    symbol: "ETH-USD",
    client_id: "My Order #11",
    type: "market",
    side: "buy",
    size: "5.0000"
  }]
}

action: 'create-order'

See REST API docs for details.

Modify Order

Example message (single modify)

{
  channel: "trading",
  type: "request",
  action: "modify-order",
  data: {
    order_id: "58f5435e-02b8-4875-81d4-e3976c5ed68b",
    symbol: "BTC-USD",
    type: "market",
    side: "buy",
    size: "5.0000"
  }
}

Example message (bulk modify)

{
  channel: "trading",
  type: "request",
  action: "modify-order",
  data: [{
    order_id: "58f5435e-02b8-4875-81d4-e3976c5ed68b",
    symbol: "BTC-USD",
    type: "market",
    side: "buy",
    size: "5.0000"
  }, {
    order_id: "06d9f411-f4b9-42f9-a239-9a8fb4b65c65",
    symbol: "BTC-USD",
    type: "limit",
    side: "sell",
    size: "100.0000",
    price: "165.50"
  }]
}

action: 'modify-order'

See REST API docs for details.

Cancel Specific Order

Example message (single cancel)

{
  channel: "trading",
  type: "request",
  action: "cancel-order",
  data: {
    order_id: "58f5435e-02b8-4875-81d4-e3976c5ed68b"
  }
}

Example message (bulk cancel)

{
  channel: "trading",
  type: "request",
  action: "cancel-order",
  data: [{
    order_id: "58f5435e-02b8-4875-81d4-e3976c5ed68b"
  }, {
    order_id: "06d9f411-f4b9-42f9-a239-9a8fb4b65c65"
  }]
}

action: 'cancel-order'

See REST API docs for details.

Cancel All Orders (filterable)

Example message

{
  channel: "trading",
  type: "request",
  action: "cancel-all-orders",
  data: {
    symbol: "BTC-USD"
  }
}

action: 'cancel-all-orders'

Specifying a symbol is optional. See REST API docs for details.

Cancel All After (Dead Man's Switch)

Example message

{
  channel: "trading",
  type: "request",
  action: "cancel-all-after",
  data: {
    timeout: 60000
  }
}

action: 'cancel-all-after'

See REST API docs for details.

Appendix

Message Codes

Errors, bad requests, and rejected orders generally result in responses (either REST or WebSocket) containing a message_code string specifying the error that occurred. Here's a list of possible values for message_code:

message_code Description
ORDER_REJECT_BAD_STATUS The order has a status that makes it not cancelable or modifyable.
ORDER_REJECT_INVALID_POST_ONLY
ORDER_REJECT_INVALID_CLOSE_ONLY
ORDER_REJECT_POST_ONLY_REQUIRED The market currently allows only post-only orders.
ORDER_REJECT_FROZEN_ORDER This operation is currently not allowed on this order at this time.
ORDER_REJECT_LIMIT_PRICE_PROTECTION_VIOLATION The limit price violates the price protection range for this symbol.
ORDER_REJECT_CLOSED The market is closed for order operations.
ORDER_REJECT_MAX_ORDERS You have violated the 25 orders per symbol limit.
ORDER_REJECT_NOT_FOUND The order to modify or cancel was not found.
ORDER_REJECT_PARSE_ERROR The request failed to parse. Check data types. (strings vs. numbers)
ORDER_REJECT_PRICE_INVALID Prices must be positive and aligned with the tick size defined for the symbol.
ORDER_REJECT_QUANTITY_ZERO Quantity may not be zero.
ORDER_REJECT_TOKEN_LIMIT Your current token balance is not enough to back this order.
ORDER_REJECT_TOKEN_LIMIT_OTHER
ORDER_REJECT_SELF_TRADE This order would have been involved in a self-trade.
DENIED_MAINTENANCE The system is under active maintenance.

Schemas

AccountSummary

{
  "asset_balances": {
    "BTC": "0.00308696",
    "ETH": "20.000000000000000000"
  },
  "asset_holds": {
    "BTC": "0.00000000",
    "ETH": "1.000000000000000000"
  },
  "net_liquidation_value_usd": "string"
}

AccountSummary

Properties

Name Type Required Description
asset_balances object false Balance per-asset (in quantity)
» additionalProperties string false none
asset_holds object false Balance per-asset (in quantity) that is currently held to back open orders
» additionalProperties string false none
net_liquidation_value_usd string(decimal) false Total value of the account (in USD) with all assets valued using latest index prices

ApiKeyPair

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

ApiKeyPair

Properties

Name Type Required Description
trader_id string(uuid) true The trader account whom the key belongs to
key string(uuid) true The API key
secret string true The base64-encoded API secret
read boolean true Can this API key read private account data?
write boolean true Can this API key insert / modify orders?
transfer boolean true Can this API key transfer / withdraw funds?

Asset

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

Asset

Properties

Name Type Required Description
asset string false The identifier for the asset on CoinList Pro. (ex. BTC)
is_transferable boolean false True if the asset may be deposited and withdrawn.
is_visible boolean false True if the asset's balance is displayed to users in the CoinList Pro app. This is False only for some internal-only tracking assets such as fee credits.
index_code string false The index by which a balance of this asset will be valued (in USD).
decimal_places string(integer) false The number of decimal places in balance quantities for this asset.

Assets

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

Assets

Properties

Name Type Required Description
assets [Asset] false An array of supported assets

Auction

{
  "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"
}

Auction

Properties

Name Type Required Description
auction_code string false A code which uniquely identifies this Auction
symbol string false Symbol that the auction is for
price string(decimal) false Crossing price of the auction
volume string(decimal) false Total volume (in quantity) traded in the auction. If one trader bought 1 and another sold 1, this value will be 1.
imbalance string(decimal) false Imbalance volume (in quantity) in the auction
logical_time string(date-time) false Cutoff time for orders getting into this auction
call_time string(date-time) false Time this auction was called and results were recorded

Auctions

[
  {
    "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"
  }
]

Properties

Name Type Required Description
anonymous [Auction] false none

Balances

{
  "asset_balances": {
    "BTC": "0.00308696",
    "ETH": "20.000000000000000000"
  },
  "asset_holds": {
    "BTC": "0.00000000",
    "ETH": "1.000000000000000000"
  },
  "net_liquidation_value_usd": "string"
}

Balances

Properties

Name Type Required Description
asset_balances object false Balance per-asset (in quantity)
» additionalProperties string false none
asset_holds object false Balance per-asset (in quantity) that is currently held to back open orders
» additionalProperties string false none
net_liquidation_value_usd string(decimal) false Total value of the account (in USD) with all assets valued using latest index prices

Book

{
  "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"
    ]
  ]
}

Book

Properties

Name Type Required Description
after_auction_code string false The code of the auction after which this order book was valid
logical_time string(date-time) false The logical cutoff time for orders getting into the latest auction
call_time string(date-time) false The time the latest auction was called and results were recorded
bids [BookLevel] false [The first element in the array is the price and second element is the quantity at that price level]
asks [BookLevel] false [The first element in the array is the price and second element is the quantity at that price level]

BookLevel

[
  "7216.00000000",
  "1202.3046"
]

BookLevel

Properties

Name Type Required Description
BookLevel [string] false The first element in the array is the price and second element is the quantity at that price level

Candle

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

Tuple containing [ ISO timestamp, open, high, low, close, volume, index_close ]

Properties

None

Candles

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

Candles

Properties

Name Type Required Description
candles [Candle] false An array of arrays, each representing an individual Candle

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"
        }
      ]
    }
  ]
}

Competition

Properties

Name Type Required Description
competition_id string false An identifier which uniquely identifies this Competition
label string false Given name for the competition
created_at string(date-time) false Date and time the competition was created
start_date string(date-time) false Date and time the competition will begin or has begun
end_date string(date-time) false Date and time the competition will end or has ended
leaderboard [CompetitionRankLevel] false List of accounts participating in this competition in order of highest percent change to net liquidation value to smallest

CompetitionRankLevel

{
  "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"
    }
  ]
}

AccountRankLevel

Properties

Name Type Required Description
alias string false Trading account alias
is_eligible boolean false True if the trader is eligible to place on the leaderboard
percent_change string(decimal) false Percentage change in the total value of the account (balance + unrealized profit) since the trader joined the competition
sharpe_ratio string(decimal) false Sharpe ratio of the trader's percent change in the total value of the account since the trader joined the competition
trade_count string(decimal) false Number of trades made by the account since the trader joined the competition
trade_volume string(decimal) false Total trade volume of the account since the trader joined the competition
time_series [object] false Set of percent changes in the total value of the account since the trader joined the competition, taken 5 minutes apart
» created_at string(date-time) false Effective date and time of the percent change in the total value of the account since the trader joined the competition
» percent_change string(decimal) false Percentage change in the total value of the account since the trader joined the competition

CompetitionSummary

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

CompetitionSummary

Properties

Name Type Required Description
competition_id string false An identifier which uniquely identifies this Competition
label string false Given name for the competition
code string false A unique code that can be used to join this competition as a participant.
start_date string(date-time) false Date and time the competition will begin or has begun
end_date string(date-time) false Date and time the competition will end or has ended

CompetitionsList

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

CompetitionsList

Properties

Name Type Required Description
competitions [CompetitionSummary] false none

DailyTransactionHistory

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

Properties

Name Type Required Description
summary [DailyTransactionSummary] false none

DailyTransactionSummary

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

DailyTransactionSummary

Properties

Name Type Required Description
date string(date) false Record date (UTC).
eod_balance string(decimal) false End-of-day balance (in BTC).
amounts object false none
» fee string false none
» xfer string false none
» swap string false none
» affil string false none
» other string false none

Error

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

Properties

Name Type Required Description
message string true none
message_code string false none
message_details object false none

Fill

{
  "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"
}

Fill

Properties

Name Type Required Description
symbol string false Symbol for which the fill was recorded
auction_code string false Auction in which the fill occurred
order_id string(uuid) false Order for which the fill was recorded
quantity string(decimal) false Quantity filled
fee string(decimal) false Fee (in USD) incurred by the fill. A negative value denotes a fee rebate.
fee_type string false The designation of the fee associated with this fill. (i.e. maker or taker)
price string(decimal) false Price at which the fill was recorded
logical_time string(date-time) false Logical time of the auction in which the fill occurred

Fills

{
  "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"
    }
  ]
}

Properties

Name Type Required Description
fills [Fill] false none

Leaderboard

[
  {
    "alias": "string",
    "value": "string",
    "is_real_name": true
  }
]

Leaderboard

Properties

Name Type Required Description
Leaderboard [object] false none
alias string false Trading account alias
value string(decimal) false Metric value
is_real_name boolean false True if the user set the alias themselves; False if it was randomly assigned

MarketOrderSize

{
  "bid_size": "string",
  "ask_size": "string"
}

MarketOrderSize

Properties

Name Type Required Description
bid_size string(decimal) false Aggregate size of all market orders to buy
ask_size string(decimal) false Aggregate size of all market orders to sell

MarketSummary

{
  "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"
}

MarketSummary

Properties

Name Type Required Description
last_trade object false Info about the latest auction with volume
» price string(decimal) false The price of the last auction with volume
» volume string(decimal) false The quantity crossed in the last auction with volume
» imbalance string(decimal) false The quantity leftover that would have crossed in the auction had there have been quantity available on the other side.
» logical_time string(date-time) false The logical time of the last auction with volume
» auction_code string false The auction code of the last auction with volume
volume_base_24h string(decimal) false 24h rolling volume (in base currency; same unit as the market's size or quantity)
volume_quote_24h string(decimal) false 24h rolling volume (in quote currency; same unit as the market's price)

ModifiedOrder

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

ModifiedOrder

Properties

Name Type Required Description
type string true The type of order, which controls how the order will be executed. One of: market, limit, stop_market, stop_limit, take_market, or take_limit. See Order Types for details
side string true Can be buy or sell. You may not change the side of an order in a modify request, so this must remain the original side of the order.
size string(positiveDecimal) true The new quantity to buy or sell
price string(positiveDecimal) false The new price of this order (if the order is of type limit)
stop_price string(positiveDecimal) false The trigger price for this stop order (only if type is stop_market/stop_limit/take_market/take_limit)
stop_trigger string false Specifies whether the order should trigger when the stop price crosses the last trade price (last), the midpoint quote (fair), or underlying index price (index).
post_only boolean false A Post-Only order will only execute if it would be filled as a maker. If there is a cross that would have filled a post-only order as a taker, that order will be rejected. Post-Only orders are used by market makers to ensure they earn the maker rebate.
peg_price_type string false You can use the trailing-stop and trailing-stop-pct values along with the peg_offset_value order property to automatically peg the stop_price of an order to a fixed offset from the trigger price - but only as the market moves away from the peg, not towards it.
peg_offset_value string(decimal) false If peg_price_type is trailing-stop, this is a fixed offset from the trigger price. If trailing-stop-pct, this is a percentage offset (in decimal format). If this is a sell order, this value should be negative as the stop will 'trail' from the bottom.
origin string false Original creator of the order. One of web (inserted using the web application), api (inserted using the API), or liquidation (inserted by an internal risk monitor).

Enumerated Values

Property Value
type market
type limit
type stop_market
type stop_limit
type take_market
type take_limit
side buy
side sell
stop_trigger last
stop_trigger index
stop_trigger fair
peg_price_type trailing-stop
peg_price_type trailing-stop-pct
origin web
origin api
origin liquidation

NewOrder

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

Order

Properties

Name Type Required Description
client_id string false A client-specified order id.
symbol string true The symbol for which the order is placed
type string true The type of order, which controls how the order will be executed. One of: market, limit, stop_market, stop_limit, take_market, or take_limit. See Order Types for details
side string true Can be buy or sell
size string(positiveDecimal) true The quantity to buy or sell
price string(positiveDecimal) false The price of this order (if the order is of type limit)
stop_price string(positiveDecimal) false The trigger price for this stop order (only if type is stop_market/stop_limit/take_market/take_limit)
stop_trigger string false Specifies whether the order should trigger when the stop price crosses the last trade price (last), the midpoint quote (fair), or underlying index price (index).
self_trade_prevention string false The strategy to use for self-trade prevention. One of: keep-newest, keep-oldest, or cancel-all See Self-Trade Prevention for details.
post_only boolean false A Post-Only order will only execute if it would be filled as a maker. If there is a cross that would have filled a post-only order as a taker, that order will be rejected. Post-Only orders are used by market makers to ensure they earn the maker rebate.
peg_price_type string false You can use the trailing-stop and trailing-stop-pct values along with the peg_offset_value order property to automatically peg the stop_price of an order to a fixed offset from the trigger price - but only as the market moves away from the peg, not towards it.
peg_offset_value string(decimal) false If peg_price_type is trailing-stop, this is a fixed offset from the trigger price. If trailing-stop-pct, this is a percentage offset (in decimal format). If this is a sell order, this value should be negative as the stop will 'trail' from the bottom.
origin string false Original creator of the order. One of web (inserted using the web application), api (inserted using the API), or liquidation (inserted by an internal risk monitor).

Enumerated Values

Property Value
type market
type limit
type stop_market
type stop_limit
type take_market
type take_limit
side buy
side sell
stop_trigger last
stop_trigger index
stop_trigger fair
self_trade_prevention keep-newest
self_trade_prevention keep-oldest
self_trade_prevention cancel-all
self_trade_prevention choice-market
peg_price_type trailing-stop
peg_price_type trailing-stop-pct
origin web
origin api
origin liquidation

NewOrderRequestReceived

{
  "message": "string",
  "timestamp": "2019-08-24T14:15:22Z",
  "order": {
    "symbol": "string",
    "type": "market",
    "side": "buy",
    "size": "string",
    "price": "string",
    "stop_price": "string",
    "stop_trigger": "last",
    "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"
  }
}

NewOrderRequestReceived

Properties

allOf

Name Type Required Description
anonymous RequestReceived false none

and

Name Type Required Description
anonymous object false none
» order object false none
»» symbol string false The symbol for which the order is placed
»» type string false The type of order, which controls how the order will be executed. One of: market, limit, stop_market, stop_limit, take_market, or take_limit. See Order Types for details
»» side string false Can be buy or sell
»» size string(positiveDecimal) false The quantity to buy or sell
»» price string(positiveDecimal) false The price of this order (if the order is of type limit)
»» stop_price string(positiveDecimal) false The trigger price for this stop order (only if type is stop_market/stop_limit/take_market/take_limit)
»» stop_trigger string false Specifies whether the order should trigger when the stop price crosses the last trade price (last), the midpoint quote (fair), or underlying index price (index).
»» self_trade_prevention string false The strategy to use for self-trade prevention. One of: keep-newest, keep-oldest, or cancel-all See Self-Trade Prevention for details.
»» post_only boolean false A Post-Only order will only execute if it would be filled as a maker. If there is a cross that would have filled a post-only order as a taker, that order will be rejected. Post-Only orders are used by market makers to ensure they earn the maker rebate.
»» peg_price_type string false You can use the trailing-stop and trailing-stop-pct values along with the peg_offset_value order property to automatically peg the stop_price of an order to a fixed offset from the trigger price - but only as the market moves away from the peg, not towards it.
»» peg_offset_value string(decimal) false If peg_price_type is trailing-stop, this is a fixed offset from the trigger price. If trailing-stop-pct, this is a percentage offset (in decimal format). If this is a sell order, this value should be negative as the stop will 'trail' from the bottom.
»» origin string false Original creator of the order. One of web (inserted using the web application), api (inserted using the API), or liquidation (inserted by an internal risk monitor).
»» client_id string false A client-specified order id.
»» order_id string(uuid) false Id of the order that was created or modified
»» trader_id string(uuid) false The trading account whom the order belongs to

Enumerated Values

Property Value
type market
type limit
type stop_market
type stop_limit
type take_market
type take_limit
side buy
side sell
stop_trigger last
stop_trigger index
stop_trigger fair
self_trade_prevention keep-newest
self_trade_prevention keep-oldest
self_trade_prevention cancel-all
self_trade_prevention choice-market
peg_price_type trailing-stop
peg_price_type trailing-stop-pct
origin web
origin api
origin liquidation

NewOrderRequestsReceived

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

NewOrderRequestsReceived

Properties

allOf

Name Type Required Description
anonymous RequestReceived false none

and

Name Type Required Description
anonymous object false none
» order_ids [string] false Ids of the orders that were created or modified

Order

{
  "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": "last",
  "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"
}

Order

Properties

Name Type Required Description
order_id string(uuid) false A UUID which uniquely identifies this Order
client_id string false A client-specified order id.
symbol string false The symbol for which the order is placed
type string false The type of order, which controls how the order will be executed. One of: market, limit, stop_market, stop_limit, take_market, or take_limit. See Order Types for details
side string false Can be buy or sell
size string(positiveDecimal) false The quantity to buy or sell
price string(positiveDecimal) false The price of this order (if the order is of type limit)
stop_price string(positiveDecimal) false The trigger price for this stop order (only if type is stop_market/stop_limit/take_market/take_limit)
stop_trigger string false Specifies whether the order should trigger when the stop price crosses the last trade price (last), the midpoint quote (fair), or underlying index price (index).
self_trade_prevention string false The strategy to use for self-trade prevention. One of: keep-newest, keep-oldest, or cancel-all See Self-Trade Prevention for details.
average_fill_price string(decimal) false If the order has been partially or totally filled, the average fill price.
fill_fees string(decimal) false Aggregate fee (in USD) paid. A negative value denotes a fee rebate.
size_filled string(decimal) false Aggregate size (in quantity) filled.
created_at string(date-time) false The timestamp at which this order was created.
epoch_timestamp string(date-time) false The timestamp value used for time-priority for this order in an auction.
post_only boolean false A Post-Only order will only execute if it would be filled as a maker. If there is a cross that would have filled a post-only order as a taker, that order will be rejected. Post-Only orders are used by market makers to ensure they earn the maker rebate.
peg_price_type string false You can use the trailing-stop and trailing-stop-pct values along with the peg_offset_value order property to automatically peg the stop_price of an order to a fixed offset from the trigger price - but only as the market moves away from the peg, not towards it.
peg_offset_value string(decimal) false If peg_price_type is trailing-stop, this is a fixed offset from the trigger price. If trailing-stop-pct, this is a percentage offset (in decimal format). If this is a sell order, this value should be negative as the stop will 'trail' from the bottom.
origin string false Original creator of the order. One of web (inserted using the web application), api (inserted using the API), or liquidation (inserted by an internal risk monitor).
status string false The status of the order.

Enumerated Values

Property Value
type market
type limit
type stop_market
type stop_limit
type take_market
type take_limit
side buy
side sell
stop_trigger last
stop_trigger index
stop_trigger fair
self_trade_prevention keep-newest
self_trade_prevention keep-oldest
self_trade_prevention cancel-all
self_trade_prevention choice-market
peg_price_type trailing-stop
peg_price_type trailing-stop-pct
origin web
origin api
origin liquidation
status pending
status accepted
status rejected
status canceled
status done

Orders

{
  "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": "last",
      "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"
    }
  ]
}

Properties

Name Type Required Description
orders [Order] false none

Position

{
  "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"
}

Position

Properties

Name Type Required Description
trader_id string(uuid) false The trader who holds the position
contract_code string false The contract the position is in
quantity string(decimal) false The signed size (number of contracts) of the position
marking_price string(decimal) false The price used to mark positions and compute the other fields in this response
marking_time string false The call time of the auction that crossed with the marking price
average_entry_price string(decimal) false The average entry price of the position
open_pl string(decimal) false The unrealized (open) profit from this position (negative for unrealized losses)
day_closed_pl string(decimal) false Profit (or loss) realized today (UTC) relative to the position's average entry price
day_realized_average_entry_price string(decimal) false The average entry price of trades during the current UTC day
day_realtive_closed_pl string(decimal) false Profit (or loss) realized today (UTC) relative to the position's day-relative average entry price
day_relative_to_date string false The date the day-relative fields in this response are relative to

Positions

{
  "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"
    }
  ]
}

Properties

Name Type Required Description
positions [Position] false none

Quote

{
  "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"
}

Quote

Properties

Name Type Required Description
last_trade object false Info about the latest auction with volume
» price string(decimal) false The price of the last auction with volume
» volume string(decimal) false The quantity crossed in the last auction with volume
» imbalance string(decimal) false The quantity leftover that would have crossed in the auction had there have been quantity available on the other side.
» logical_time string(date-time) false The logical time of the last auction with volume
» auction_code string false The auction code of the last auction with volume
quote object false Best bid and best offer information from the latest auction
» bid string(decimal) false The best bid price in the latest auction
» bid_size string(decimal) false The aggregate size at the best bid price in the latest auction
» ask string(decimal) false The best ask price in the latest auction
» ask_size string(decimal) false The aggregate size at the best ask price in the latest auction
after_auction_code string false The auction code of the latest auction (after which this quote data is relevant)
logical_time string(date-time) false The logical cutoff time for orders getting into the latest auction
call_time string(date-time) false The time the latest auction was called and results were recorded

RequestReceived

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

RequestReceived

Properties

Name Type Required Description
message string true Request received message
timestamp string(date-time) true Time that the request was received

Symbol

{
  "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"
}

Symbol

Properties

Name Type Required Description
symbol string false Symbol name (i.e. BTC-USD)
series_code string false Series name (i.e. BTC)
index_code string false Index code (i.e. .BTCUSD)
type string false The type of market this symbol represents
list_time string(date-time) false Symbol listing date and time (listing here means available for trading)
base_currency string false Base currency or asset underlying this market
quote_currency string false Currency or asset against which prices are quoted for this market
minimum_size_increment string(decimal) false The smallest size fluctuation possible for this market
minimum_price_increment string(decimal) false The smallest price fluctuation possible (tick size) for this market
minimum_size string(decimal) false The smallest order size possible for this market

Enumerated Values

Property Value
type spot

SymbolSummary

{
  "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"
}

SymbolSummary

Properties

Name Type Required Description
type string false none
last_price string(decimal) false none
lowest_ask string(decimal) false none
highest_bid string(decimal) false none
last_trade object false Info about the latest auction with volume
» price string(decimal) false The price of the last auction with volume
» volume string(decimal) false The quantity crossed in the last auction with volume
» imbalance string(decimal) false The quantity leftover that would have crossed in the auction had there have been quantity available on the other side.
» logical_time string(date-time) false The logical time of the last auction with volume
» auction_code string false The auction code of the last auction with volume
volume_base_24h string(decimal) false 24h rolling volume (in base currency; same unit as the symbol's size or quantity)
volume_quote_24h string(decimal) false 24h rolling volume (in quote currency; same unit as the symbol's price)
price_change_percent_24h string(decimal) false none
highest_price_24h string(decimal) false none
lowest_price_24h string(decimal) false none

Symbols

{
  "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"
    }
  ]
}

Properties

Name Type Required Description
symbols [Symbol] false none

Time

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

Time

Properties

Name Type Required Description
epoch number false the current time as a Unix Epoch time
iso string(date-time) false the current time in UTC as an ISO 8601 date-time

Transaction

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

*A transaction is an entry on the asset-specific ledger that tracks a trading account's asset balances.

Here are the possible values of type:

Properties

Name Type Required Description
transaction_id string(uuid) false Transaction id.
created_at string(date-time) false The time the transaction was completed.
asset string false The asset whose balance is affected by the transaction. (ex. BTC)
symbol string false The symbol relevant to the transaction (if applicable).
amount string(decimal) false The value of the transaction (balance delta).
type string false The reason for the transaction. (see the table above for possible options)
details object false Additional details regarding the transaction. (ex. relevant order ids, etc.)

Enumerated Values

Property Value
type fee
type xfer
type credit
type swap

TransactionHistory

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

Properties

Name Type Required Description
transactions [Transaction] false A trading account's transaction ledger

Transfer

{
  "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"
}

*A transfer representes a user-initiated movement of funds in or out out of a CoinList Pro trading account. Currently, you may only transfer funds between CoinList and CoinList Pro or between entity trading accounts.

These transfers are represented as type xfer in the transaction ledger. *

Properties

Name Type Required Description
transfer_id string(uuid) false Transfer id.
created_at string(date-time) false The time the transfer was initiated.
canceled_at string(date-time) false The time the transfer was canceled.
confirmed_at string(date-time) false The time the transfer was confirmed.
asset string false The asset whose balance is affected by the transfer. (ex. BTC)
amount string(decimal) false The value of the transfer (balance delta).
status string false The status of the transfer.

Enumerated Values

Property Value
status pending
status processing
status confirmed
status canceled

TransferHistory

{
  "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"
    }
  ]
}

Properties

Name Type Required Description
transfers [Transfer] false A list of user-initiated transfers in or out of a trading account

Wallet

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

Wallet

Properties

Name Type Required Description
asset string false The identifier for the wallet's asset on CoinList Pro (e.g. BTC)
balance string(decimal) false The the available balance of the wallet

WalletLedgerEntry

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

WalletLedgerEntry

Properties

Name Type Required Description
id string(uuid) false The identifier for the ledger entry.
description string false A description of the transaction.
asset string false The asset whose balance is affected by the transaction. (ex. BTC)
amount string(decimal) false The value of the transaction (balance delta).
created_at string(date-time) false The time the transaction was initiated.