OTC lockup purchases

Endpoint

GET /api/otc/lockup/purchase/v1

Description

Returns lockup purchases — the moments a buyer committed TAO into a lockup listing’s escrow account. Each row records the escrow account, executed price, TAO + alpha amounts, fee, and the unlock_block after which the buyer can call claim to take possession of the alpha. Filter by status (pending, claimed, cancelled) to see what’s still in escrow.

Parameters

Name	In	Type	Required	Description
purchase_id	query	string		Filter by purchase id.
listing_id	query	string		Filter to purchases against a specific lockup listing.
buyer	query	string		Filter by buyer coldkey (SS58).
seller	query	string		Filter by seller coldkey (SS58).
netuid	query	integer		Subnet id.
status	query	—		Purchase lifecycle: pending (in escrow), claimed (released to buyer), cancelled.
unlock_block_start	query	integer		Earliest unlock block (inclusive).
unlock_block_end	query	integer		Latest unlock block (inclusive).
created_block_start	query	integer
created_block_end	query	integer
created_timestamp_start	query	integer
created_timestamp_end	query	integer
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 purchases retrieved successfully

Media: application/json

Schema

{
  "type": "object",
  "required": [
    "pagination",
    "data"
  ],
  "properties": {
    "data": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "purchase_id",
          "listing_id",
          "buyer",
          "seller",
          "netuid",
          "alpha_amount",
          "tao_amount",
          "executed_price",
          "fee",
          "unlock_block",
          "escrow_account",
          "status",
          "created_block",
          "created_timestamp"
        ],
        "properties": {
          "alpha_amount": {
            "type": "string"
          },
          "amount_claimed": {
            "type": "string",
            "nullable": true
          },
          "buyer": {
            "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"
              }
            }
          },
          "claimed_block": {
            "type": "integer",
            "format": "int32",
            "nullable": true
          },
          "claimed_timestamp": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "created_block": {
            "type": "integer",
            "format": "int32"
          },
          "created_timestamp": {
            "type": "string",
            "format": "date-time"
          },
          "escrow_account": {
            "type": "string"
          },
          "executed_price": {
            "type": "string"
          },
          "fee": {
            "type": "string"
          },
          "listing_id": {
            "type": "string"
          },
          "netuid": {
            "type": "integer",
            "format": "int32"
          },
          "purchase_id": {
            "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"
          },
          "tao_amount": {
            "type": "string"
          },
          "unlock_block": {
            "type": "integer",
            "format": "int32"
          }
        }
      }
    },
    "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

Try it

Interactive request console coming soon. In the meantime you can use the OpenAPI spec with any client (Insomnia, Bruno, Scalar, curl).

Authentication

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