Metadata-Version: 2.4
Name: algorand-x402-client
Version: 0.1.0
Summary: Lightweight Algorand Indexer client: Nodely free queries + x402 paid queries to api.algorand-indexer.xyz
Author: thecryptomie
License-Expression: MIT
Project-URL: Homepage, https://github.com/thecryptomie/algorand-x402-client
Project-URL: Repository, https://github.com/thecryptomie/algorand-x402-client
Project-URL: Issues, https://github.com/thecryptomie/algorand-x402-client/issues
Project-URL: Documentation, https://api.algorand-indexer.xyz
Keywords: algorand,indexer,x402
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: algokit-utils<5,>=4.2.3
Requires-Dist: x402-avm[avm,httpx,requests]>=2.0.2
Requires-Dist: httpx>=0.28.1
Requires-Dist: requests>=2.32.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == "dev"
Requires-Dist: pytest-cov>=5.0.0; extra == "dev"
Requires-Dist: ruff>=0.6.0; extra == "dev"
Provides-Extra: publish
Requires-Dist: build>=1.2.0; extra == "publish"
Requires-Dist: twine>=5.0.0; extra == "publish"
Dynamic: license-file

# algorand-x402-client

Python Indexer client that wraps AlgoKit Utils and py-algorand-sdk `IndexerClient`:

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

The library does **not** reimplement Indexer REST. It injects HTTP under the official
`IndexerClient` so lookups, searches, and pagination stay upstream.

Paid and free backends share the same Indexer contract (complete history). They
differ by billing and rate limits. There is no silent “try Nodely, then pay”
default — that would spend USDC on 429s.

## Install

Python 3.10+:

```bash
pip install algorand-x402-client
# or: uv add algorand-x402-client
```

## Usage

```python
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 `IndexerClient`s
(`health()`, `account_info()`, `search_transactions()`, …).
`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).

Environment: `BUYER_MNEMONIC`, `X402_BASE_URL`, `X402_NETWORK`, `ALGORAND_X402_LOG_FILE`.

## Docs

- Repository: https://github.com/thecryptomie/algorand-x402-client
- Gateway health: https://api.algorand-indexer.xyz/health
- OpenAPI: https://api.algorand-indexer.xyz/openapi.json
