# Executed OTC Trades

Returns settled OTC trades — the matches between listings and offers (or direct buys).

_Source: https://beta.taostats.io/docs/api-reference/otc/get-otc-trade_

_Last reviewed: 2026-09-18_

```http
GET https://api.taostats.io/api/otc/trade/v2
```

Requires an API key in the `Authorization` header.

Returns settled OTC trades — the matches between listings and offers (or direct buys). Each row records the alpha amount, TAO amount, executed price (the absolute price that was snapped from the market when the trade settled, in rao per alpha), `price_offset_bps` (the offset the listing or offer was authored with), fee, buyer/seller, and the extrinsic that settled the trade on-chain. Use this for volume analytics, price-time series, and trade reconstruction.

## Try it

Try this request in the browser on the HTML version of this page, or use the code samples below.

### Examples

List executed OTC trades in subnet 19

```text
https://api.taostats.io/api/otc/trade/v2?netuid=19&order=block_number_desc&limit=50
```

Find the largest OTC trades by TAO amount

```text
https://api.taostats.io/api/otc/trade/v2?order=tao_amount_desc&limit=20
```

### Code samples

**cURL**

```bash
curl -H "Authorization: <YOUR_API_KEY>" \
  "https://api.taostats.io/api/otc/trade/v2?netuid=19&limit=50&order=block_number_desc"
```

**JavaScript**

```js
const response = await fetch('https://api.taostats.io/api/otc/trade/v2?netuid=19&limit=50&order=block_number_desc', {
  headers: {
    Authorization: '<YOUR_API_KEY>',
  },
});
const data = await response.json();
```

**Python**

```python
import requests

response = requests.get(
    "https://api.taostats.io/api/otc/trade/v2?netuid=19&limit=50&order=block_number_desc",
    headers={"Authorization": "<YOUR_API_KEY>"},
)
data = response.json()
```

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `trade_type` | query | `string` |  | How the trade was matched: `listing_filled`, `offer_filled`, or `direct`. One of `listing_taken`, `offer_taken`, `all`. |
| `seller` | query | `string` |  | Filter by seller coldkey (SS58). |
| `buyer` | query | `string` |  | Filter by buyer coldkey (SS58). |
| `netuid` | query | `integer (int32)` |  | Subnet id. |
| `listing_id` | query | `string` |  | Filter to trades that filled a specific listing. |
| `offer_id` | query | `string` |  | Filter to trades that filled a specific offer. |
| `block_start` | query | `integer (int32)` |  | Earliest block height (inclusive). |
| `block_end` | query | `integer (int32)` |  | Latest block height (inclusive). |
| `timestamp_start` | query | `integer (int64)` |  | Earliest Unix timestamp in seconds (inclusive). |
| `timestamp_end` | query | `integer (int64)` |  | Latest Unix timestamp in seconds (inclusive). |
| `page` | query | `integer (int32)` |  | 1-based page number. |
| `limit` | query | `integer (int32)` |  | Page size (max 200). |
| `order` | query | `string` |  | Sort order, e.g. `block_number_desc`. One of `block_number_asc`, `block_number_desc`, `timestamp_asc`, `timestamp_desc`, `tao_amount_asc`, `tao_amount_desc`, `alpha_amount_asc`, `alpha_amount_desc`, `executed_price_asc`, `executed_price_desc`. |

## Responses

### `200` — OTC trades retrieved successfully

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `data` | `array` | Yes |  |
| `data[].alpha_amount` | `string` | Yes |  |
| `data[].block_number` | `integer (int32)` | Yes |  |
| `data[].buyer` | `object` | Yes |  |
| `data[].buyer.hex` | `string` | Yes | The hex format of the hot key |
| `data[].buyer.ss58` | `string` | Yes | The SS58 format of the hot key |
| `data[].executed_price` | `string` | Yes |  |
| `data[].extrinsic_id` | `string` | Yes |  |
| `data[].fee` | `string` | Yes |  |
| `data[].id` | `string` | Yes |  |
| `data[].listing_id` | `string, nullable` |  |  |
| `data[].netuid` | `integer (int32)` | Yes |  |
| `data[].offer_id` | `string, nullable` |  |  |
| `data[].price_offset_bps` | `integer (int32)` | Yes |  |
| `data[].seller` | `object` | Yes |  |
| `data[].seller.hex` | `string` | Yes | The hex format of the hot key |
| `data[].seller.ss58` | `string` | Yes | The SS58 format of the hot key |
| `data[].tao_amount` | `string` | Yes |  |
| `data[].timestamp` | `string (date-time)` | Yes |  |
| `data[].trade_type` | `string` | Yes |  |
| `pagination` | `object` | Yes |  |
| `pagination.current_page` | `integer (int32)` | Yes |  |
| `pagination.next_page` | `integer (int32), nullable` |  |  |
| `pagination.per_page` | `integer (int32)` | Yes |  |
| `pagination.prev_page` | `integer (int32), nullable` |  |  |
| `pagination.total_items` | `integer (int32)` | Yes |  |
| `pagination.total_pages` | `integer (int32)` | Yes |  |

### Other responses

| Status | Meaning |
| --- | --- |
| `400` | Bad request |
| `500` | Internal server error |

Every request needs an `Authorization` header holding your API key — see [Getting started with the Taostats API](https://beta.taostats.io/docs/start-here/getting-started-with-taostats-api).