x402kit

A minimal, correct, safety-capped Python client for x402 pay-per-call HTTP APIs.

Most of the friction in x402 is the wire shape, not the crypto. A signed EIP-3009 authorization is rejected with a bare invalid_payload if it isn't nested the way the facilitator expects. This library builds that shape:

{
  "x402Version": 1,
  "paymentPayload": {
    "x402Version": 1, "scheme": "exact", "network": "base",
    "payload": { "signature": "0x..", "authorization": { "EIP-3009 fields": ".." } }
  },
  "paymentRequirements": { "...the accepts[i] object verbatim..." }
}

Posting those fields flat yields HTTP 400 invalid_payload.

Install

pip install x402kit            # free path (stdlib + requests-free)
pip install "x402kit[eth]"     # paid path: adds eth-account

Free path — inspect a price, spend nothing

import x402kit
r = x402kit.get("https://example.com/paid-endpoint")
if r.status_code == 402:
    for c in x402kit.parse_challenge(r):
        print(c.amount_usdc(), "USDC on", c.network, "->", c.pay_to)

Paid path — with a hard spending cap

from decimal import Decimal
import x402kit

r = x402kit.get(
    "https://example.com/paid-endpoint",
    private_key=open("key").read().strip(),
    max_spend_usdc=Decimal("0.10"),   # REQUIRED — the safety cap
    network="base",                    # USDC on Base only
)
print(r.json())

Safety guarantees

• Never signs before parsing a 402 — no blind spending.
• max_spend_usdc is required for the paid path. If the server asks for more, signing is refused. A malicious server cannot make you sign an unbounded authorization.
• USDC only, on the network you request. Any other asset/network is refused.
• Local signature self-check before the header is sent.
• Non-2xx after payment is a hard error, never reported as success.

Honest status

The wire shape was validated against a live facilitator's request gate (PayAI, network base, 2026-10-08), and the free path is exercised against a live 402. No payment has been settled on-chain by this library yet. Treat the paid path as new: use a throwaway wallet and a small max_spend_usdc.

License

MIT. Written by an autonomous AI agent.