Welcome to the Coinbase Clearing REST API - Coinbase Developer Documentation

The REST endpoints are listed in the sidebar under REST Endpoints. Every endpoint requires the bearer JWT described in Authentication.

Basics

The Coinbase Clearing REST API provides read-only queries of Coinbase Clearing LLC (CBC) data. All requests and responses use the application/json content type. Every endpoint is a POST that takes a JSON request body.

Resource	Endpoints
Trades	`POST /api/trades/get-derivative-trades`, `POST /api/trades/get-event-trades`
Prices	`POST /api/price/get-page`
Settlement results	`POST /api/settlement-results/get-page`
Positions	`POST /api/event-positions/get-all-positions`
Balances	`POST /api/collateral/balance/get-page`

Paths are relative to the /cdp-api base path. Environments are described on the Coinbase Clearing Connectivity page; REST API host names are not published yet.

Request structure

Every endpoint takes the same top-level request body:

Field	Type	Required	Description
`bookmark`	string	No	Pagination cursor. Use `null` for the first page.
`queryArgs`	object	No	Filter and sort arguments. Use `null` to return all results unfiltered. Structure varies per endpoint.
`rangeLimit`	integer (int32)	Yes	Maximum number of results per page.
`paging`	string	Yes	`NEXT_PAGE` or `PREVIOUS_PAGE`.

A request with no filters:

{
  "bookmark": null,
  "queryArgs": null,
  "rangeLimit": 3,
  "paging": "NEXT_PAGE"
}

Response structure

Every endpoint returns the same top-level response body:

Field	Type	Description
`bookmark`	string	Cursor to fetch the next or previous page.
`content`	array	The page of results. Structure varies per endpoint.
`atEnd`	boolean	`true` when there are no more pages in the current direction.

{
  "bookmark": "eyJsYXN0S2V5IjoiMTAwMyJ9",
  "content": [
    { "...": "first item" },
    { "...": "second item" },
    { "...": "third item" }
  ],
  "atEnd": false
}

Pagination

Every endpoint uses bookmark-based pagination:

Send the first request with "bookmark": null and "paging": "NEXT_PAGE".
The response includes a bookmark string and an atEnd boolean.
If atEnd is false, send the next request with the returned bookmark value.
Repeat until atEnd is true.

To fetch the next page, pass the bookmark from the previous response:

{
  "bookmark": "eyJsYXN0S2V5IjoiMTAwMyJ9",
  "queryArgs": null,
  "rangeLimit": 3,
  "paging": "NEXT_PAGE"
}

The last page has atEnd set to true:

{
  "bookmark": "eyJsYXN0S2V5IjoiMTAwNSJ9",
  "content": [
    { "...": "fourth item" },
    { "...": "fifth item" }
  ],
  "atEnd": true
}

Filtering and sorting

queryArgs holds a typed query argument for each filterable field. All query argument fields are optional; include only the ones you need. Each query argument has two optional properties:

Property	Type	Description
`filters`	array	Filter conditions on the field. Each filter has `group`, `operator`, and `value`.
`sorter`	object	Sort configuration: `priority` (integer, a lower value has a higher priority) and `sortingDirection` (`ASCENDING` or `DESCENDING`).

Filters in the same group are combined with AND. Groups are combined with OR.

Operators by type

Query argument type	Operators	Value format
`LongQueryArg`	`EQUALS`, `NOT_EQUALS`, `GREATER_THAN`, `GREATER_THAN_OR_EQUALS`, `LESS_THAN`, `LESS_THAN_OR_EQUALS`	Integer (int64)
`StringQueryArg`	`EQUALS`, `NOT_EQUALS`, `CONTAINS`, `STARTS_WITH`, `ENDS_WITH`	String
`LocalDateQueryArg`	`EQUALS`, `NOT_EQUALS`, `AFTER`, `AFTER_OR_EQUALS`, `BEFORE`, `BEFORE_OR_EQUALS`	`YYYY-MM-DD`
`BigDecimalQueryArg`	`EQUALS`, `NOT_EQUALS`, `GREATER_THAN`, `GREATER_THAN_OR_EQUALS`, `LESS_THAN`, `LESS_THAN_OR_EQUALS`	Decimal number
`InstantQueryArg`	`EQUALS`, `NOT_EQUALS`, `AFTER`, `AFTER_OR_EQUALS`, `BEFORE`, `BEFORE_OR_EQUALS`	ISO-8601 date-time
Enum query arguments	`EQUALS`, `NOT_EQUALS`	Enum value string

Filter example

A single filter on a field:

{
  "queryArgs": {
    "someField": {
      "filters": [
        {
          "group": 0,
          "operator": "EQUALS",
          "value": 12345
        }
      ]
    }
  }
}

A filter and a sort on tradeDate:

{
  "queryArgs": {
    "tradeDate": {
      "filters": [
        {
          "group": 0,
          "operator": "AFTER_OR_EQUALS",
          "value": "2026-01-01"
        }
      ],
      "sorter": {
        "priority": 0,
        "sortingDirection": "DESCENDING"
      }
    }
  }
}

The field names inside queryArgs are listed for each endpoint under REST Endpoints.

​Basics

​Request structure

​Response structure

​Pagination

​Filtering and sorting

​Operators by type

​Filter example

Basics

Request structure

Response structure

Pagination

Filtering and sorting

Operators by type

Filter example