List OTC Lockup Listings

Endpoint

GET /api/otc/lockup/listing/v1

Try it

Fills the fields below — runs automatically if your API key is saved.

API key

👁

Remember on this browser Get a free API key →

cURLTypeScriptPythonSDK

Run

listing_idFilter by exact lockup listing id.sellerFilter by seller coldkey (SS58).hotkeyFilter by the hotkey the alpha is delegated to.netuidSubnet id.price_offset_bps_minMinimum price offset in basis points (signed; -10000 to +10000). Negative = discount, positive = premium.price_offset_bps_maxMaximum price offset in basis points.lockup_duration_minMinimum lockup duration in blocks.lockup_duration_maxMaximum lockup duration in blocks.total_amount_minMinimum total alpha originally listed (rao).total_amount_maxMaximum total alpha originally listed (rao).remaining_amount_minMinimum alpha still available to purchase (rao).remaining_amount_maxMaximum alpha still available to purchase (rao).created_block_startEarliest creation block (inclusive).created_block_endLatest creation block (inclusive).created_timestamp_startEarliest creation timestamp (seconds, inclusive).created_timestamp_endLatest creation timestamp (seconds, inclusive).page1-based page number.limitPage size (max 200).

curlCopy

Description

Returns active and historical lockup listings on the Taostats OTC desk. A lockup listing is a sell-side OTC offer where the purchased alpha is held in an escrow account and only claimable by the buyer after a defined unlock_block. Sellers commit alpha; buyers commit TAO up-front; the escrow releases on unlock.

Lockups use offset pricing (price_offset_bps) — the executed price floats with the current alpha market price plus or minus the offset in basis points, snapped at purchase time.

Parameters

Name	In	Type	Required	Description
listing_id	query	string		Filter by exact lockup listing id.
seller	query	string		Filter by seller coldkey (SS58).
hotkey	query	string		Filter by the hotkey the alpha is delegated to.
netuid	query	integer		Subnet id.
status	query	—		Lifecycle state: active, filled, cancelled, expired.
price_offset_bps_min	query	integer		Minimum price offset in basis points (signed; -10000 to +10000). Negative = discount, positive = premium.
price_offset_bps_max	query	integer		Maximum price offset in basis points.
lockup_duration_min	query	integer		Minimum lockup duration in blocks.
lockup_duration_max	query	integer		Maximum lockup duration in blocks.
total_amount_min	query	string		Minimum total alpha originally listed (rao).
total_amount_max	query	string		Maximum total alpha originally listed (rao).
remaining_amount_min	query	string		Minimum alpha still available to purchase (rao).
remaining_amount_max	query	string		Maximum alpha still available to purchase (rao).
created_block_start	query	integer		Earliest creation block (inclusive).
created_block_end	query	integer		Latest creation block (inclusive).
created_timestamp_start	query	integer		Earliest creation timestamp (seconds, inclusive).
created_timestamp_end	query	integer		Latest creation timestamp (seconds, inclusive).
page	query	integer		1-based page number.
limit	query	integer		Page size (max 200).
order	query	—		Sort order, e.g. created_block_desc.

Responses

200 — Lockup listings retrieved successfully

Media: application/json

Schema

{
  "type": "object",
  "required": [
    "pagination",
    "data"
  ],
  "properties": {
    "data": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "listing_id",
          "seller",
          "hotkey",
          "netuid",
          "total_amount",
          "remaining_amount",
          "price_offset_bps",
          "lockup_duration",
          "status",
          "force_cancelled",
          "created_block",
          "created_timestamp",
          "updated_block",
          "updated_timestamp"
        ],
        "properties": {
          "created_block": {
            "type": "integer",
            "format": "int32"
          },
          "created_timestamp": {
            "type": "string",
            "format": "date-time"
          },
          "force_cancelled": {
            "type": "boolean"
          },
          "hotkey": {
            "type": "object",
            "required": [
              "ss58",
              "hex"
            ],
            "properties": {
              "hex": {
                "type": "string",
                "description": "The hex format of the hot key"
              },
              "ss58": {
                "type": "string",
                "description": "The SS58 format of the hot key"
              }
            }
          },
          "initiated_by": {
            "type": "string",
            "nullable": true
          },
          "listing_id": {
            "type": "string"
          },
          "lockup_duration": {
            "type": "integer",
            "format": "int32"
          },
          "netuid": {
            "type": "integer",
            "format": "int32"
          },
          "price_offset_bps": {
            "type": "integer",
            "format": "int32"
          },
          "remaining_amount": {
            "type": "string"
          },
          "seller": {
            "type": "object",
            "required": [
              "ss58",
              "hex"
            ],
            "properties": {
              "hex": {
                "type": "string",
                "description": "The hex format of the hot key"
              },
              "ss58": {
                "type": "string",
                "description": "The SS58 format of the hot key"
              }
            }
          },
          "status": {
            "type": "string"
          },
          "total_amount": {
            "type": "string"
          },
          "updated_block": {
            "type": "integer",
            "format": "int32"
          },
          "updated_timestamp": {
            "type": "string",
            "format": "date-time"
          }
        }
      }
    },
    "pagination": {
      "type": "object",
      "required": [
        "current_page",
        "per_page",
        "total_items",
        "total_pages"
      ],
      "properties": {
        "current_page": {
          "type": "integer",
          "format": "int32"
        },
        "next_page": {
          "type": "integer",
          "format": "int32",
          "nullable": true
        },
        "per_page": {
          "type": "integer",
          "format": "int32"
        },
        "prev_page": {
          "type": "integer",
          "format": "int32",
          "nullable": true
        },
        "total_items": {
          "type": "integer",
          "format": "int32"
        },
        "total_pages": {
          "type": "integer",
          "format": "int32"
        }
      }
    }
  }
}

400 — Bad request

500 — Internal server error

Authentication

All Taostats API requests require an Authorization header containing your API key. See Getting Started.