x402-agent

Framework-agnostic payer for the x402 HTTP payment protocol.

x402-agent is an independent open-source package. It is not affiliated with, endorsed by, or sponsored by the x402 Foundation, LF Projects, LLC, or Coinbase, Inc. "x402" is used nominatively to refer to the open HTTP payment protocol. Maintained by Xenarch.

Zero framework dependencies. Subclass or compose from LangChain, CrewAI, AutoGen, LangGraph, or anything else that wants to let an agent spend USDC against a 402 Payment Required response without rolling its own pay loop.

What it does

from decimal import Decimal
from x402_agent import X402Payer, BudgetPolicy

payer = X402Payer(
    private_key="0x...",
    budget_policy=BudgetPolicy(
        max_per_call=Decimal("0.05"),
        max_per_session=Decimal("1.00"),
    ),
)

result = payer.pay("https://example.com/gated/article")
# {"success": True, "body": "...", "amount_usd": "0.01", ...}

pay(url) walks the full challenge: GET → parse 402 → pick a supported (scheme, network) → enforce your budget → sign an EIP-3009 USDC authorisation → retry with the version-correct payment header (PAYMENT-SIGNATURE for V2, X-PAYMENT for V1 legacy gates) → return the unlocked body. Never raises; every failure mode is a dict you can show an LLM.

Async via await payer.pay_async(url).

What's in the package

Constants (DEFAULT_NETWORK, DEFAULT_SCHEME, X_PAYMENT_HEADER, X_PAYMENT_RESPONSE_HEADER, PAYMENT_SIGNATURE_HEADER, PAYMENT_RESPONSE_HEADER) are exported so adapters don't have to hard-code them.

Subclassing

The four hooks are the intended extension point. Override any subset:

class MyPayer(X402Payer):
    def _pre_payment_hook(self, *, url, accept, price):
        # Return an error dict to abort before the budget lock.
        if self._is_suspicious(accept.pay_to):
            return {"error": "refused_by_policy"}
        return None

    def _post_payment_hook(self, result, paid_response):
        # Mutate result in place; post runs after budget.commit().
        result["signed_by"] = "my-facilitator"

Pre-hook runs before the budget lock so a slow external check (reputation lookup, etc.) can't block other concurrent payments. Post-hook runs after the spend is committed so a receipt fetch failure can't revert a paid GET.

Stability

__all__ defines the v0.x stable surface. Anything in x402_agent._helpers or x402_agent._payer is accessible but subject to rename.

Licence

MIT.