API reference

Service surfaces

Configure each base URL independently. A deploymentId mismatch is a release error, not a reason to silently merge data from another network.

Indexer REST endpoints

The REST projection is intentionally close to the frontend hooks. Addresses and hashes are hex strings. uint256, uint64, amounts, and ids are decimal strings in JSON so consumers do not lose precision through JavaScript numbers.

Read the current round

const response = await fetch(`${INDEXER_URL}/lotto-uma/current`);
if (!response.ok) throw new Error(`indexer HTTP ${response.status}`);
const snapshot = await response.json();
if (!snapshot) throw new Error("No current round");

if (snapshot.deploymentId !== EXPECTED_DEPLOYMENT_ID) {
  throw new Error("indexer is serving another deployment");
}
if (snapshot.effectiveStatus === "betting_open") {
  // still simulate the contract call before presenting a buy button
}

Deposit authorization API

POST /api/v1/deposit-authorizations accepts userAddress, token, and amount. amount is a positive decimal string in the token's smallest unit. The service checks the backend whitelist, AML decision, single-transaction limit, and rolling daily limit before signing.

POST /api/v1/deposit-authorizations HTTP/1.1
content-type: application/json

{"userAddress":"0x...","token":"0x...","amount":"1000000"}

200 OK
{"user":"0x...","token":"0x...","amount":"1000000",
 "deadline":"1780000000","nonce":"42","signature":"0x..."}

Backend utility endpoints

These endpoints are convenience surfaces, not custody or settlement APIs. They may be unavailable when the upstream bridge provider is unavailable, and their output must be checked against the active manifest before use.

GraphQL and SQL over HTTP

The indexer also mounts /graphql and /sql/* for integrations that need filtered or analytical queries. These endpoints expose indexed data, not privileged chain writes. The generated schema is available in indexer/generated/schema.graphql and should be pinned by clients that need a stable query contract.

query CurrentRounds {
  lotto3dRounds(limit: 5, orderBy: "roundId", orderDirection: "desc") {
    items { roundId status winningNumber updatedAtBlock }
  }
}

Errors, retries, and consistency

• Retry idempotent GET requests with bounded backoff. Do not blindly retry a wallet write or deposit authorization after a timeout without checking whether the nonce was consumed.
• HTTP 503 from /admin/health or an empty indexer response means the read model is unavailable; it does not mean funds or a round disappeared.
• Use the chain receipt to resolve ambiguous writes. The indexer can be backfilled or restarted without changing contract state.
• Treat unknown fields as forward-compatible and preserve decimal strings as bigint/BigNumber values in the client.