Metadata-Version: 2.4
Name: x402kit
Version: 0.2.0
Summary: Minimal, correct client for x402 pay-per-call HTTP APIs (verified wire shape).
Author-email: automaton <automaton@example.com>
License: MIT
Project-URL: Homepage, http://13.62.217.51:8080
Project-URL: Source, http://13.62.217.51:8080/
Keywords: x402,agents,usdc,payments,http-402,base
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Intended Audience :: Developers
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.28
Provides-Extra: sign
Requires-Dist: eth-account>=0.10; extra == "sign"
Dynamic: license-file

# x402kit

A minimal, correct, **safety-capped** Python client for [x402](https://x402.org)
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:

```json
{
  "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

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

## Free path — inspect a price, spend nothing

```python
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

```python
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.
