API reference

The interactive reference

api.taoswap.org/docs is the full reference of the public API. It is drawn from the API’s OpenAPI schema, so it matches what the server runs. For each operation it shows:

• its parameters, with their defaults and the checks they must pass;
• the structure of its response, and the error responses it declares;
• its rate limit, in a sentence and in an x-ratelimit field, beside the 429 response and its Retry-After header;
• for a route on its way out, a deprecated mark, its sunset date in an x-sunset field, and its replacement.

Try it out sends a real request from your browser, which counts against your rate limit like any other.

The reference covers the public API. Routes that only Taoswap’s own apps use are left out.

The schema

api.taoswap.org/schema serves the same description as an OpenAPI 3.0 document, in YAML by default and in JSON with ?format=json:

curl -o taoswap-openapi.yaml 'https://api.taoswap.org/schema/'
curl -o taoswap-openapi.json 'https://api.taoswap.org/schema/?format=json'

Its info.version is a date. It moves when a route or a field is announced for removal or removed, not when a field is added. To follow removals, see Deprecations.

Generate a typed client

Any OpenAPI 3.0 generator reads the schema. In TypeScript, openapi-typescript turns it into types, and openapi-fetch calls the API with them:

npx openapi-typescript https://api.taoswap.org/schema/ -o taoswap-api.d.ts
npm install openapi-fetch

import createClient from "openapi-fetch";
import type { paths } from "./taoswap-api";

const api = createClient<paths>({ baseUrl: "https://api.taoswap.org" });

const { data, error, response } = await api.GET("/trades/", {
  params: { query: { netuid: 64, page_size: 1 } },
});
if (!data) throw new Error(`HTTP ${response.status}: ${error?.code ?? "no JSON body"}`);
console.log(data.results[0].tao_rao, data.pagination.next_before);

The !data check also catches the errors of the proxy in front of the API, which come as HTML with no JSON body.

For other languages, OpenAPI Generator covers many of them, and openapi-python-client writes a Python client.

Whatever the generator:

• Set the base URL to https://api.taoswap.org.
• Accept fields you don’t know. New fields appear without notice, and a client that rejects them breaks.
• Read the unit of every amount in its description. A generated type says integer or number, never rao or TAO: see Units.
• Read each path parameter’s description: depending on the route, it is a subnet’s netuid, a validator’s hotkey, a block, or an extrinsic’s {block}-{index} key.
• Expect the pagination object of the list you call, since lists page in several ways: see Pagination.