Skip to content
Taoswap Docs

API quickstart

The Taoswap API serves Bittensor data: subnets, validators, accounts, blocks, extrinsics, trades and portfolios. It needs no key and no account, and every public endpoint answers GET requests, except the testnet faucet’s claim.

  • Base URL: https://api.taoswap.org. Plain HTTP redirects to HTTPS.
  • Responses are JSON.
  • The reference lists every endpoint with its parameters, its response and its rate limit.

Your first request

Section titled “Your first request”

The last trade on subnet 64:

Terminal window
curl 'https://api.taoswap.org/trades/?netuid=64&page_size=1'

The response, trimmed:

{
  "results": [
    {
      "block": 9347124,
      "timestamp": "2026-10-23T15:24:36+00:00",
      "extrinsic_idx": 33,
      "success": true,
      "side": "sell",
      "netuid": 64,
      "coldkey": "5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY",
      "hotkey": "5GKH9FPPnWSUoeeTJp19wVtd84XqFW4pyK2ijV2GsFbhTrP1",
      "tao_rao": 224758735,
      "alpha": 3303435725,
      "unit_price_rao": 68037871,
      "operation": "remove"
    }
  ],
  "pagination": {
    "page": 1,
    "page_size": 1,
    "has_next": true,
    "has_previous": false,
    "truncated": false,
    "next_before": "9347124-45651241",
    "total_count": 730023,
    "total_pages": 730023
  }
}

This sale swapped 3.303435725 alpha for 0.224758735 TAO, about 0.068 TAO per alpha. The sections below explain the units, the timestamp and the pagination object.

Large responses come compressed when you ask for it: add --compressed to curl, or send Accept-Encoding: gzip.

Rate limits

Section titled “Rate limits”

Limits apply per IP address, in two layers.

The proxy in front of the API takes 10 requests per second from one address, sustained, and serves a burst of up to 100 at once. It also allows 100 open connections per address, and 8 requests in flight at once on /events/, /extrinsics/ and /trades/. Past these limits it answers 429 with an HTML page and no Retry-After header.

The API’s own limits depend on the endpoint:

Limit Applies to
600 per minute Every endpoint without a tighter limit.
300 per minute The heavy lists and details (/accounts/, /blocks/, /events/, /extrinsics/, /identities/, /search/, /subnets/, /trades/, /validators/, /v1/beta-baskets/, their sub-routes and their /v2/ forms) and four portfolio endpoints (/portfolio-balance/, /portfolio-pnl-apy/, /account-transactions/, /v1/account-ledger/).
2000 per minute The subnet price chart, /subnet-price-history/. The proxy still caps sustained traffic at 600 per minute, so the rest is usable in bursts only.
3 per minute The testnet faucet’s claim.

Each limit is one budget per IP address, shared by every endpoint it covers: requests to /extrinsics/ leave less for /trades/. The reference repeats each operation’s limit in its description and in an x-ratelimit field that client generators can read. The API sends no header with your remaining budget, so pace your requests from these figures.

When you exceed a limit:

  • The API answers 429 with a Retry-After header and the same number of seconds in detail.retry_after. Wait that long before the next request.
  • The proxy answers 429 as HTML, with no delay to read. Back off, and increase the wait each time it happens again.

An address that keeps hitting the proxy’s limit, with hundreds of refused requests within ten minutes, is banned for an hour. Never retry a 429 in a tight loop.

Units

Section titled “Units”

On chain, every amount is an integer: 1 TAO is 10⁹ rao, and alpha uses the same nine decimals. The API serves amounts both ways, as integers in rao (or alpha’s base unit) and as decimal numbers of TAO or alpha, and a field’s name doesn’t always say which:

Field Endpoint Unit
tao_rao /trades/ rao, an integer
alpha /trades/ alpha’s base unit, an integer (10⁹ per alpha)
unit_price_rao /trades/ rao per whole alpha, an integer
free, staked_tao, total_tao /accounts/ rao, integers
threshold_tao /accounts/wealth-distribution/ whole TAO
price, market_cap /v2/subnets/ TAO per alpha and TAO, decimal numbers

Most dollar amounts sit in fields whose names contain usd, while /price-history/ gives TAO’s price in the currency its currency field names. Before you rely on a field, read its description in the reference.

Timestamps

Section titled “Timestamps”
  • Timestamps are ISO 8601 strings in UTC, such as 2026-10-23T15:24:36+00:00.
  • Dates are YYYY-MM-DD, as UTC days.
  • The candles of /subnet-price-history/ carry time in UNIX seconds.
  • Many rows also carry the block they come from.

Date filters such as date_from and date_to take YYYY-MM-DD or an ISO 8601 instant. Check each bound in the reference: on /trades/, date_to is exclusive.

Pagination

Section titled “Pagination”

Lists page in several ways, and each one’s reference names its parameters.

Pages. Most lists take page (from 1) and page_size, whose default and maximum vary by endpoint. They answer results, a list (on /blocks/, a map keyed by block number), beside a pagination object that carries page, page_size, has_next, has_previous and, where a total is known, total_count and total_pages. Variants:

  • /events/ gives no totals.
  • /extrinsics/ and /v2/extrinsics/ add total_count_approximate, true when the total is an estimate.
  • /trades/ can answer null totals. To read further, pass pagination.next_before back as before: it reads the next page at any depth. When truncated is true, the page came back short; follow next_before all the same.

Page numbers reach 10,000 rows deep at most, and a deeper page answers 400. Where pagination carries reachable_count, as on /accounts/ and /blocks/, total_pages and has_next already stop at that depth, and reachable_count says how many rows you can reach.

Cursors. The delegators of /v2/subnets/{id}/?delegators=true and /v2/validators/{id}/, and /v1/beta-baskets/{id}/deposits/ and /v1/beta-baskets/{id}/swaps/, take after, set to the next_cursor of the previous page.

Limit and offset. /account-transactions/ takes limit (0 to 500) and offset (0 to 10,000) and returns no pagination object.

Limit only. /subnet-price-history/, /price-history/, /network-stats/history/ and /search/ take a limit.

Some lists return every row at once, such as /v2/subnets/.

Errors

Section titled “Errors”

Every error the API answers has the same JSON envelope:

{ "error": true, "code": "RESOURCE_NOT_FOUND", "message": "Not found", "detail": null }
Status code Meaning
400 VALIDATION_ERROR A parameter failed a check. message, or detail per field, says which.
404 RESOURCE_NOT_FOUND Nothing exists at this address. The answer may be cached for 15 seconds.
405 METHOD_NOT_ALLOWED The endpoint doesn’t take this method.
410 ENDPOINT_REMOVED The route was removed. detail.replacement names its successor, if any. See Deprecations.
429 RATE_LIMITED You exceeded a limit. Wait detail.retry_after seconds.
500 INTERNAL_ERROR Something failed on the server.
503 QUERY_TIMEOUT The query ran past its time budget. Retry, or narrow the request, for example its date range.

Other client errors carry a code named after the error, such as PARSE_ERROR or NOT_ACCEPTABLE. Errors from the proxy in front of the API, its 429 and the 502 or 504 it returns when the API doesn’t answer, come as HTML, not JSON: check the status code before you parse the body.

CORS

Section titled “CORS”

Browsers refuse calls to the API from other websites: it allows only Taoswap’s own pages. Call the API from your server, and have your pages read your server.

Versions

Section titled “Versions”
  • The bare path is version 1, and /v1/ writes that version down: /trades/ and /v1/trades/ answer the same, byte for byte.
  • /v2/ carries the routes whose response changed shape: /v2/subnets/, /v2/validators/ and /v2/extrinsics/. Their version 1 form keeps its old shape until it is deprecated.
  • Routes added more recently exist under /v1/ only, such as /v1/beta-baskets/ and /v1/account-ledger/.

For a new integration, call /v2/ for subnets, validators and extrinsics. For the other routes, the bare path and /v1/ are equivalent.

A new field or filter can appear at any time without notice, so ignore the fields you don’t use. A change of shape gets a new version, and a route leaves only through the deprecation process.

Next steps

Section titled “Next steps”