> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cdp.coinbase.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Welcome to the Coinbase Clearing REST API

> [!TIP]
>
> The REST endpoints are listed in the sidebar under **REST Endpoints**. Every endpoint requires the bearer JWT described in [Authentication](https://docs.cdp.coinbase.com/api-reference/clearing-api/rest-api/authentication.md).

## 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](https://docs.cdp.coinbase.com/clearing/connectivity.md) 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:

```json theme={null}
{
  "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. |

```json theme={null}
{
  "bookmark": "eyJsYXN0S2V5IjoiMTAwMyJ9",
  "content": [
    { "...": "first item" },
    { "...": "second item" },
    { "...": "third item" }
  ],
  "atEnd": false
}
```

## Pagination

Every endpoint uses bookmark-based pagination:

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

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

```json theme={null}
{
  "bookmark": "eyJsYXN0S2V5IjoiMTAwMyJ9",
  "queryArgs": null,
  "rangeLimit": 3,
  "paging": "NEXT_PAGE"
}
```

The last page has `atEnd` set to `true`:

```json theme={null}
{
  "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:

```json theme={null}
{
  "queryArgs": {
    "someField": {
      "filters": [
        {
          "group": 0,
          "operator": "EQUALS",
          "value": 12345
        }
      ]
    }
  }
}
```

A filter and a sort on `tradeDate`:

```json theme={null}
{
  "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**.