Skip to main content

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:

  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

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

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)

Source distribution for algorand-x402-client 0.2.0
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)

Table of built distributions (wheels) for algorand-x402-client 0.2.0
File Interpreter ABI Platform Actions
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 log

Release 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 log

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

Select from 2 files

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 log

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

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page