Introduction

Welcome to Coinbase Pro trader and developer documentation. These documents outline exchange functionality, market details, and APIs.

APIs are separated into two categories: trading and feed. Trading APIs require authentication and provide access to placing orders and other account information. Feed APIs provide market data and are public.

Upcoming Changes

06/14/21

• Order Cancel Batch Request(U4) will now return Order Cancel Reject(9) for partial rejected cancel request

General

Market overview and general information.

Matching Engine

Coinbase Pro operates a continuous first-come, first-serve order book. Orders are executed in price-time priority as received by the matching engine.

Self-Trade Prevention

Self-trading is not allowed on Coinbase Pro. Two orders from the same user will not fill one another. When placing an order, you can specify the self-trade prevention behavior.

Decrement and cancel

The default behavior is decrement and cancel. When two orders from the same user cross, the smaller order will be canceled and the larger order size will be decremented by the smaller order size. If the two orders are the same size, both will be canceled.

Cancel oldest

Cancel the older (resting) order in full. The new order continues to execute.

Cancel newest

Cancel the newer (taking) order in full. The old resting order remains on the order book.

Cancel both

Immediately cancel both orders.

Notes for Market Orders

When a market order using dc self-trade prevention encounters an open limit order, the behavior depends on which fields for the market order message were specified. If funds and size are specified for a buy order, then size for the market order will be decremented internally within the matching engine and funds will remain unchanged. The intent is to offset your target size without limiting your buying power. If size is not specified, then funds will be decremented. For a market sell, the size will be decremented when encountering existing limit orders.

Price Improvement

Orders are matched against existing order book orders at the price of the order on the book, not at the price of the taker order.

Example

User A places a Buy order for 1 BTC at 100 USD. User B then wishes to sell 1 BTC at 80 USD. Because User A's order was first to the trading engine, they will have price priority and the trade will occur at 100 USD.

Order Lifecycle

Valid orders sent to the matching engine are confirmed immediately and are in the received state. If an order executes against another order immediately, the order is considered done. An order can execute in part or whole. Any part of the order not filled immediately, will be considered open. Orders will stay in the open state until canceled or subsequently filled by new orders. Orders that are no longer eligible for matching (filled or canceled) are in the done state.

Data Centers

Coinbase Pro data centers are in the Amazon US East N. Virginia (us-east-1) region.

Sandbox

A public sandbox is available for testing API connectivity and web trading. While the sandbox only hosts a subset of the production order books, all of the exchange functionality is available. Additionally, in this environment you are allowed to add unlimited fake funds for testing.

Login sessions and API keys are separate from production. Use the sandbox web interface to create keys in the sandbox environment.

To add funds, use the web interface deposit and withdraw buttons as you would on the production web interface.

Sandbox URLs

When testing your API connectivity, make sure to use the following URLs.

Website
https://public.sandbox.pro.coinbase.com

REST API
https://api-public.sandbox.pro.coinbase.com

Websocket Feed
wss://ws-feed-public.sandbox.pro.coinbase.com

FIX API
tcp+ssl://fix-public.sandbox.pro.coinbase.com:4198

Client Libraries

We do not actively maintain official client libraries. Below are a list of unofficial clients that can help you integrate with our API:

• Node.js client library
• GDAX trading toolkit (Node.js)
• Ruby (not actively maintained)
• Go
• Haskell
• Java
• Python
• Rust
• C#

Profiles

Profiles are the equivalent of portfolios on the Coinbase Pro website. API keys are scoped to a specific profile. An API key only has access to creating and viewing data that belongs to its own profile, unless otherwise noted. This is true for the REST API, FIX API and Websocket Feed. In order to access data or actions on a different profile, please create a new API key via the Coinbase Pro website.

Deleted Profiles

Profiles can be deleted on the Coinbase Pro website. A deleted profile's API keys' permissions are automatically set to "View".

API

The REST API has endpoints for account and order management as well as public market data.

REST API Endpoint URL

https://api.pro.coinbase.com

There is also a FIX API for order management.

Requests

All requests and responses are application/json content type and follow typical HTTP response status codes for success and failure.

Errors

{
    "message": "Invalid Price"
}

Unless otherwise stated, errors to bad requests will respond with HTTP 4xx or status codes. The body will also contain a message parameter indicating the cause. Your language's http library should be configured to provide message bodies for non-2xx requests so that you can read the message field from the body.

Common error codes

Success

A successful response is indicated by HTTP status code 200 and may contain an optional body. If the response has a body it will be documented under each resource below.

Pagination

Coinbase Pro uses cursor pagination for all REST requests which return arrays. Cursor pagination allows for fetching results before and after the current page of results and is well suited for realtime data. Endpoints like /trades, /fills, /orders, return the latest items by default. To retrieve more results subsequent requests should specify which direction to paginate based on the data previously returned.

before and after cursors are available via response headers CB-BEFORE and CB-AFTER. Your requests should use these cursor values when making requests for pages after the initial request.

Parameters

Example

GET /orders?before=2&limit=30

Before and After cursors

The before cursor references the first item in a results page and the after cursor references the last item in a set of results.

To request a page of records before the current one, use the before query parameter. Your initial request can omit this parameter to get the default first page.

The response will contain a CB-BEFORE header which will return the cursor id to use in your next request for the page before the current one. The page before is a newer page and not one that happened before in chronological time.

The response will also contain a CB-AFTER header which will return the cursor id to use in your next request for the page after this one. The page after is an older page and not one that happened after this one in chronological time.

Types

Timestamps

2014-11-06T10:34:47.123456Z

Unless otherwise specified, all timestamps from API are returned in ISO 8601 with microseconds. Make sure you can parse the following ISO 8601 format. Most modern languages and libraries will handle this without issues.

Numbers

Decimal numbers are returned as strings to preserve full precision across platforms. When making a request, it is recommended that you also convert your numbers to strings to avoid truncation and precision errors.

Integer numbers (like trade id and sequence) are unquoted.

IDs

Most identifiers are UUID unless otherwise specified. When making a request which requires a UUID, both forms (with and without dashes) are accepted.

132fb6ae-456b-4654-b4e0-d681ac05cea1 or 132fb6ae456b4654b4e0d681ac05cea1

Rate Limits

When a rate limit is exceeded, a status of 429 Too Many Requests will be returned.

REST API

Public endpoints

We throttle public endpoints by IP: 10 requests per second, up to 15 requests per second in bursts. Some endpoints may have custom rate limits.

Private endpoints

We throttle private endpoints by profile ID: 15 requests per second, up to 30 requests per second in bursts. Some endpoints may have custom rate limits.

/fills endpoint has a custom rate limit of 10 requests per second, up to 20 requests per second in bursts.

Financial Information eXchange API

The FIX API throttles the number of incoming messages to 50 commands per second. A maximum of 5 connections can be established per profile.

Private

Private endpoints are available for order management, and account management. Every private request must be signed using the described authentication scheme.

Authentication

Generating an API Key

Before being able to sign any requests, you must create an API key via the Coinbase Pro website. The API key will be scoped to a specific profile. Upon creating a key you will have 3 pieces of information which you must remember:

• Key
• Secret
• Passphrase

The Key and Secret will be randomly generated and provided by Coinbase Pro; the Passphrase will be provided by you to further secure your API access. Coinbase Pro stores the salted hash of your passphrase for verification, but cannot recover the passphrase if you forget it. Each user can generate a max of 200 API keys.

API Key Permissions

You can restrict the functionality of API keys. Before creating the key, you must choose what permissions you would like the key to have. The permissions are:

• View - Allows a key read permissions. This includes all GET endpoints.
• Transfer - Allows a key to transfer currency on behalf of an account, including deposits and withdraws. Enable with caution - API key transfers WILL BYPASS two-factor authentication.
• Trade - Allows a key to enter orders, as well as retrieve trade data. This includes POST /orders and several GET endpoints.

Please refer to documentation below to see what API key permissions are required for a specific route.

Creating a Request

All REST requests must contain the following headers:

• CB-ACCESS-KEY The api key as a string.
• CB-ACCESS-SIGN The base64-encoded signature (see Signing a Message).
• CB-ACCESS-TIMESTAMP A timestamp for your request.
• CB-ACCESS-PASSPHRASE The passphrase you specified when creating the API key.

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

Signing a Message

var crypto = require('crypto');

var secret = 'PYPd1Hv4J6/7x...';

var timestamp = Date.now() / 1000;
var requestPath = '/orders';

var body = JSON.stringify({
    price: '1.0',
    size: '1.0',
    side: 'buy',
    product_id: 'BTC-USD'
});

var method = 'POST';

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

// decode the base64 secret
var key = Buffer(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');

# Requires python-requests. Install with pip:
#
#   pip install requests
#
# or, with easy-install:
#
#   easy_install requests

import json, hmac, hashlib, time, requests, base64
from requests.auth import AuthBase

# Create custom authentication for Exchange
class CoinbaseExchangeAuth(AuthBase):
    def __init__(self, api_key, secret_key, passphrase):
        self.api_key = api_key
        self.secret_key = secret_key
        self.passphrase = passphrase

    def __call__(self, request):
        timestamp = str(time.time())
        message = timestamp + request.method + request.path_url + (request.body or '')
        hmac_key = base64.b64decode(self.secret_key)
        signature = hmac.new(hmac_key, message, hashlib.sha256)
        signature_b64 = signature.digest().encode('base64').rstrip('\n')

        request.headers.update({
            'CB-ACCESS-SIGN': signature_b64,
            'CB-ACCESS-TIMESTAMP': timestamp,
            'CB-ACCESS-KEY': self.api_key,
            'CB-ACCESS-PASSPHRASE': self.passphrase,
            'Content-Type': 'application/json'
        })
        return request

api_url = 'https://api.pro.coinbase.com/'
auth = CoinbaseExchangeAuth(API_KEY, API_SECRET, API_PASS)

# Get accounts
r = requests.get(api_url + 'accounts', auth=auth)
print r.json()
# [{"id": "a1b2c3d4", "balance":...

# Place an order
order = {
    'size': 1.0,
    'price': 1.0,
    'side': 'buy',
    'product_id': 'BTC-USD',
}
r = requests.post(api_url + 'orders', json=order, auth=auth)
print r.json()
# {"id": "0428b97b-bec1-429e-a94c-59992926778d"}

require 'base64'
require 'openssl'
require 'json'

class CoinbaseExchange
    def initialize(key, secret, passphrase)
      @key = key
      @secret = secret
      @passphrase = passphrase
    end

    def signature(request_path='', body='', timestamp=nil, method='GET')
      body = body.to_json if body.is_a?(Hash)
      timestamp = Time.now.to_i if !timestamp

      what = "#{timestamp}#{method}#{request_path}#{body}";

      # create a sha256 hmac with the secret
      secret = Base64.decode64(@secret)
      hash  = OpenSSL::HMAC.digest('sha256', secret, what)
      Base64.strict_encode64(hash)
    end
end

<?php
class CoinbaseExchange {
    public function __construct($key, $secret, $passphrase) {
        $this->key = $key;
        $this->secret = $secret;
        $this->passphrase = $passphrase;
    }

    public function signature($request_path='', $body='', $timestamp=false, $method='GET') {
        $body = is_array($body) ? json_encode($body) : $body;
        $timestamp = $timestamp ? $timestamp : time();

        $what = $timestamp.$method.$request_path.$body;

        return base64_encode(hash_hmac("sha256", $what, base64_decode($this->secret), true));
    }
}

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

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

The method should be UPPER CASE.

Selecting a Timestamp

The CB-ACCESS-TIMESTAMP header MUST be number of seconds since Unix Epoch in UTC. Decimal values are allowed.

Your timestamp must be within 30 seconds of the api service time or your request will be considered expired and rejected. We recommend using the time endpoint to query for the API server time if you believe there many be time skew between your server and the API servers.

Accounts

List Accounts

[
    {
        "id": "71452118-efc7-4cc4-8780-a5e22d4baa53",
        "currency": "BTC",
        "balance": "0.0000000000000000",
        "available": "0.0000000000000000",
        "hold": "0.0000000000000000",
        "profile_id": "75da88c5-05bf-4f54-bc85-5c775bd68254",
        "trading_enabled": true
    },
    {
        "id": "e316cb9a-0808-4fd7-8914-97829c1925de",
        "currency": "USD",
        "balance": "80.2301373066930000",
        "available": "79.2266348066930000",
        "hold": "1.0035025000000000",
        "profile_id": "75da88c5-05bf-4f54-bc85-5c775bd68254",
        "trading_enabled": true
    }
]

Get a list of trading accounts from the profile of the API key.

HTTP Request

GET /accounts

API Key Permissions

This endpoint requires either the "view" or "trade" permission.

Rate Limits

This endpoint has a custom rate limit by profile ID: 25 requests per second, up to 50 requests per second in bursts

Account Fields

Funds on Hold

When you place an order, the funds for the order are placed on hold. They cannot be used for other orders or withdrawn. Funds will remain on hold until the order is filled or canceled.

Get an Account

{
    "id": "a1b2c3d4",
    "balance": "1.100",
    "holds": "0.100",
    "available": "1.00",
    "currency": "USD"
}

Information for a single account. Use this endpoint when you know the account_id. API key must belong to the same profile as the account.

HTTP request

GET /accounts/<account-id>

API Key Permissions

This endpoint requires either the "view" or "trade" permission.

Account Fields

Get Account History

[
    {
        "id": "100",
        "created_at": "2014-11-07T08:19:27.028459Z",
        "amount": "0.001",
        "balance": "239.669",
        "type": "fee",
        "details": {
            "order_id": "d50ec984-77a8-460a-b958-66f114b0de9b",
            "trade_id": "74",
            "product_id": "BTC-USD"
        }
    }
]

List account activity of the API key's profile. Account activity either increases or decreases your account balance. Items are paginated and sorted latest first. See the Pagination section for retrieving additional entries after the first page.

HTTP request

GET /accounts/<account-id>/ledger

API Key Permissions

This endpoint requires either the "view" or "trade" permission.

Entry Types

Entry type indicates the reason for the account change.

Details

If an entry is the result of a trade (match, fee), the details field will contain additional information about the trade.

Get Holds

[
    {
        "id": "82dcd140-c3c7-4507-8de4-2c529cd1a28f",
        "account_id": "e0b3f39a-183d-453e-b754-0c13e5bab0b3",
        "created_at": "2014-11-06T10:34:47.123456Z",
        "updated_at": "2014-11-06T10:40:47.123456Z",
        "amount": "4.23",
        "type": "order",
        "ref": "0a205de4-dd35-4370-a285-fe8fc375a273",
    }
]

List holds of an account that belong to the same profile as the API key. Holds are placed on an account for any active orders or pending withdraw requests. As an order is filled, the hold amount is updated. If an order is canceled, any remaining hold is removed. For a withdraw, once it is completed, the hold is removed.

HTTP Request

GET /accounts/<account_id>/holds

API Key Permissions

This endpoint requires either the "view" or "trade" permission.

Type

The type of the hold will indicate why the hold exists. The hold type is order for holds related to open orders and transfer for holds related to a withdraw.

Ref

The ref field contains the id of the order or transfer which created the hold.

Orders

Place a New Order

{
    "size": "0.01",
    "price": "0.100",
    "side": "buy",
    "product_id": "BTC-USD"
}

Response

{
    "id": "d0c5340b-6d6c-49d9-b567-48c4bfca13d2",
    "price": "0.10000000",
    "size": "0.01000000",
    "product_id": "BTC-USD",
    "side": "buy",
    "stp": "dc",
    "type": "limit",
    "time_in_force": "GTC",
    "post_only": false,
    "created_at": "2016-12-08T20:02:28.53864Z",
    "fill_fees": "0.0000000000000000",
    "filled_size": "0.00000000",
    "executed_value": "0.0000000000000000",
    "status": "pending",
    "settled": false
}

You can place two types of orders: limit and market. Orders can only be placed if your account has sufficient funds. Each profile can have a maximum of 500 open orders on a product. Once reached, the profile will not be able to place any new orders until the total number of open orders is below 500. Once an order is placed, your account funds will be put on hold for the duration of the order. How much and which funds are put on hold depends on the order type and parameters specified. See the Holds details below.

HTTP Request

POST /orders

API Key Permissions

This endpoint requires the "trade" permission.

Parameters

These parameters are common to all order types. Depending on the order type, additional parameters will be required (see below).

limit order parameters

* Requires time_in_force to be GTT

** Invalid when time_in_force is IOC or FOK

market order parameters

* One of size or funds is required.

Product ID

The product_id must match a valid product. The products list is available via the /products endpoint.

Client Order ID

The optional client_oid field must be a UUID generated by your trading application. This field value will be broadcast in the public feed for received messages. You can use this field to identify your orders in the public feed.

The client_oid is different than the server-assigned order id. If you are consuming the public feed and see a received message with your client_oid, you should record the server-assigned order_id as it will be used for future order status updates. The client_oid will NOT be used after the received message is sent.

The server-assigned order id is also returned as the id field to this HTTP POST request.

Type

When placing an order, you can specify the order type. The order type you specify will influence which other order parameters are required as well as how your order will be executed by the matching engine. If type is not specified, the order will default to a limit order.

limit orders are both the default and basic order type. A limit order requires specifying a price and size. The size is the number of base currency to buy or sell, and the price is the price per base currency. The limit order will be filled at the price specified or better. A sell order can be filled at the specified price per base currency or a higher price per base currency and a buy order can be filled at the specified price or a lower price depending on market conditions. If market conditions cannot fill the limit order immediately, then the limit order will become part of the open order book until filled by another incoming order or canceled by the user.

market orders differ from limit orders in that they provide no pricing guarantees. They however do provide a way to buy or sell specific amounts of base currency or fiat without having to specify the price. Market orders execute immediately and no part of the market order will go on the open order book. Market orders are always considered takers and incur taker fees. When placing a market order you can specify funds and/or size. Funds will limit how much of your quote currency account balance is used and size will limit the amount of base currency transacted.

Stop orders

Stop orders become active and wait to trigger based on the movement of the last trade price. There are two types of stop orders, stop loss and stop entry:

stop: 'loss': Triggers when the last trade price changes to a value at or below the stop_price.

stop: 'entry': Triggers when the last trade price changes to a value at or above the stop_price.

The last trade price is the last price at which an order was filled. This price can be found in the latest match message. Note that not all match messages may be received due to dropped messages.

Note that when stop orders are triggered, they execute as limit orders and are therefore subject to holds.

Price

The price must be specified in quote_increment product units. The quote increment is the smallest unit of price. For example, the BTC-USD product has a quote increment of 0.01 or 1 penny. Prices less than 1 penny will not be accepted, and no fractional penny prices will be accepted. Not required for market orders.

Size

The size must be greater than the base_min_size for the product and no larger than the base_max_size. The size can be in incremented in units of base_increment. size indicates the amount of BTC (or base currency) to buy or sell.

Funds

The funds field is optionally used for market orders. When specified it indicates how much of the product quote currency to buy or sell. For example, a market buy for BTC-USD with funds specified as 150.00 will spend 150 USD to buy BTC (including any fees). If the funds field is not specified for a market buy order, size must be specified and Coinbase Pro will use available funds in your account to buy bitcoin.

A market sell order can also specify the funds. If funds is specified, it will limit the sell to the amount of funds specified. You can use funds with sell orders to limit the amount of quote currency funds received.

Time in force

Time in force policies provide guarantees about the lifetime of an order. There are four policies: good till canceled GTC, good till time GTT, immediate or cancel IOC, and fill or kill FOK.

GTC Good till canceled orders remain open on the book until canceled. This is the default behavior if no policy is specified.

GTT Good till time orders remain open on the book until canceled or the allotted cancel_after is depleted on the matching engine. GTT orders are guaranteed to cancel before any other order is processed after the cancel_after timestamp which is returned by the API. A day is considered 24 hours.

IOC Immediate or cancel orders instantly cancel the remaining size of the limit order instead of opening it on the book.

FOK Fill or kill orders are rejected if the entire size cannot be matched.

* Note, match also refers to self trades.

Post only

The post-only flag indicates that the order should only make liquidity. If any part of the order results in taking liquidity, the order will be rejected and no part of it will execute.

Holds

For limit buy orders, we will hold price x size x (1 + fee-percent) USD. For sell orders, we will hold the number of base currency you wish to sell. Actual fees are assessed at time of trade. If you cancel a partially filled or unfilled order, any remaining funds will be released from hold.

For market buy orders where funds is specified, the funds amount will be put on hold. If only size is specified, all of your account balance (in the quote account) will be put on hold for the duration of the market order (usually a trivially short time). For a sell order, the size in base currency will be put on hold. If size is not specified (and only funds is specified), your entire base currency balance will be on hold for the duration of the market order.

Self-trade prevention

Self-trading is not allowed on Coinbase Pro. Two orders from the same user will not be allowed to match with one another. To change the self-trade behavior, specify the stp flag.

See the self-trade prevention documentation for details about these fields.

Order Lifecycle

The HTTP Request will respond when an order is either rejected (insufficient funds, invalid parameters, etc) or received (accepted by the matching engine). A 200 response indicates that the order was received and is active. Active orders may execute immediately (depending on price and market conditions) either partially or fully. A partial execution will put the remaining size of the order in the open state. An order that is filled completely, will go into the done state.

Users listening to streaming market data are encouraged to use the client_oid field to identify their received messages in the feed. The REST response with a server order_id may come after the received message in the public data feed.

Response

A successful order will be assigned an order id. A successful order is defined as one that has been accepted by the matching engine.

Cancel an Order

Cancel a previously placed order. Order must belong to the profile that the API key belongs to.

If the order had no matches during its lifetime its record may be purged. This means the order details will not be available with GET /orders/<id>.

HTTP Request

DELETE /orders/<id>
DELETE /orders/client:<client_oid>

API Key Permissions

This endpoint requires the "trade" permission.

Orders may be canceled using either the exchange assigned id or the client assigned client_oid. When using client_oid it must be preceded by the client: namespace.

Query Parameters

Cancel Reject

If the order could not be canceled (already filled or previously canceled, etc), then an error response will indicate the reason in the message field.

Cancel all

With best effort, cancel all open orders from the profile that the API key belongs to. The response is a list of ids of the canceled orders.

[
    "144c6f8e-713f-4682-8435-5280fbe8b2b4",
    "debe4907-95dc-442f-af3b-cec12f42ebda",
    "cf7aceee-7b08-4227-a76c-3858144323ab",
    "dfc5ae27-cadb-4c0c-beef-8994936fde8a",
    "34fecfbf-de33-4273-b2c6-baf8e8948be4"
]

HTTP Request

DELETE /orders

API Key Permissions

This endpoint requires the "trade" permission.

Query Parameters

List Orders

[
    {
        "id": "d0c5340b-6d6c-49d9-b567-48c4bfca13d2",
        "price": "0.10000000",
        "size": "0.01000000",
        "product_id": "BTC-USD",
        "side": "buy",
        "stp": "dc",
        "type": "limit",
        "time_in_force": "GTC",
        "post_only": false,
        "created_at": "2016-12-08T20:02:28.53864Z",
        "fill_fees": "0.0000000000000000",
        "filled_size": "0.00000000",
        "executed_value": "0.0000000000000000",
        "status": "open",
        "settled": false
    },
    {
        "id": "8b99b139-58f2-4ab2-8e7a-c11c846e3022",
        "price": "1.00000000",
        "size": "1.00000000",
        "product_id": "BTC-USD",
        "side": "buy",
        "stp": "dc",
        "type": "limit",
        "time_in_force": "GTC",
        "post_only": false,
        "created_at": "2016-12-08T20:01:19.038644Z",
        "fill_fees": "0.0000000000000000",
        "filled_size": "0.00000000",
        "executed_value": "0.0000000000000000",
        "status": "open",
        "settled": false
    }
]

List your current open orders from the profile that the API key belongs to. Only open or un-settled orders are returned. As soon as an order is no longer open and settled, it will no longer appear in the default request.

HTTP REQUEST

GET /orders

API Key Permissions

This endpoint requires either the "view" or "trade" permission.

Query Parameters

To specify multiple statuses, use the status query argument multiple times: /orders?status=done&status=pending.

Order status and settlement

Orders which are no longer resting on the order book, will be marked with the done status. There is a small window between an order being done and settled. An order is settled when all of the fills have settled and the remaining holds (if any) have been removed.

Polling

For high-volume trading it is strongly recommended that you maintain your own list of open orders and use one of the streaming market data feeds to keep it updated. You should poll the open orders endpoint once when you start trading to obtain the current state of any open orders.

executed_value is the cumulative match size * price and is only present for orders placed after 2016-05-20.

Get an Order

{
    "id": "68e6a28f-ae28-4788-8d4f-5ab4e5e5ae08",
    "size": "1.00000000",
    "product_id": "BTC-USD",
    "side": "buy",
    "stp": "dc",
    "funds": "9.9750623400000000",
    "specified_funds": "10.0000000000000000",
    "type": "market",
    "post_only": false,
    "created_at": "2016-12-08T20:09:05.508883Z",
    "done_at": "2016-12-08T20:09:05.527Z",
    "done_reason": "filled",
    "fill_fees": "0.0249376391550000",
    "filled_size": "0.01291771",
    "executed_value": "9.9750556620000000",
    "status": "done",
    "settled": true
}

Get a single order by order id from the profile that the API key belongs to.

HTTP Request

GET /orders/<id>
GET /orders/client:<client_oid>

API Key Permissions

This endpoint requires either the "view" or "trade" permission.

Orders may be queried using either the exchange assigned id or the client assigned client_oid. When using client_oid it must be preceded by the client: namespace.

If the order is canceled the response may have status code 404 if the order had no matches.

Fills

List Fills

[
    {
        "trade_id": 74,
        "product_id": "BTC-USD",
        "price": "10.00",
        "size": "0.01",
        "order_id": "d50ec984-77a8-460a-b958-66f114b0de9b",
        "created_at": "2014-11-07T22:19:28.578544Z",
        "liquidity": "T",
        "fee": "0.00025",
        "settled": true,
        "side": "buy"
    }
]

Get a list of recent fills of the API key's profile.

HTTP request

GET /fills

API Key Permissions

This endpoint requires either the "view" or "trade" permission.

Query Parameters

You can request fills for specific orders or products using query parameters.

Settlement and Fees

Fees are recorded in two stages. Immediately after the matching engine completes a match, the fill is inserted into our datastore. Once the fill is recorded, a settlement process will settle the fill and credit both trading counterparties.

The fee field indicates the fees charged for this individual fill.

Liquidity

The liquidity field indicates if the fill was the result of a liquidity provider or liquidity taker. M indicates Maker and T indicates Taker.

Pagination

Fills are returned sorted by descending trade_id from the largest trade_id to the smallest trade_id. The CB-BEFORE header will have this first trade id so that future requests using the cb-before parameter will fetch fills with a greater trade id (newer fills).

Limits

Get Current Exchange Limits

{
  "limit_currency": "USD",
  "transfer_limits": {
    "ach": {
      "BAT": {
        "max": "21267.54245368",
        "remaining": "21267.54245368",
        "period_in_days": 7
      }
    },
    "ach_no_balance": {
      "BAT": {
        "max": "21267.54245368",
        "remaining": "21267.54245368",
        "period_in_days": 1
      }
    },
    "credit_debit_card": {
      "BAT": {
        "max": "1450.00481776",
        "remaining": "1450.00481776",
        "period_in_days": 7
      }
    },
    "ach_curm": {
      "BAT": {
        "max": "200748.99232287",
        "remaining": "200748.99232287",
        "period_in_days": 1
      }
    },
    "secure3d_buy": {
      "BAT": {
        "max": "1450.00481776",
        "remaining": "1450.00481776",
        "period_in_days": 7
      }
    },
    "exchange_withdraw": {
      "BAT": {
        "max": "220733.98464574",
        "remaining": "220733.98464574",
        "period_in_days": 1
      }
    },
    "exchange_ach": {
      "BAT": {
        "max": "21267.54245368",
        "remaining": "21267.54245368",
        "period_in_days": 7
      }
    },
    "paypal_withdrawal": {
      "BAT": {
        "max": "200748.99232287",
        "remaining": "200748.99232287",
        "period_in_days": 1
      }
    },
    "instant_ach_withdrawal": {
      "BAT": {
        "max": "1103.66992323",
        "remaining": "1103.66992323",
        "period_in_days": 1
      }
    },
    "buy": {
      "BAT": {
        "max": "212677.90003268",
        "remaining": "212677.90003268",
        "period_in_days": 7
      }
    },
    "sell": {
      "BAT": {
        "max": "212677.90003268",
        "remaining": "212677.90003268",
        "period_in_days": 7
      }
    }
  }
}

HTTP request

GET /users/self/exchange-limits

This request will return information on your payment method transfer limits, as well as buy/sell limits per currency.

Deposits

List Deposits

[
  {
    "id": "6cca6a14-a5e3-4219-9542-86123fc9d6c3",
    "type": "deposit",
    "created_at": "2019-06-18 01:37:48.78953+00",
    "completed_at": "2019-06-18 01:37:49.756147+00",
    "canceled_at": null,
    "processed_at": "2019-06-18 01:37:49.756147+00",
    "account_id": "bf091906-ca7f-499e-95fa-5bc15e918b46",
    "user_id": "5eeac63c90b913bf3cf7c92e",
    "user_nonce": null,
    "amount": "40.00000000",
    "details": {
      "crypto_address": "rw2ciyaNshpHe7bCHo4bRWq6pqqynnWKQg",
      "destination_tag": "379156162",
      "coinbase_account_id": "7f8803e2-1be5-4a29-bfd2-3bc6645f5a24",
      "destination_tag_name": "XRP Tag",
      "crypto_transaction_id": "5eeac64cc46b34f5332e5326",
      "coinbase_transaction_id": "5eeac652be6cf8b17f7625bd",
      "crypto_transaction_hash": "B918BF044B6ADA318B36F4F23E7EB141C15BF2B6CFB96FDFC674E907FE235FB1"
    }
  },
  ...
]
[
  {
    "id": "6b09bf5e-c94c-405b-b7dc-ad2b27749ce5",
    "type": "internal_deposit",
    "created_at": "2021-02-08 21:33:14.23887+00",
    "account_id": "bcf1fc34-3180-4acf-97be-c1c20a719e34",
    "user_id": "5eeace07a181d1e866db83e5",
    "amount": "3.0000000000000000",
    "currency": "USD"
  },
  ...
]

Get a list of deposits from the profile of the API key, in descending order by created time. See the Pagination section for retrieving additional entries after the first page.

HTTP request

GET /transfers

API Key Permissions

This endpoint requires either the "view" or "trade" permission.

Query Parameters

You can request deposits within a certain time range using query parameters.

Single Deposit

{
  "id": "6cca6a14-a5e3-4219-9542-86123fc9d6c3",
  "type": "deposit",
  "created_at": "2019-06-18 01:37:48.78953+00",
  "completed_at": "2019-06-18 01:37:49.756147+00",
  "canceled_at": null,
  "processed_at": "2019-06-18 01:37:49.756147+00",
  "account_id": "bf091906-ca7f-499e-95fa-5bc15e918b46",
  "user_id": "5eeac63c90b913bf3cf7c92e",
  "user_nonce": null,
  "amount": "40.00000000",
  "details": {
    "crypto_address": "rw2ciyaNshpHe7bCHo4bRWq6pqqynnWKQg",
    "destination_tag": "379156162",
    "coinbase_account_id": "7f8803e2-1be5-4a29-bfd2-3bc6645f5a24",
    "destination_tag_name": "XRP Tag",
    "crypto_transaction_id": "5eeac64cc46b34f5332e5326",
    "coinbase_transaction_id": "5eeac652be6cf8b17f7625bd",
    "crypto_transaction_hash": "B918BF044B6ADA318B36F4F23E7EB141C15BF2B6CFB96FDFC674E907FE235FB1"
  }
}

Get information on a single deposit.

HTTP request

GET /transfers/:transfer_id

API Key Permissions

This endpoint requires either the "view" or "trade" permission.

Payment method

Request

{
    "amount": 10.00,
    "currency": "USD",
    "payment_method_id": "bc677162-d934-5f1a-968c-a496b1c1270b"
}

Response

{
    "id": "593533d2-ff31-46e0-b22e-ca754147a96a",
    "amount": "10.00",
    "currency": "USD",
    "payout_at": "2016-08-20T00:31:09Z"
}

Deposit funds from a payment method. See the Payment Methods section for retrieving your payment methods.

HTTP request

POST /deposits/payment-method

API Key Permissions

This endpoint requires the "transfer" permission. API key must belong to default profile.

Parameters

Coinbase

Request

{
    "amount": 10.00,
    "currency": "BTC",
    "coinbase_account_id": "c13cd0fc-72ca-55e9-843b-b84ef628c198",
}

Response

{
    "id": "593533d2-ff31-46e0-b22e-ca754147a96a",
    "amount": "10.00",
    "currency": "BTC",
}

Deposit funds from a coinbase account. You can move funds between your Coinbase accounts and your Coinbase Pro trading accounts within your daily limits. Moving funds between Coinbase and Coinbase Pro is instant and free. See the Coinbase Accounts section for retrieving your Coinbase accounts.

HTTP request

POST /deposits/coinbase-account

API Key Permissions

This endpoint requires the "transfer" permission. API key must belong to default profile.

Parameters

Generate a Crypto Deposit Address

{
    "id": "7b147f5d-79de-4d3b-b116-446b259f8765",
    "address": "cx3iotaZqweMa7bABi4bRWq6rpponnOIFa",
    "destination_tag": "3299925630",
    "address_info": {
        "address": "cx3iotaZqweMa7bABi4bRWq6rpponnOIFa",
        "destination_tag": "4938102"
    },
    "created_at": "2020-06-17T20:35:38Z",
    "updated_at": "2020-06-17T20:35:38Z",
    "network": "ripple",
    "resource": "address",
    "deposit_uri": "xrp:cx3iotaZqweMa7bABi4bRWq6rpponnOIFa?dt=4938102",
    "exchange_deposit_address": true
}

You can generate an address for crypto deposits. See the Coinbase Accounts section for information on how to retrieve your coinbase account ID.

HTTP request

POST /coinbase-accounts/<coinbase-account-id>/addresses

API Key Permissions

This endpoint requires the "transfer" permission. API key must belong to default profile.

Withdrawals

List Withdrawals

[
  {
    "id": "6b09bf5e-c94c-405b-b7dc-ad2b27749ce5",
    "type": "withdraw",
    "created_at": "2019-06-18 02:11:25.610908+00",
    "completed_at": "2019-06-18 02:11:26.416758+00",
    "canceled_at": null,
    "processed_at": "2019-06-18 02:11:37.996052+00",
    "account_id": "bcf1fc34-3180-4acf-97be-c1c20a719e34",
    "user_id": "5eeace07a181d1e866db83e5",
    "user_nonce": "1592624441614",
    "amount": "22.01",
    "details": {
      "destination_tag": "567148403",
      "sent_to_address": "rw2ciyaNshpHe7bCHo4bRWq6pqqynnWKQg",
      "coinbase_account_id": "26dbbe94-7321-4ca4-8744-622f5a98a45a",
      "destination_tag_name": "XRP Tag",
      "coinbase_withdrawal_id": "935107c5-b443-4cf4-b9ef-e49f856c4de8",
      "coinbase_transaction_id": "5eeace0cfe2410af68891bcb",
      "crypto_transaction_hash": "217AF4782DFB632121F1EAEF33DBAEC0539A77E5CBFCBA4AA71925ADB2B15D13",
      "coinbase_payment_method_id": "",
      "fee": ".01",
      "subtotal": "22.00",
    }
  },
  ...
]
[
  {
    "id": "6b09bf5e-c94c-405b-b7dc-ad2b27749ce5",
    "type": "internal_withdraw",
    "created_at": "2021-02-08 21:33:14.23887+00",
    "account_id": "bcf1fc34-3180-4acf-97be-c1c20a719e34",
    "user_id": "5eeace07a181d1e866db83e5",
    "amount": "3.0000000000000000",
    "currency": "USD"
  },
  ...
]

Get a list of withdrawals from the profile of the API key, in descending order by created time. See the Pagination section for retrieving additional entries after the first page.

HTTP request

GET /transfers

API Key Permissions

This endpoint requires either the "view" or "trade" permission.

Query Parameters

You can request withdrawals within a certain time range using query parameters.

Single Withdrawal

{
  "id": "6b09bf5e-c94c-405b-b7dc-ad2b27749ce5",
  "type": "withdraw",
  "created_at": "2019-06-18 02:11:25.610908+00",
  "completed_at": "2019-06-18 02:11:26.416758+00",
  "canceled_at": null,
  "processed_at": "2019-06-18 02:11:37.996052+00",
  "account_id": "bcf1fc34-3180-4acf-97be-c1c20a719e34",
  "user_id": "5eeace07a181d1e866db83e5",
  "user_nonce": "1592624441614",
  "amount": "22.01",
  "details": {
    "destination_tag": "567148403",
    "sent_to_address": "rw2ciyaNshpHe7bCHo4bRWq6pqqynnWKQg",
    "coinbase_account_id": "26dbbe94-7321-4ca4-8744-622f5a98a45a",
    "destination_tag_name": "XRP Tag",
    "coinbase_withdrawal_id": "935107c5-b443-4cf4-b9ef-e49f856c4de8",
    "coinbase_transaction_id": "5eeace0cfe2410af68891bcb",
    "crypto_transaction_hash": "217AF4782DFB632121F1EAEF33DBAEC0539A77E5CBFCBA4AA71925ADB2B15D13",
    "fee": ".01",
    "subtotal": "22.00",
    "coinbase_payment_method_id": ""
  }
}

Get information on a single withdrawal.

HTTP request

GET /transfers/:transfer_id

API Key Permissions

This endpoint requires either the "view" or "trade" permission.

Canceled Withdrawal

{
  "id": "6b09bf5e-c94c-405b-b7dc-ad2b27749ce5",
  "type": "withdraw",
  "created_at": "2019-06-18 02:11:25.610908+00",
  "completed_at": null,
  "canceled_at": "2019-06-18 02:11:26.416758+00",
  "processed_at": "2019-06-18 02:11:37.996052+00",
  "account_id": "bcf1fc34-3180-4acf-97be-c1c20a719e34",
  "user_id": "5eeace07a181d1e866db83e5",
  "user_nonce": "1592624441614",
  "amount": "22.01",
  "details": {
    "destination_tag": "567148403",
    "sent_to_address": "rw2ciyaNshpHe7bCHo4bRWq6pqqynnWKQg",
    "coinbase_account_id": "26dbbe94-7321-4ca4-8744-622f5a98a45a",
    "destination_tag_name": "XRP Tag",
    "coinbase_withdrawal_id": "935107c5-b443-4cf4-b9ef-e49f856c4de8",
    "coinbase_transaction_id": "5eeace0cfe2410af68891bcb",
    "crypto_transaction_hash": "217AF4782DFB632121F1EAEF33DBAEC0539A77E5CBFCBA4AA71925ADB2B15D13",
    "coinbase_payment_method_id": "",
    "fee": ".01",
    "subtotal": "22.00",
    "cancel_code": 2007,
  }
}

Withdrawals are created and processed asynchronously. After creating a withdrawal, it is important to query for that transfer and check if it's been completed or canceled.

If the withdrawal is canceled, you can check the error in the details.cancel_code field.

Cancel codes

Below is a map from the cancel code to the cancellation reason. 1xxx cancel codes are for fiat transfers and 2xxx cancel codes are for crypto transfer. Please make changes accordingly before retrying the withdrawal.

0: Default error

1000: This transaction exceeds the transaction limit.

1001: You must enter an amount greater than 0.

1002: Cannot withdraw using that account.

1003: Cannot withdraw using that payment method.

1004: Cannot withdraw this currency with this payment method.

1005: Amount is too large. You don't have enough funds in your account.

1006: Amount must be at least 1.00.

1007: Please enter a larger amount.

1008: The selected payment method cannot be used with recurring transfers.

1009: You must enter a currency that matches the account currency.

1010: That payment method cannot be used.

1011: You are creating transfers too fast. Please wait and try again in a few hours.

1012: The provided amount would exceed your maximum account balance. Please choose a lower amount.

1013: Please enter a positive amount.

2000: Warning: the recipient may lose your funds if you don’t include a tag name. Please confirm that a tag name isn’t required by your recipient.

2004: This would put you over our send limits. Please try a smaller amount or try again later.

2005: You've reached the maximum number of sends per hour. Please contact support if you require a higher limit on your account.

2007: The send amount is below the minimum amount required to send on-blockchain.

2008: Two-step verification code required to complete this request. Re-play the request with CB-2FA-Token header.

2009: A tag name is required to send this currency.

2010: You must enter a valid amount.

2011: Sending this currency is temporarily disabled.

2012: Amount must be less than the maximum withdrawal amount for that currency.

2013: Amount must be less than the maximum send amount for that currency.

2014: Sending from fiat accounts is temporarily disabled.

2015: This payment request has expired.

2016: You cannot send from this account.

2017: You are currently unable to send to this address.

2018: This recipient address isn't whitelisted.

2020: This recipient address has been added to your Whitelist and is pending 48 hour hold.

2021: You are currently unable to send to this user.

2022: You can't send a payment from an account to itself.

2023: You are sending too fast. Please wait for some transactions to confirm before sending more.

2024: Please enter a valid email or network address.

2025: This user's account is not configured to support this currency at this time.

Payment method

Request

{
    "amount": 10.00,
    "currency": "USD",
    "payment_method_id": "bc677162-d934-5f1a-968c-a496b1c1270b"
}

Response

{
    "id":"593533d2-ff31-46e0-b22e-ca754147a96a",
    "amount": "10.00",
    "currency": "USD",
    "payout_at": "2016-08-20T00:31:09Z"
}

Withdraw funds to a payment method. See the Payment Methods section for retrieving your payment methods.

HTTP request

POST /withdrawals/payment-method

API Key Permissions

This endpoint requires the "transfer" permission. API key is restricted to the default profile.

Parameters

Coinbase

Request

{
    "amount": 10.00,
    "currency": "BTC",
    "coinbase_account_id": "c13cd0fc-72ca-55e9-843b-b84ef628c198",
}

Response

{
    "id":"593533d2-ff31-46e0-b22e-ca754147a96a",
    "amount":"10.00",
    "currency": "BTC",
}

Withdraw funds to a coinbase account. You can move funds between your Coinbase accounts and your Coinbase Pro trading accounts within your daily limits. Moving funds between Coinbase and Coinbase Pro is instant and free. See the Coinbase Accounts section for retrieving your Coinbase accounts.

HTTP request

POST /withdrawals/coinbase-account

API Key Permissions

This endpoint requires the "transfer" permission.

Parameters

Crypto

Request

{
    "amount": 10.00,
    "currency": "BTC",
    "crypto_address": "0x5ad5769cd04681FeD900BCE3DDc877B50E83d469"
}

Response

{
    "id":"593533d2-ff31-46e0-b22e-ca754147a96a",
    "amount":"10.01",
    "currency": "BTC",
    "fee": ".01",
    "subtotal": "10.00",
}

Withdraws funds to a crypto address.

HTTP request

POST /withdrawals/crypto

API Key Permissions

This endpoint requires the "transfer" permission. API key must belong to default profile.

Parameters

Fee Estimate

Request

{
    "currency": "BTC",
    "crypto_address": "0x5ad5769cd04681FeD900BCE3DDc877B50E83d469"
}

Response

{
    "fee":".01",
}

Gets the network fee estimate when sending to the given address.

HTTP request

GET /withdrawals/fee-estimate

API Key Permissions

This endpoint requires the "transfer" permission. API key must belong to default profile.

Query Parameters

Stablecoin Conversions

Create Conversion

Request

{
    "from": "USD",
    "to": "USDC",
    "amount": "10000.00"
}

Response

{
    "id": "8942caee-f9d5-4600-a894-4811268545db",
    "amount": "10000.00",
    "from_account_id": "7849cc79-8b01-4793-9345-bc6b5f08acce",
    "to_account_id": "105c3e58-0898-4106-8283-dc5781cda07b",
    "from": "USD",
    "to": "USDC"
}

Convert $10,000.00 to 10,000.00 USDC.

HTTP Request

POST /conversions

API Key Permissions

This endpoint requires the "trade" permission.

Parameters

Response

A successful conversion will be assigned a conversion id. The corresponding ledger entries for a conversion will reference this conversion id.

Payment Methods

List Payment Methods

[
    {
        "id": "bc6d7162-d984-5ffa-963c-a493b1c1370b",
        "type": "ach_bank_account",
        "name": "Bank of America - eBan... ********7134",
        "currency": "USD",
        "primary_buy": true,
        "primary_sell": true,
        "allow_buy": true,
        "allow_sell": true,
        "allow_deposit": true,
        "allow_withdraw": true,
        "limits": {
            "buy": [
                {
                    "period_in_days": 1,
                    "total": {
                        "amount": "10000.00",
                        "currency": "USD"
                    },
                    "remaining": {
                        "amount": "10000.00",
                        "currency": "USD"
                    }
                }
            ],
            "instant_buy": [
                {
                    "period_in_days": 7,
                    "total": {
                        "amount": "0.00",
                        "currency": "USD"
                    },
                    "remaining": {
                        "amount": "0.00",
                        "currency": "USD"
                    }
                }
            ],
            "sell": [
                {
                    "period_in_days": 1,
                    "total": {
                        "amount": "10000.00",
                        "currency": "USD"
                    },
                    "remaining": {
                        "amount": "10000.00",
                        "currency": "USD"
                    }
                }
            ],
            "deposit": [
                {
                    "period_in_days": 1,
                    "total": {
                        "amount": "10000.00",
                        "currency": "USD"
                    },
                    "remaining": {
                        "amount": "10000.00",
                        "currency": "USD"
                    }
                }
            ]
        }
    },
]

Get a list of your payment methods.

HTTP Request

GET /payment-methods

API Key Permissions

This endpoint requires the "transfer" permission.

Coinbase Accounts

List Accounts

[
    {
        "id": "fc3a8a57-7142-542d-8436-95a3d82e1622",
        "name": "ETH Wallet",
        "balance": "0.00000000",
        "currency": "ETH",
        "type": "wallet",
        "primary": false,
        "active": true
    },
    {
        "id": "2ae3354e-f1c3-5771-8a37-6228e9d239db",
        "name": "USD Wallet",
        "balance": "0.00",
        "currency": "USD",
        "type": "fiat",
        "primary": false,
        "active": true,
        "wire_deposit_information": {
            "account_number": "0199003122",
            "routing_number": "026013356",
            "bank_name": "Metropolitan Commercial Bank",
            "bank_address": "99 Park Ave 4th Fl New York, NY 10016",
            "bank_country": {
                "code": "US",
                "name": "United States"
            },
            "account_name": "Coinbase, Inc",
            "account_address": "548 Market Street, #23008, San Francisco, CA 94104",
            "reference": "BAOCAEUX"
        }
    },
    {
        "id": "1bfad868-5223-5d3c-8a22-b5ed371e55cb",
        "name": "BTC Wallet",
        "balance": "0.00000000",
        "currency": "BTC",
        "type": "wallet",
        "primary": true,
        "active": true
    },
    {
        "id": "2a11354e-f133-5771-8a37-622be9b239db",
        "name": "EUR Wallet",
        "balance": "0.00",
        "currency": "EUR",
        "type": "fiat",
        "primary": false,
        "active": true,
        "sepa_deposit_information": {
            "iban": "EE957700771001355096",
            "swift": "LHVBEE22",
            "bank_name": "AS LHV Pank",
            "bank_address": "Tartu mnt 2, 10145 Tallinn, Estonia",
            "bank_country_name": "Estonia",
            "account_name": "Coinbase UK, Ltd.",
            "account_address": "9th Floor, 107 Cheapside, London, EC2V 6DN, United Kingdom",
            "reference": "CBAEUXOVFXOXYX"
        }
    },
    ...
]

Get a list of your coinbase accounts.

Visit the Coinbase accounts API for more information.

HTTP Request

GET /coinbase-accounts

API Key Permissions

This endpoint requires either the "view" or "transfer" permission.

Fees

Get Current Fees

[
    {
        "maker_fee_rate": "0.0015",
        "taker_fee_rate": "0.0025",
        "usd_volume": "25000.00"
    }
]

HTTP request

GET /fees

This request will return your current maker & taker fee rates, as well as your 30-day trailing volume. Quoted rates are subject to change. More information on fees can found on our support page.

Reports

Create a new report

Request

{
    "type": "fills",
    "start_date": "2014-11-01T00:00:00.000Z",
    "end_date": "2014-11-30T23:59:59.000Z"
}

Response

{
    "id": "0428b97b-bec1-429e-a94c-59232926778d",
    "type": "fills",
    "status": "pending",
    "created_at": "2015-01-06T10:34:47.000Z",
    "completed_at": undefined,
    "expires_at": "2015-01-13T10:35:47.000Z",
    "file_url": undefined,
    "params": {
        "start_date": "2014-11-01T00:00:00.000Z",
        "end_date": "2014-11-30T23:59:59.000Z"
    }
}

Reports provide batches of historic information about your profile in various human and machine readable forms.

HTTP request

POST /reports

API Key Permissions

This endpoint requires either the "view" or "trade" permission.

Parameters

The report will be generated when resources are available. Report status can be queried via the /reports/:report_id endpoint. The file_url field will be available once the report has successfully been created and is available for download.

Expired reports

Reports are only available for download for a few days after being created. Once a report expires, the report is no longer available for download and is deleted.

Get report status

Response (creating report)

{
    "id": "0428b97b-bec1-429e-a94c-59232926778d",
    "type": "fills",
    "status": "creating",
    "created_at": "2015-01-06T10:34:47.000Z",
    "completed_at": undefined,
    "expires_at": "2015-01-13T10:35:47.000Z",
    "file_url": undefined,
    "params": {
        "start_date": "2014-11-01T00:00:00.000Z",
        "end_date": "2014-11-30T23:59:59.000Z"
    }
}

Response (finished report)

{
    "id": "0428b97b-bec1-429e-a94c-59232926778d",
    "type": "fills",
    "status": "ready",
    "created_at": "2015-01-06T10:34:47.000Z",
    "completed_at": "2015-01-06T10:35:47.000Z",
    "expires_at": "2015-01-13T10:35:47.000Z",
    "file_url": "https://example.com/0428b97b.../fills.pdf",
    "params": {
        "start_date": "2014-11-01T00:00:00.000Z",
        "end_date": "2014-11-30T23:59:59.000Z"
    }
}

HTTP request

GET /reports/:report_id

Once a report request has been accepted for processing, the status is available by polling the report resource endpoint.

The final report will be uploaded and available at file_url once the status indicates ready

API Key Permissions

This endpoint requires either the "view" or "trade" permission.

Status

Profiles

Profiles are equivalent to portfolios. A user can have a max of 10 profiles.

List Profiles

[
    {
        "id": "86602c68-306a-4500-ac73-4ce56a91d83c",
        "user_id": "5844eceecf7e803e259d0365",
        "name": "default",
        "active": true,
        "is_default": true,
        "created_at": "2019-11-18T15:08:40.236309Z"
    }
]

List your profiles.

HTTP Request

GET /profiles

API Key Permissions

This endpoint requires the "view" permission and is accessible by any profile's API key.

Parameters

Get a Profile

{
    "id": "86602c68-306a-4500-ac73-4ce56a91d83c",
    "user_id": "5844eceecf7e803e259d0365",
    "name": "default",
    "active": true,
    "is_default": true,
    "created_at": "2019-11-18T15:08:40.236309Z"
}

Get a single profile by profile id.

HTTP Request

GET /profiles/<profile_id>

API Key Permissions

This endpoint requires the "view" permission and is accessible by any profile's API key.

Create profile transfer

{
    "from": "86602c68-306a-4500-ac73-4ce56a91d83c",
    "to": "e87429d3-f0a7-4f28-8dff-8dd93d383de1",
    "currency": "BTC",
    "amount": "1000.00"
}

Transfer funds from API key's profile to another user owned profile.

HTTP request

POST /profiles/transfer

API Key Permissions

This endpoint requires the "transfer" permission.

Parameters

Oracle

Response

{
    "timestamp": "1583195520",
    "messages": [
        "0x0000000000000000000000000000000000000000000000000000000000000080000000000000000000000000000000000000000000000000000000005e5da58000000000000000000000000000000000000000000000000000000000000000c0000000000000000000000000000000000000000000000000000000020f3570580000000000000000000000000000000000000000000000000000000000000006707269636573000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000034254430000000000000000000000000000000000000000000000000000000000",
        "0x0000000000000000000000000000000000000000000000000000000000000080000000000000000000000000000000000000000000000000000000005e5da58000000000000000000000000000000000000000000000000000000000000000c0000000000000000000000000000000000000000000000000000000000da3f9500000000000000000000000000000000000000000000000000000000000000006707269636573000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000034554480000000000000000000000000000000000000000000000000000000000"
    ],
    "signatures": [
        "0x8318875F720F88683B75C949A1E83FCEFBD586AE8A8276944F126CDBA176F3844B05C92D1B4393DCF1DAD2D59B88F196C9ABA988141265BDACBFDBC90049FA211c",
        "0x69BD1ECDF391B2A24D61C8FAB6FF1874DCC5CDCFB1B691DC14BC288503B0B460F43F5CDD83615B0D3E785110279A85C75E19C6ED3A645DC9A084B9BC6B8584BE1b"
    ],
    "prices": {
        "BTC": "8845.095000000001",
        "ETH": "228.85",
    }
}

Get cryptographically signed prices ready to be posted on-chain using Open Oracle smart contracts.

HTTP request

GET /oracle

API Key Permissions

This endpoint requires the “view” permission and is accessible by any profile’s API key.

Details

• timestamp field indicates when the latest datapoint was obtained.
• messages array contains abi-encoded values [kind, timestamp, key, value], where kind always equals to 'prices', timestamp is the time when the price was obtained, key is asset ticker (e.g. 'eth') and value is asset price.
• signatures is an array of Ethereum-compatible ECDSA signatures for each message.
• prices contains human-readable asset prices.

Decoding Messages

Decoding messages

import { Reporter } from 'open-oracle-reporter';

let messages = ['0x0000000000000000000000000000000000000000000000000000000000000080000000000000000000000000000000000000000000000000000000005e5da58000000000000000000000000000000000000000000000000000000000000000c0000000000000000000000000000000000000000000000000000000020f3570580000000000000000000000000000000000000000000000000000000000000006707269636573000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000034254430000000000000000000000000000000000000000000000000000000000'];

let decoded = Reporter.decode('prices', messages);
// [ [ '1583195520', 'BTC', '8845095000' ] ]

Messages can be decoded using the Open Oracle Reporter JavaScript library.

Each message encodes values [kind, timestamp, key, value], where kind always equals to 'prices', timestamp is the time when the price was obtained, key is asset ticker (e.g. 'eth') and value is a 6-decimal precision encoded price.

Recovering Signatory

Recovering signer public key

import Web3 from 'web3';
const web3 = new Web3(null); // This is just for encoding, etc.

const COINBASE_ORACLE_PUBLIC_KEY = '0xfCEAdAFab14d46e20144F48824d0C09B1a03F2BC';

let messages = ['0x0000000000000000000000000000000000000000000000000000000000000080000000000000000000000000000000000000000000000000000000005e5da58000000000000000000000000000000000000000000000000000000000000000c0000000000000000000000000000000000000000000000000000000020f3570580000000000000000000000000000000000000000000000000000000000000006707269636573000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000034254430000000000000000000000000000000000000000000000000000000000'];
let signatures = ['0x8318875F720F88683B75C949A1E83FCEFBD586AE8A8276944F126CDBA176F3844B05C92D1B4393DCF1DAD2D59B88F196C9ABA988141265BDACBFDBC90049FA211c'];

let hash = web3.utils.keccak256(messages[0]);
let signatory = web3.eth.accounts.recover(hash, signatures[0]);
const isValid = signatory == COINBASE_ORACLE_PUBLIC_KEY;

The public key used to produce a signature can be directly obtained from the signature and the corresponding message. The signature format is Web3 and EVM / Solidity -friendly.

Posting data on-chain

Posting data on-chain

import poster from 'delfi-poster';
import Web3 from 'web3';

// let posterKey = ...a key to a wallet holding eth for gas;
// let viewAddress = "0xDelfiPriceView";
// let viewFunction = ...view function signature e.g. 'postPrices(bytes[],bytes[],string[])';
// let web3Provider = new Web3("web3Node.com", undefined, {transactionPollingTimeout: 180});
const payloads = [{...oracle_response...}];
const gasPrice = await poster.fetchGasPrice();
const trxData = poster.buildTrxData(payloads, viewFunction);

const trx = {
    data: trxData,
    to: viewAddress,
    gasPrice: gasPrice
}

await poster.postWithRetries(trx, posterKey, web3Provider);

Open Oracle provides a Poster utility app that simplifies submitting signed messages from the Oracle API on-chain using a DelFiPrice contract. This requires an Ethereum address with some ETH to pay for gas.

Market Data

The Market Data API is an unauthenticated set of endpoints for retrieving market data. These endpoints provide snapshots of market data.

Products

Get Products

[
    {
        "id": "BTC-USD",
        "display_name": "BTC/USD",
        "base_currency": "BTC",
        "quote_currency": "USD",
        "base_increment": "0.00000001",
        "quote_increment": "0.01000000",
        "base_min_size": "0.00100000",
        "base_max_size": "280.00000000",
        "min_market_funds": "5",
        "max_market_funds": "1000000",
        "status": "online",
        "status_message": "",
        "cancel_only": false,
        "limit_only": false,
        "post_only": false,
        "trading_disabled": false
    },
    ...
]

Get a list of available currency pairs for trading.

HTTP Request

GET /products

Details

The base_min_size and base_max_size fields define the min and max order size.

The min_market_funds and max_market_funds fields define the min and max funds allowed in a market order.

status_message provides any extra information regarding the status if available.

The quote_increment field specifies the min order price as well as the price increment.

The order price must be a multiple of this increment (i.e. if the increment is 0.01, order prices of 0.001 or 0.021 would be rejected).

The base_increment field specifies the minimum increment for the base_currency.

trading_disabled indicates whether trading is currently restricted on this product, this includes whether both new orders and order cancelations are restricted.

cancel_only indicates whether this product only accepts cancel requests for orders.

post_only indicates whether only maker orders can be placed. No orders will be matched when post_only mode is active.

limit_only indicates whether this product only accepts limit orders.

Only a maximum of one of trading_disabled, cancel_only, post_only, limit_only can be true at once. If none are true, the product is trading normally.

Get Single Product

{
    "id": "BTC-USD",
    "display_name": "BTC/USD",
    "base_currency": "BTC",
    "quote_currency": "USD",
    "base_increment": "0.00000001",
    "quote_increment": "0.01000000",
    "base_min_size": "0.00100000",
    "base_max_size": "280.00000000",
    "min_market_funds": "5",
    "max_market_funds": "1000000",
    "status": "online",
    "status_message": "",
    "cancel_only": false,
    "limit_only": false,
    "post_only": false,
    "trading_disabled": false
}

Get market data for a specific currency pair.

HTTP Request

GET /products/<product-id>

Get Product Order Book

Example Response for /products/BTC-USD/book Only the best bid and ask is returned.

{
    "sequence": "3",
    "bids": [
        [ price, size, num-orders ],
    ],
    "asks": [
        [ price, size, num-orders ],
    ]
}

Example Response for /products/BTC-USD/book?level=2

{
    "sequence": "3",
    "bids": [
        [ price, size, num-orders ],
        [ "295.96", "4.39088265", 2 ],
        ...
    ],
    "asks": [
        [ price, size, num-orders ],
        [ "295.97", "25.23542881", 12 ],
        ...
    ]
}

Example Response for /products/BTC-USD/book?level=3

{
    "sequence": "3",
    "bids": [
        [ price, size, order_id ],
        [ "295.96","0.05088265","3b0f1225-7f84-490b-a29f-0faef9de823a" ],
        ...
    ],
    "asks": [
        [ price, size, order_id ],
        [ "295.97","5.72036512","da863862-25f4-4868-ac41-005d11ab0a5f" ],
        ...
    ]
}

Get a list of open orders for a product. The amount of detail shown can be customized with the level parameter.

HTTP Request

GET /products/<product-id>/book

Details

By default, only the inside (i.e. best) bid and ask are returned. This is equivalent to a book depth of 1 level. If you would like to see a larger order book, specify the level query parameter.

If a level is not aggregated, then all of the orders at each price will be returned. Aggregated levels return only one size for each active price (as if there was only a single order for that size at the level).

Parameters

Levels

Levels 1 and 2 are aggregated. The size field is the sum of the size of the orders at that price, and num-orders is the count of orders at that price; size should not be multiplied by num-orders.

Level 3 is non-aggregated and returns the entire order book.

Get Product Ticker

{
  "trade_id": 4729088,
  "price": "333.99",
  "size": "0.193",
  "bid": "333.98",
  "ask": "333.99",
  "volume": "5957.11914015",
  "time": "2015-11-14T20:46:03.511254Z"
}

Snapshot information about the last trade (tick), best bid/ask and 24h volume.

HTTP request

GET /products/<product-id>/ticker

Real-time updates

Polling is discouraged in favor of connecting via the websocket stream and listening for match messages.

Get Trades

[{
    "time": "2014-11-07T22:19:28.578544Z",
    "trade_id": 74,
    "price": "10.00000000",
    "size": "0.01000000",
    "side": "buy"
}, {
    "time": "2014-11-07T01:08:43.642366Z",
    "trade_id": 73,
    "price": "100.00000000",
    "size": "0.01000000",
    "side": "sell"
}]

List the latest trades for a product.

HTTP request

GET /products/<product-id>/trades

Side

The trade side indicates the maker order side. The maker order is the order that was open on the order book. buy side indicates a down-tick because the maker was a buy order and their order was removed. Conversely, sell side indicates an up-tick.

Get Historic Rates

[
    [ time, low, high, open, close, volume ],
    [ 1415398768, 0.32, 4.2, 0.35, 4.2, 12.3 ],
    ...
]

Historic rates for a product. Rates are returned in grouped buckets based on requested granularity.

HTTP request

GET /products/<product-id>/candles

Parameters

Details

If either one of the start or end fields are not provided then both fields will be ignored. If a custom time range is not declared then one ending now is selected.

The granularity field must be one of the following values: {60, 300, 900, 3600, 21600, 86400}. Otherwise, your request will be rejected. These values correspond to timeslices representing one minute, five minutes, fifteen minutes, one hour, six hours, and one day, respectively.

Response Items

Each bucket is an array of the following information:

• time bucket start time
• low lowest price during the bucket interval
• high highest price during the bucket interval
• open opening price (first trade) in the bucket interval
• close closing price (last trade) in the bucket interval
• volume volume of trading activity during the bucket interval

Get 24hr Stats

{
    "open": "6745.61000000", 
    "high": "7292.11000000", 
    "low": "6650.00000000", 
    "volume": "26185.51325269", 
    "last": "6813.19000000", 
    "volume_30day": "1019451.11188405"
}

Get 24 hr stats for the product. volume is in base currency units. open, high, low are in quote currency units.

HTTP request

GET /products/<product-id>/stats

Currencies

Get currencies

[{
    "id": "BTC",
    "name": "Bitcoin",
    "min_size": "0.00000001",
    "status": "online",
    "message": "",
    "max_precision": "0.01",
    "convertible_to": [],
    "details": {
        "type": "crypto",
        "symbol": "₿",
        "network_confirmations": 3,
        "sort_order": 3,
        "crypto_address_link": "https://live.blockcypher.com/btc/address/{{address}}",
        "crypto_transaction_link": "https://live.blockcypher.com/btc/tx/{{txId}}",
        "push_payment_methods": [
            "crypto"
        ],
        "group_types": [
            "btc",
            "crypto"
        ],
        "display_name": "",
        "processing_time_seconds": 0,
        "min_withdrawal_amount": 0,
        "max_withdrawal_amount": 1000
    }
}, {
    "id": "USD",
    "name": "United States Dollar",
    "min_size": "0.01000000",
    "status": "online",
    "message": "",
    "max_precision": "0.01",
    "convertible_to": [
        "USDC"
    ],
    "details": {
        "type": "fiat",
        "symbol": "$",
        "network_confirmations": 0,
        "sort_order": 0,
        "crypto_address_link": "",
        "crypto_transaction_link": "",
        "push_payment_methods": [
            "bank_wire",
            "fedwire",
            "swift_bank_account",
            "intra_bank_account"
        ],
        "group_types": [
            "fiat",
            "usd"
        ],
        "display_name": "US Dollar",
        "processing_time_seconds": 0,
        "min_withdrawal_amount": 0
    }
} ... ]

List known currencies.

HTTP request

GET /currencies

Get a currency

{
    "id": "BTC",
    "name": "Bitcoin",
    "min_size": "0.00000001",
    "status": "online",
    "max_precision": "0.01",
    "message": "",
    "details": {
        "type": "crypto",
        "symbol": "₿",
        "network_confirmations": 3,
        "sort_order": 3,
        "crypto_address_link": "https://live.blockcypher.com/btc/address/{{address}}",
        "crypto_transaction_link": "https://live.blockcypher.com/btc/tx/{{txId}}",
        "push_payment_methods": [
            "crypto"
        ],
        "group_types": [
            "btc",
            "crypto"
        ],
    }
}

List the currency for specified id.

HTTP request

GET /currencies/<id>
The field that has empty or default value is omitted except message field

Currency Codes

Currency codes will conform to the ISO 4217 standard where possible. Currencies which have or had no representation in ISO 4217 may use a custom code.

Time

{
    "iso": "2015-01-07T23:47:25.201Z",
    "epoch": 1420674445.201
}

Get the API server time.

HTTP request

GET /time

Epoch

The epoch field represents decimal seconds since Unix Epoch

Websocket Feed

The websocket feed provides real-time market data updates for orders and trades.

wss://ws-feed.pro.coinbase.com

Overview

Real-time market data updates provide the fastest insight into order flow and trades. This however means that you are responsible for reading the message stream and using the message relevant for your needs which can include building real-time order books or tracking real-time trades.

The websocket feed is publicly available, but connections to it are rate-limited to 1 per 4 seconds per IP, messages sent by client on each connection are rate-limited to 100 per second per IP.

Protocol overview

The websocket feed uses a bidirectional protocol, which encodes all messages as JSON objects. All messages have a type attribute that can be used to handle the message appropriately.

Please note that new message types can be added at any point in time. Clients are expected to ignore messages they do not support.

Error messages: Most failure cases will cause an error message (a message with the type "error") to be emitted. This can be helpful for implementing a client or debugging issues.

{
    "type": "error",
    "message": "error message",
    /* ... */
}

Subscribe

// Request
// Subscribe to ETH-USD and ETH-EUR with the level2, heartbeat and ticker channels,
// plus receive the ticker entries for ETH-BTC and ETH-USD
{
    "type": "subscribe",
    "product_ids": [
        "ETH-USD",
        "ETH-EUR"
    ],
    "channels": [
        "level2",
        "heartbeat",
        {
            "name": "ticker",
            "product_ids": [
                "ETH-BTC",
                "ETH-USD"
            ]
        }
    ]
}

To begin receiving feed messages, you must first send a subscribe message to the server indicating which channels and products to receive. This message is mandatory — you will be disconnected if no subscribe has been received within 5 seconds.

There are two ways to specify products ids to listen for within each channel: First, you can specify the product ids for an individual channel. Also, as a shorthand, you can define products ids at the root of the object, which will add them to all the channels you subscribe to.

// Response
{
    "type": "subscriptions",
    "channels": [
        {
            "name": "level2",
            "product_ids": [
                "ETH-USD",
                "ETH-EUR"
            ],
        },
        {
            "name": "heartbeat",
            "product_ids": [
                "ETH-USD",
                "ETH-EUR"
            ],
        },
        {
            "name": "ticker",
            "product_ids": [
                "ETH-USD",
                "ETH-EUR",
                "ETH-BTC"
            ]
        }
    ]
}

Once a subscribe message is received the server will respond with a subscriptions message that lists all channels you are subscribed to.

Subsequent subscribe messages will add to the list of subscriptions. In case you already subscribed to a channel without being authenticated you will remain in the unauthenticated channel.

If you want to unsubscribe from channel/product pairs, send an unsubscribe message. The structure is equivalent to subscribe messages. As a shorthand you can also provide no product ids for a channel, which will unsubscribe you from the channel entirely.

// Request
{
    "type": "unsubscribe",
    "product_ids": [
        "ETH-USD",
        "ETH-EUR"
    ],
    "channels": ["ticker"]
}

// Request
{
    "type": "unsubscribe",
    "channels": ["heartbeat"]
}

As a response to an unsubscribe message you will receive a subscriptions message.

Authentication

It is possible to authenticate yourself when subscribing to the websocket feed.

Authentication will result in a couple of benefits:

1. Messages where you're one of the parties are expanded and have more useful fields
2. You will receive private messages, such as lifecycle information about stop orders you placed

// Authenticated feed messages add user_id and
// profile_id for messages related to your user
{
    "type": "open", // "received" | "open" | "done" | "match" | "change" | "activate"
    "user_id": "5844eceecf7e803e259d0365",
    "profile_id": "765d1549-9660-4be2-97d4-fa2d65fa3352",
    /* ... */
}

Here's an example of an authenticated subscribe request:

// Request
{
    "type": "subscribe",
    "product_ids": [
        "BTC-USD"
    ],
    "channels": ["full"],
    "signature": "...",
    "key": "...",
    "passphrase": "...",
    "timestamp": "..."
}

To authenticate, you send a subscribe message as usual, but you also pass in fields just as if you were signing a request to GET /users/self/verify. To get the necessary parameters, you would go through the same process as you do to make authenticated calls to the API.

The easiest way to connect to an authenticated feed are our gdax-node and GDAX trading toolkit libraries.

Sequence Numbers

Most feed messages contain a sequence number. Sequence numbers are increasing integer values for each product with every new message being exactly 1 sequence number greater than the one before it.

If you see a sequence number that is more than one value from the previous, it means a message has been dropped. A sequence number less than one you have seen can be ignored or has arrived out-of-order. In both situations you may need to perform logic to make sure your system is in the correct state.

Channels

The heartbeat channel

// Request
{
    "type": "subscribe",
    "channels": [{ "name": "heartbeat", "product_ids": ["ETH-EUR"] }]
}

To receive heartbeat messages for specific products once a second subscribe to the heartbeat channel. Heartbeats also include sequence numbers and last trade ids that can be used to verify no messages were missed.

// Heartbeat message
{
    "type": "heartbeat",
    "sequence": 90,
    "last_trade_id": 20,
    "product_id": "BTC-USD",
    "time": "2014-11-07T08:19:28.464459Z"
}

The status channel

// Request
{
    "type": "subscribe",
    "channels": [{ "name": "status"}]
}

The status channel will send all products and currencies on a preset interval.

// Status Message
{
    "type": "status",
    "products": [
        {
            "id": "BTC-USD",
            "base_currency": "BTC",
            "quote_currency": "USD",
            "base_min_size": "0.001",
            "base_max_size": "70",
            "base_increment": "0.00000001",
            "quote_increment": "0.01",
            "display_name": "BTC/USD",
            "status": "online",
            "status_message": null,
            "min_market_funds": "10",
            "max_market_funds": "1000000",
            "post_only": false,
            "limit_only": false,
            "cancel_only": false
        }
    ],
    "currencies": [
        {
            "id": "USD",
            "name": "United States Dollar",
            "min_size": "0.01000000",
            "status": "online",
            "status_message": null,
            "max_precision": "0.01",
            "convertible_to": ["USDC"], "details": {}
        },
        {
            "id": "USDC",
            "name": "USD Coin",
            "min_size": "0.00000100",
            "status": "online",
            "status_message": null,
            "max_precision": "0.000001",
            "convertible_to": ["USD"], "details": {}
        },
        {
            "id": "BTC",
            "name": "Bitcoin",
            "min_size":" 0.00000001",
            "status": "online",
            "status_message": null,
            "max_precision": "0.00000001",
            "convertible_to": []
        }
    ]
}

The ticker channel

The ticker channel provides real-time price updates every time a match happens. It batches updates in case of cascading matches, greatly reducing bandwidth requirements.

{
    "type": "ticker",
    "trade_id": 20153558,
    "sequence": 3262786978,
    "time": "2017-09-02T17:05:49.250000Z",
    "product_id": "BTC-USD",
    "price": "4388.01000000",
    "side": "buy", // Taker side
    "last_size": "0.03000000",
    "best_bid": "4388",
    "best_ask": "4388.01"
}

Please note that more information will be added to messages from this channel in the near future.

The level2 channel

The easiest way to keep a snapshot of the order book is to use the level2 channel. It guarantees delivery of all updates, which reduce a lot of the overhead required when consuming the full channel.

{
    "type": "snapshot",
    "product_id": "BTC-USD",
    "bids": [["10101.10", "0.45054140"]],
    "asks": [["10102.55", "0.57753524"]]
}

When subscribing to the channel it will send a message with the type snapshot and the corresponding product_id. bids and asks are arrays of [price, size] tuples and represent the entire order book.

{
  "type": "l2update",
  "product_id": "BTC-USD",
  "time": "2019-08-14T20:42:27.265Z",
  "changes": [
    [
      "buy",
      "10101.80000000",
      "0.162567"
    ]
  ]
}

Subsequent updates will have the type l2update. The changes property of l2updates is an array with [side, price, size] tuples. The time property of l2update is the time of the event as recorded by our trading engine. Please note that size is the updated size at that price level, not a delta. A size of "0" indicates the price level can be removed.

The user channel

This channel is a version of the full channel that only contains messages that include the authenticated user. Consequently, you need to be authenticated to receive any messages.

The matches channel

If you are only interested in match messages you can subscribe to the matches channel. This is useful when you're consuming the remaining feed using the level 2 channel.

Please note that messages can be dropped from this channel. By using the heartbeat channel you can track the last trade id and fetch trades that you missed from the REST API.

The full channel

The full channel provides real-time updates on orders and trades. These updates can be applied on to a level 3 order book snapshot to maintain an accurate and up-to-date copy of the exchange order book.

An algorithm to maintain an up-to-date level 3 order book is described below. Please note that you will rarely need to implement this yourself.

1. Send a subscribe message for the product(s) of interest and the full channel.
2. Queue any messages received over the websocket stream.
3. Make a REST request for the order book snapshot from the REST feed.
4. Playback queued messages, discarding sequence numbers before or equal to the snapshot sequence number.
5. Apply playback messages to the snapshot as needed (see below).
6. After playback is complete, apply real-time stream messages as they arrive.

The following messages are sent over the websocket stream in JSON format when subscribing to the full channel:

Received

{
    "type": "received",
    "time": "2014-11-07T08:19:27.028459Z",
    "product_id": "BTC-USD",
    "sequence": 10,
    "order_id": "d50ec984-77a8-460a-b958-66f114b0de9b",
    "size": "1.34",
    "price": "502.1",
    "side": "buy",
    "order_type": "limit"
}

{
    "type": "received",
    "time": "2014-11-09T08:19:27.028459Z",
    "product_id": "BTC-USD",
    "sequence": 12,
    "order_id": "dddec984-77a8-460a-b958-66f114b0de9b",
    "funds": "3000.234",
    "side": "buy",
    "order_type": "market"
}

A valid order has been received and is now active. This message is emitted for every single valid order as soon as the matching engine receives it whether it fills immediately or not.

The received message does not indicate a resting order on the order book. It simply indicates a new incoming order which as been accepted by the matching engine for processing. Received orders may cause match message to follow if they are able to begin being filled (taker behavior). Self-trade prevention may also trigger change messages to follow if the order size needs to be adjusted. Orders which are not fully filled or canceled due to self-trade prevention result in an open message and become resting orders on the order book.

Market orders (indicated by the order_type field) may have an optional funds field which indicates how much quote currency will be used to buy or sell. For example, a funds field of 100.00 for the BTC-USD product would indicate a purchase of up to 100.00 USD worth of bitcoin.

Open

{
    "type": "open",
    "time": "2014-11-07T08:19:27.028459Z",
    "product_id": "BTC-USD",
    "sequence": 10,
    "order_id": "d50ec984-77a8-460a-b958-66f114b0de9b",
    "price": "200.2",
    "remaining_size": "1.00",
    "side": "sell"
}

The order is now open on the order book. This message will only be sent for orders which are not fully filled immediately. remaining_size will indicate how much of the order is unfilled and going on the book.

Done

{
    "type": "done",
    "time": "2014-11-07T08:19:27.028459Z",
    "product_id": "BTC-USD",
    "sequence": 10,
    "price": "200.2",
    "order_id": "d50ec984-77a8-460a-b958-66f114b0de9b",
    "reason": "filled", // or "canceled"
    "side": "sell",
    "remaining_size": "0"
}