Documentation / API reference / OTC
OTC Lockup Listing Event History
Reference
Last reviewed 2026-09-18
Immutable event log for lockup listings: created, updated, cancelled, purchased, expired. Each event records the executed price, escrow account, lockup duration, unlock block, and extrinsic context. For current lockup listing state use /api/otc/lockup/listing/v1.
Try it
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
listing_id | query | string | Filter to events for one specific lockup listing. | |
event_type | query | string | Event type: created, updated, cancelled, purchased, expired. One of created, taken, cancelled, force_cancelled, filled, all. | |
seller | query | string | Filter by seller coldkey. | |
buyer | query | string | Filter to events involving a specific buyer (e.g. purchased). | |
hotkey | query | string | Filter by hotkey. | |
netuid | query | integer (int32) | Subnet id. | |
block_start | query | integer (int32) | Earliest block (inclusive). | |
block_end | query | integer (int32) | Latest block (inclusive). | |
timestamp_start | query | integer (int64) | Earliest timestamp (seconds, inclusive). | |
timestamp_end | query | integer (int64) | Latest timestamp (seconds, inclusive). | |
page | query | integer (int32) | 1-based page number. | |
limit | query | integer (int32) | Page size (max 200). | |
order | query | string | Sort order. One of block_number_asc, block_number_desc, timestamp_asc, timestamp_desc. |
Responses
200 — Lockup listing history retrieved successfully
| Field | Type | Required | Description |
|---|---|---|---|
data | array | Yes | |
data[].alpha_amount | string, nullable | ||
data[].amount | string, nullable | ||
data[].amount_returned | string, nullable | ||
data[].block_number | integer (int32) | Yes | |
data[].buyer | object, nullable | ||
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[].escrow_account | string, nullable | ||
data[].event_type | string | Yes | |
data[].executed_price | string, nullable | ||
data[].extrinsic_id | string | Yes | |
data[].fee | string, nullable | ||
data[].force_cancelled | boolean, nullable | ||
data[].hotkey | object, nullable | ||
data[].hotkey.hex | string | Yes | The hex format of the hot key |
data[].hotkey.ss58 | string | Yes | The SS58 format of the hot key |
data[].id | string | Yes | |
data[].initiated_by | string, nullable | ||
data[].listing_id | string | Yes | |
data[].lockup_duration | integer (int32), nullable | ||
data[].netuid | integer (int32) | Yes | |
data[].price_offset_bps | integer (int32), nullable | ||
data[].purchase_id | string, nullable | ||
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, nullable | ||
data[].timestamp | string (date-time) | Yes | |
data[].unlock_block | integer (int32), nullable | ||
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.