algorand-x402-client

Query Algorand Indexer with the official AlgoKit Utils IndexerClient. This package does not add a new query API. It only changes where the HTTP goes, and whether that request can pay.

| Backend | Default origin | Auth | Data | | --- | --- | --- | --- | | .free | Nodely / AlgoNode (AlgoKit getAlgoNodeConfig) | none | full archival Indexer v2 | | .paid | MainNet https://api.algorand-indexer.xyz, TestNet https://testnet.algorand-indexer.xyz | x402 USDC (exact / AVM) | private full Indexer (genesis → tip) |

You call the same methods as always (lookupAccountById(), searchForTransactions(), pagination helpers). Under the hood the official IndexerClient is pointed at one of two transports:

1. .free — send the request to Nodely. No payment headers, no USDC.
2. .paid — send the same path to the x402 gateway. If the gateway replies HTTP 402, the client signs a USDC payment (capped), retries once with a payment signature, and returns the Indexer JSON.

Both backends speak vanilla Indexer REST and retain history from genesis. They differ by billing and rate limits, not by how far back data goes. There is no silent “try Nodely, then pay” fallback — a free-tier 429 would otherwise spend USDC.

Install

Node 20+:

npm install algorand-x402-client

ESM only ("type": "module").

Usage

import { createAlgorandIndexer } from "algorand-x402-client";

const indexerClient = createAlgorandIndexer({
  network: "mainnet",
  payer: { mnemonic: process.env.BUYER_MNEMONIC }, // omit for free-only
});

const free = await indexerClient.free.lookupAccountById(
  "JRG3CUVOFK3YJK3QDD4IOWKMHHRCWVTEMUSYKDN7U73FQO5ZYTCC7CEBRQ",
);

const paid = await indexerClient.paid.lookupAccountById(
  "JRG3CUVOFK3YJK3QDD4IOWKMHHRCWVTEMUSYKDN7U73FQO5ZYTCC7CEBRQ",
);

const health = await indexerClient.gateway.health();

indexerClient.free / indexerClient.paid are AlgoKit Utils v10 IndexerClients (healthCheck(), lookupAccountById(), searchForTransactions(), …).

Payer must be opted into USDC: MainNet 31566704, TestNet 10458941. Default max payment is 10_000 microUSDC ($0.01). network: "testnet" points .paid / .gateway at https://testnet.algorand-indexer.xyz.

Environment: BUYER_MNEMONIC, X402_BASE_URL, X402_NETWORK.

How the HTTP layer is swapped

AlgoKit Utils v10 IndexerApi accepts a custom BaseHttpRequest. This library supplies one that uses fetch.

• Free — plain fetch, plus backoff on HTTP 429.
• Paid — fetch wrapped with @x402/fetch wrapFetchWithPayment and @x402/avm ExactAvmScheme. The wrapper owns the 402 → sign → retry loop. Suggested params for the payment group come from Nodely algod, not from the Indexer.

You still get official response types. Only the transport is ours.

Docs

• Repository: https://github.com/thecryptomie/algorand-x402-client
• MainNet gateway health: https://api.algorand-indexer.xyz/health
• MainNet OpenAPI: https://api.algorand-indexer.xyz/openapi.json
• TestNet gateway health: https://testnet.algorand-indexer.xyz/health
• TestNet OpenAPI: https://testnet.algorand-indexer.xyz/openapi.json