# Get Trading Pairs

Returns tradeable token pairs. Pairs can be filtered by chain and token symbols.

**Endpoint:** `GET /api/v1/pairs`\
**Auth:** Required (`Authorization: Bearer YOUR_API_KEY`)

## Query parameters

| Parameter       | Type    | Required | Description                                                    | Example        |
| --------------- | ------- | -------- | -------------------------------------------------------------- | -------------- |
| `chainRef`      | string  | No       | Filter by chain. When set, only same-chain pairs are returned. | `eth-mainnet`  |
| `tokenIn`       | string  | No       | Filter by input token symbol                                   | `USDC`         |
| `tokenOut`      | string  | No       | Filter by output token symbol                                  | `USDT`         |
| `limit`         | integer | No       | Max pairs to return (1–10000, default: 1000)                   | `20`           |
| `cursor`        | string  | No       | Cursor for pagination (opaque)                                 | (opaque value) |
| `supportedOnly` | string  | No       | `1` or `true` — only pairs with supported tokens               | `1`            |
| `debug`         | string  | No       | `1` or `true` — include debug info in response                 | `1`            |

## Example

{% tabs %}
{% tab title="cURL" %}

```bash
curl -X GET 'https://api.gateway.zert.com/api/v1/pairs?chainRef=eth-mainnet&tokenIn=USDC&limit=20' \
  -H 'Authorization: Bearer YOUR_API_KEY'
```

{% endtab %}

{% tab title="Example Response" %}

```json
{
  "data": {
    "pairs": [
      {
        "fromChain": "eth-mainnet",
        "toChain": "eth-mainnet",
        "tokenIn": "USDC",
        "tokenOut": "USDT"
      }
    ],
    "nextCursor": null
  },
  "meta": {
    "requestId": "req_xyz",
    "timestamp": "2026-04-23T12:00:00.000Z"
  }
}
```

{% endtab %}
{% endtabs %}

## Pair fields

| Field        | Type           | Description                  |
| ------------ | -------------- | ---------------------------- |
| `fromChain`  | string         | Source chain identifier      |
| `toChain`    | string         | Destination chain identifier |
| `tokenIn`    | string         | Input token symbol           |
| `tokenOut`   | string         | Output token symbol          |
| `nextCursor` | string or null | Cursor for the next page     |

## Responses

| Code | Description                               |
| ---- | ----------------------------------------- |
| 200  | List of trading pairs                     |
| 400  | Invalid request                           |
| 401  | Unauthorized (missing or invalid API key) |
| 502  | Quote-service token discovery unavailable |

{% embed url="<https://api.gateway.zert.com/docs>" %}
Zert API — Pairs
{% endembed %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.zert.com/api-reference/discovery/list-pairs.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.