Démarrage rapide de l'API

L’API Taoswap sert des données Bittensor : subnets, validateurs, comptes, blocs, extrinsics, trades et portefeuilles. Elle ne demande ni clé ni compte, et chaque point d’accès public répond aux requêtes GET, sauf la réclamation du faucet testnet.

URL de base : https://api.taoswap.org. Le HTTP simple redirige vers HTTPS.
Les réponses sont en JSON.
La référence liste chaque point d’accès avec ses paramètres, sa réponse et sa limite de débit.

Votre première requête

Le dernier trade sur le subnet 64 :

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

La réponse, raccourcie :

{
  "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
  }
}

Cette vente a échangé 3,303435725 alpha contre 0,224758735 TAO, soit environ 0,068 TAO par alpha. Les sections ci-dessous expliquent les unités, l’horodatage et l’objet pagination.

Les grosses réponses arrivent compressées quand vous le demandez : ajoutez --compressed à curl, ou envoyez Accept-Encoding: gzip.

Limites de débit

Les limites s’appliquent par adresse IP, en deux couches.

Le proxy devant l’API accepte 10 requêtes par seconde depuis une adresse, en continu, et sert une rafale de 100 au plus d’un coup. Il autorise aussi 100 connexions ouvertes par adresse, et 8 requêtes simultanées en cours sur /events/, /extrinsics/ et /trades/. Au-delà de ces limites, il répond 429 avec une page HTML et sans en-tête Retry-After.

Les limites propres à l’API dépendent du point d’accès :

Limite	S’applique à
600 par minute	Chaque point d’accès sans limite plus stricte.
300 par minute	Les listes et détails lourds (`/accounts/`, `/blocks/`, `/events/`, `/extrinsics/`, `/identities/`, `/search/`, `/subnets/`, `/trades/`, `/validators/`, `/v1/beta-baskets/`, leurs sous-routes et leurs formes `/v2/`) et quatre points d’accès de portefeuille (`/portfolio-balance/`, `/portfolio-pnl-apy/`, `/account-transactions/`, `/v1/account-ledger/`).
2000 par minute	Le graphique de prix des subnets, `/subnet-price-history/`. Le proxy plafonne toujours le trafic continu à 600 par minute : le reste n’est utilisable qu’en rafales.
3 par minute	La réclamation du faucet testnet.

Chaque limite est un budget par adresse IP, partagé par tous les points d’accès qu’elle couvre : les requêtes vers /extrinsics/ en laissent moins pour /trades/. La référence répète la limite de chaque opération dans sa description et dans un champ x-ratelimit que les générateurs de clients peuvent lire. L’API n’envoie aucun en-tête indiquant votre budget restant : réglez donc le rythme de vos requêtes à partir de ces chiffres.

Quand vous dépassez une limite :

L’API répond 429 avec un en-tête Retry-After et le même nombre de secondes dans detail.retry_after. Attendez ce délai avant la requête suivante.
Le proxy répond 429 en HTML, sans délai à lire. Ralentissez, et allongez l’attente à chaque nouvelle occurrence.

Une adresse qui continue de heurter la limite du proxy, avec des centaines de requêtes refusées en dix minutes, est bannie pendant une heure. Ne réessayez jamais un 429 dans une boucle serrée.

Unités

On-chain, chaque montant est un entier : 1 TAO vaut 10⁹ rao, et l’alpha utilise les mêmes neuf décimales. L’API sert les montants sous les deux formes, en entiers en rao (ou dans l’unité de base de l’alpha) et en nombres décimaux de TAO ou d’alpha, et le nom d’un champ ne dit pas toujours laquelle :

Champ	Point d’accès	Unité
`tao_rao`	`/trades/`	rao, un entier
`alpha`	`/trades/`	l’unité de base de l’alpha, un entier (10⁹ par alpha)
`unit_price_rao`	`/trades/`	rao par alpha entier, un entier
`free`, `staked_tao`, `total_tao`	`/accounts/`	rao, des entiers
`threshold_tao`	`/accounts/wealth-distribution/`	TAO entiers
`price`, `market_cap`	`/v2/subnets/`	TAO par alpha et TAO, des nombres décimaux

La plupart des montants en dollars se trouvent dans des champs dont le nom contient usd, tandis que /price-history/ donne le prix du TAO dans la devise que nomme son champ currency. Avant de vous fier à un champ, lisez sa description dans la référence.

Horodatages

Les horodatages sont des chaînes ISO 8601 en UTC, comme 2026-10-23T15:24:36+00:00.
Les dates sont au format YYYY-MM-DD, en jours UTC.
Les bougies de /subnet-price-history/ portent time en secondes UNIX.
Beaucoup de lignes portent aussi le block dont elles viennent.

Les filtres de date comme date_from et date_to acceptent YYYY-MM-DD ou un instant ISO 8601. Vérifiez chaque borne dans la référence : sur /trades/, date_to est exclusive.

Pagination

Les listes se paginent de plusieurs façons, et la référence de chacune nomme ses paramètres.

Pages. La plupart des listes acceptent page (à partir de 1) et page_size, dont la valeur par défaut et le maximum varient selon le point d’accès. Elles répondent results, une liste (sur /blocks/, une table indexée par numéro de bloc), à côté d’un objet pagination qui porte page, page_size, has_next, has_previous et, quand un total est connu, total_count et total_pages. Variantes :

/events/ ne donne pas de totaux.
/extrinsics/ et /v2/extrinsics/ ajoutent total_count_approximate, vrai quand le total est une estimation.
/trades/ peut répondre des totaux null. Pour lire plus loin, renvoyez pagination.next_before comme before : il lit la page suivante à n’importe quelle profondeur. Quand truncated est vrai, la page est revenue incomplète ; suivez quand même next_before.

Les numéros de page atteignent 10 000 lignes de profondeur au plus, et une page plus profonde répond 400. Là où pagination porte reachable_count, comme sur /accounts/ et /blocks/, total_pages et has_next s’arrêtent déjà à cette profondeur, et reachable_count indique combien de lignes vous pouvez atteindre.

Curseurs. Les délégateurs de /v2/subnets/{id}/?delegators=true et de /v2/validators/{id}/, ainsi que /v1/beta-baskets/{id}/deposits/ et /v1/beta-baskets/{id}/swaps/, acceptent after, réglé sur le next_cursor de la page précédente.

Limite et décalage. /account-transactions/ accepte limit (de 0 à 500) et offset (de 0 à 10 000) et ne renvoie pas d’objet pagination.

Limite seule. /subnet-price-history/, /price-history/, /network-stats/history/ et /search/ acceptent une limit.

Certaines listes renvoient toutes les lignes d’un coup, comme /v2/subnets/.

Erreurs

Chaque erreur que répond l’API a la même enveloppe JSON :

{ "error": true, "code": "RESOURCE_NOT_FOUND", "message": "Not found", "detail": null }

Statut	`code`	Signification
400	`VALIDATION_ERROR`	Un paramètre a échoué à une vérification. `message`, ou `detail` par champ, indique lequel.
404	`RESOURCE_NOT_FOUND`	Rien n’existe à cette adresse. La réponse peut être mise en cache 15 secondes.
405	`METHOD_NOT_ALLOWED`	Le point d’accès n’accepte pas cette méthode.
410	`ENDPOINT_REMOVED`	La route a été supprimée. `detail.replacement` nomme son successeur, s’il y en a un. Voir Dépréciations.
429	`RATE_LIMITED`	Vous avez dépassé une limite. Attendez `detail.retry_after` secondes.
500	`INTERNAL_ERROR`	Quelque chose a échoué sur le serveur.
503	`QUERY_TIMEOUT`	La requête a dépassé son budget de temps. Réessayez, ou restreignez la requête, par exemple sa plage de dates.

Les autres erreurs client portent un code nommé d’après l’erreur, comme PARSE_ERROR ou NOT_ACCEPTABLE. Les erreurs du proxy devant l’API, son 429 et le 502 ou 504 qu’il renvoie quand l’API ne répond pas, arrivent en HTML, pas en JSON : vérifiez le code de statut avant d’analyser le corps.

CORS

Les navigateurs refusent les appels à l’API depuis d’autres sites web : elle n’autorise que les propres pages de Taoswap. Appelez l’API depuis votre serveur, et faites lire votre serveur par vos pages.

Versions

Le chemin nu est la version 1, et /v1/ écrit cette version en toutes lettres : /trades/ et /v1/trades/ répondent la même chose, octet pour octet.
/v2/ porte les routes dont la réponse a changé de forme : /v2/subnets/, /v2/validators/ et /v2/extrinsics/. Leur forme en version 1 garde son ancienne forme jusqu’à sa dépréciation.
Les routes ajoutées plus récemment n’existent que sous /v1/, comme /v1/beta-baskets/ et /v1/account-ledger/.

Pour une nouvelle intégration, appelez /v2/ pour les subnets, les validateurs et les extrinsics. Pour les autres routes, le chemin nu et /v1/ sont équivalents.

Un nouveau champ ou filtre peut apparaître à tout moment sans préavis : ignorez donc les champs que vous n’utilisez pas. Un changement de forme donne une nouvelle version, et une route ne part que par le processus de dépréciation.

Étapes suivantes

Parcourez les points d’accès et générez un client typé : Référence de l’API.
Suivez les routes en voie de suppression : Dépréciations.
Posez vos questions sur Discord.