API des applications

Ce que c'est

L'interface de la chaîne est le JSON-RPC. Tout ce qui est sur ces pages est quelque chose qu'une application s'est construit puis a laissé joignable : un index Postgres sur le spool de logs du séquenceur, un processus qui détient une clé, une boucle de jeu. C'est pratique, c'est de première partie, et ce n'est pas faisant autorité.

Où ils répondent

Aucun de ces services n'a de nom d'hôte à lui. Chacun est un montage /api/ sur l'origine d'une interface, ce qui fait de la base publique un fait nginx plutôt qu'un fait de service : un déploiement qui déplace un site déplace son API avec lui, et le chemin à l'intérieur reste le même. Sur une pile que vous faites tourner vous-même, les mêmes services répondent sur le bouclage, sur le port que nomme la page de chacun d'eux.

Authentification

Aucun des quatre ne demande d'authentification, et la différence qui compte est ce que chacun peut faire sans.

• L'explorateur, l'API du DEX et l'arcade n'en prennent aucune. Ils sont en lecture seule et publics. L'explorateur répond 405 à tout POST ; l'API du DEX n'implémente aucun verbe sauf GET.
• Le faucet n'en prend aucune non plus, et il écrit sur la chaîne. C'est toute la raison pour laquelle son quota est strict et est réservé avant toute signature.

En appeler un depuis un navigateur

Le CORS est réglé service par service et ils ne sont pas d'accord entre eux, donc la première chose à établir est si une page de votre origine peut appeler celui que vous voulez.

• L'API du DEX n'envoie aucun en-tête CORS et n'a pas de gestionnaire OPTIONS. Un fetch multi-origine depuis un navigateur échoue net alors que la même requête depuis un serveur réussit, ce qui est la forme de bug qu'on impute au réseau. Passez par un proxy, ou appelez-la depuis un backend.
• L'explorateur et le faucet tiennent des listes d'autorisation. Un préflight venu d'une origine absente de la liste est refusé 403, ce qui est au moins une réponse claire.
• L'arcade vérifie l'Origin à la montée en WebSocket et refuse 403 avant la poignée de main, donc le socket ne s'ouvre jamais plutôt que de s'ouvrir et de se taire.

Limites et pagination

Seul l'explorateur limite le débit des requêtes. Les trois autres s'appuient sur un écrêtage, un quota ou un plafond de connexions.

Là où la pagination existe, c'est limit et offset, pas un curseur. Cela veut dire qu'une liste qui grandit par la tête glisse sous vous entre deux pages : des lignes déjà vues réapparaissent, et des lignes jamais vues peuvent être sautées. Pour tout ce qui doit être complet, paginez sur une clé que vous contrôlez - un numéro de bloc, un hash - plutôt que sur un offset.

Conventions

// The shape of a careful call against any of these: a timeout, a status check
// before the body, and a big-integer parse of anything that looks like money.
const res = await fetch(`${BASE}/pools`, { signal: AbortSignal.timeout(5000) });
if (!res.ok) throw new Error(`pools: ${res.status}`);          // never the message
const { pools } = await res.json();                              // an object, not an array
const reserve0 = BigInt(pools[0].reserve0);                      // a decimal string

Quand l'un est en panne

Chacun des quatre échoue différemment, et un seul de ces échecs ressemble à un échec vu de l'extérieur.

• L'API du DEX répond 503 index not ready quand la base de données est injoignable ou que l'indexeur n'a jamais tourné, donc que les tables n'existent pas. C'est le cas honnête. Le cas malhonnête est un indexeur qui s'est ARRÊTÉ : toutes les routes continuent de répondre avec l'état qu'il a atteint, et seul lagBlocks sur /health le dit.
• L'explorateur continue de servir l'index quand le nœud est injoignable, et les parties d'une réponse qui demandent une lecture en direct - un solde, un enregistrement du service de noms, le solde en attente du routeur de frais - reviennent nulles ou absentes plutôt qu'en erreur. Le champ indexLag sur /stats est le chiffre à surveiller.
• Le faucet répond 502 quand le nœud ne répond pas, et rien n'a été signé. Un 503 veut dire qu'il est à court de fonds, ou que le drip a revert.
• Le /ready de l'arcade répond 503 quand son socket vers le nœud est tombé, ou quand le dernier mini-bloc qu'il a APPLIQUÉ a plus de cinq secondes. Mesurer l'arrivée à la place laissait un processus coincé répondre 200 sans que rien ne bouge.

Ce qui est documenté ailleurs

• The node. Chain state, transactions, logs and subscriptions are JSON-RPC and are documented in this reference's own RPC pages, not here.
• Contracts. What the pools, the faucet and the games actually do on chain - their functions, their events and their revert reasons - is the contract reference.
• Prices. Several answers here carry a dollar figure or a price snapshot. Those fields come from a layer this page does not own; read its own reference for what the number means, how old it is and when it is absent.