APIs das aplicações

O que são

A interface da cadeia é o JSON-RPC. Tudo o que está nestas páginas é algo que uma aplicação construiu para si mesma e depois deixou alcançável: um índice Postgres sobre o spool de logs do sequenciador, um processo que detém uma chave, um laço de jogo. É prático, é de primeira parte, e não é autoritativo.

Onde respondem

Nenhum desses serviços tem um nome de host próprio. Cada um é uma montagem /api/ na origem de uma interface, o que faz da base pública um fato do nginx e não um fato do serviço: uma implantação que move um site move a API dele junto, e o caminho interno continua o mesmo. Numa pilha que você mesmo roda, os mesmos serviços respondem no loopback, na porta que a página de cada um nomeia.

Autenticação

Nenhum dos quatro pede autenticação, e a diferença que conta é o que cada um consegue fazer sem ela.

• O explorador, a API do DEX e o arcade não pedem nenhuma. São somente de leitura e públicos. O explorador responde 405 a todo POST; a API do DEX não implementa nenhum verbo além de GET.
• O faucet também não pede nenhuma, e ele escreve na cadeia. É toda a razão pela qual a cota dele é estrita e é reservada antes de qualquer assinatura.

Chamar um deles de um navegador

O CORS é ajustado serviço a serviço e eles não concordam entre si, então a primeira coisa a estabelecer é se uma página da sua origem consegue chamar aquele que você quer.

• A API do DEX não envia nenhum cabeçalho CORS e não tem manipulador OPTIONS. Um fetch de outra origem a partir de um navegador falha de cara enquanto a mesma requisição a partir de um servidor tem sucesso, que é a forma de bug que se costuma culpar na rede. Passe por um proxy, ou chame-a de um backend.
• O explorador e o faucet mantêm listas de permissões. Um preflight vindo de uma origem que não está na lista é recusado com 403, o que pelo menos é uma resposta clara.
• O arcade confere o Origin no upgrade e recusa 403 antes do aperto de mão, então o socket nunca abre em vez de abrir e ficar calado.

Limites e paginação

Só o explorador limita a taxa de requisições. Os outros três se apoiam numa trava, numa cota ou num teto de conexões.

Onde há paginação, ela é limit e offset, não um cursor. Isso quer dizer que uma lista que cresce pela cabeça desliza debaixo de você entre duas páginas: linhas já vistas reaparecem, e linhas nunca vistas podem ser puladas. Para qualquer coisa que precise ser completa, pagine por uma chave que você controla - um número de bloco, um hash - e não por um offset.

Convenções

// 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

Quando um está fora do ar

Cada um dos quatro falha de um jeito, e só uma dessas falhas se parece com uma falha vista de fora.

• A API do DEX responde 503 index not ready quando o banco de dados está inalcançável ou o indexador nunca rodou, então as tabelas não existem. Esse é o caso honesto. O desonesto é um indexador que PAROU: todas as rotas continuam respondendo com o estado a que ele chegou, e só o lagBlocks em /health diz isso.
• O explorador continua servindo o índice quando o nó está inalcançável, e as partes de uma resposta que exigem uma leitura ao vivo - um saldo, um registro do serviço de nomes, o saldo pendente do roteador de taxas - voltam nulas ou ausentes em vez de dar erro. O campo indexLag em /stats é o número a vigiar.
• O faucet responde 502 quando o nó não responde, e nada foi assinado. Um 503 quer dizer que ele está sem fundos, ou que o drip deu revert.
• O /ready do arcade responde 503 quando o socket dele para o nó caiu, ou quando o último minibloco que ele APLICOU tem mais de cinco segundos. Medir a chegada no lugar disso deixava um processo travado responder 200 sem que nada se mexesse.

O que está documentado em outro lugar

• 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.