algorand-x402-client
Query Algorand Indexer with the official py-algorand-sdk / AlgoKit client. 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 (account_info(), search_transactions(),
pagination helpers). Under the hood the official IndexerClient is pointed at
one of two transports:
.free— send the request to Nodely. No payment headers, no USDC..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
Python 3.10+:
pip install algorand-x402-client
# or: uv add algorand-x402-client
Usage
import os
from algorand_x402_client import Payer, configure_logging, create_algorand_indexer, get_logger
configure_logging() # stderr + algorand-x402-client.log
logger = get_logger(__name__)
indexer_client = create_algorand_indexer(
"mainnet",
payer=Payer(mnemonic=os.environ["BUYER_MNEMONIC"]), # omit for free-only
)
# Nodely — never sends PAYMENT-SIGNATURE, never spends USDC
account = indexer_client.free.account_info("JRG3CUVOFK3YJK3QDD4IOWKMHHRCWVTEMUSYKDN7U73FQO5ZYTCC7CEBRQ")
# x402 gateway — HTTP 402 → sign USDC → retry (search tier is $0.0001)
paid = indexer_client.paid.account_info("JRG3CUVOFK3YJK3QDD4IOWKMHHRCWVTEMUSYKDN7U73FQO5ZYTCC7CEBRQ")
logger.info("gateway network=%s", indexer_client.gateway.health()["network"])
indexer_client.close()
indexer_client.free / indexer_client.paid are py-algorand-sdk IndexerClients.
indexer_client.algorand_free is AlgorandClient.from_clients with Nodely algod
- the free Indexer.
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, ALGORAND_X402_LOG_FILE.
How the HTTP layer is swapped
py-algorand-sdk’s IndexerClient has no session hook, so this library subclasses
it (SessionIndexerClient) and sends every call through a requests.Session.
- Free session — plain
requests, plus backoff on HTTP 429. - Paid session — the same session wrapped with x402-avm
wrapRequestsWithPayment. 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
Metadata
Release files for algorand-x402-client 0.2.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| algorand_x402_client-0.2.0.tar.gz | 12.1 kB | With provenance | Details for algorand_x402_client-0.2.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| algorand_x402_client-0.2.0-py3-none-any.whl | Python 3 | none | any | Details for algorand_x402_client-0.2.0-py3-none-any.whl |
Total release size: 27.5 kB
Release files / algorand_x402_client-0.2.0.tar.gz
| Download URL | algorand_x402_client-0.2.0.tar.gz |
|---|---|
| Size | 12.1 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
86a2f8425f9c3f42955bd2e6e41d7fb7347e5b59c2b8753e099fa3fb1895586f
|
|
BLAKE2b-256 checksum How to use checksums |
088a64464babad7b09c3620cb063ac25db9c23e0bad45fda6dce1e0f4516a83b
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 30, 2026.
Transparency logRelease files / algorand_x402_client-0.2.0-py3-none-any.whl
| Download URL | algorand_x402_client-0.2.0-py3-none-any.whl |
|---|---|
| Size | 15.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
3e1e5e858bd5a01fc51f3f9579c173651ec96d6c84ac0d4de2bf01cce221de36
|
|
BLAKE2b-256 checksum How to use checksums |
3eba1ca80343791136496d843b5c0ab0974087993d6f2f836bbf592abca5f2ac
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 30, 2026.
Transparency logSecurity for algorand-x402-client 0.2.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for algorand_x402_client-0.2.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 30, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.