x402 HTTP payments¶

x402 is a pattern where a resource responds with HTTP 402 and machine-readable payment requirements; the client pays on-chain (here: Algorand USDC per the exact Algo scheme), then retries the request with proof of payment.

Using x402 with AlgoPay¶

Pass an https:// URL as recipient to pay():

result = await client.pay(
    wallet_id,
    "https://api.example.com/protected/resource",
    "2.5",  # max USDC you allow this resource to charge
)
if result.success and result.resource_data is not None:
    # Final response body / parsed payload depends on adapter
    print(result.resource_data)

The X402Adapter (see algopay.protocols.x402) handles discovery, quote acceptance within your cap, signing, and the paid retry.

Dependencies¶

The package depends on x402-avm[avm] and httpx for HTTP and protocol handling (see python/pyproject.toml or PyPI metadata).

Environment and examples¶

Example script in the repo: python/examples/x402_client_demo.py.

Set:

Variable	Purpose
`ALGOPAY_X402_URL`	HTTPS URL that returns x402 payment requirements
`ALGOPAY_MAX_USDC`	Maximum USDC for the demo client

Full SDK env reference: Environment variables.

Guards and URLs¶

Recipient guards support domains and patterns so agents only pay approved x402 endpoints.

TypeScript parity¶

The npm package @algodev-studio/algopay (typescript/) implements the same HTTPS → x402 routing for pay() using @x402-avm/fetch and @x402-avm/avm. See x402 stack and the package README.