Metadata-Version: 2.4
Name: x402-pay
Version: 0.1.0
Summary: Pay for x402 APIs with 3 lines of Python — no wallet needed
Author-email: hugen <dev@hugen.tokyo>
License-Expression: MIT
Project-URL: Homepage, https://github.com/hugen-tokyo/x402-pay
Project-URL: Documentation, https://discovery.hugen.tokyo/llms.txt
Project-URL: Issues, https://github.com/hugen-tokyo/x402-pay/issues
Keywords: x402,micropayments,api,pay-per-call,usdc
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
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
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx>=0.27
Provides-Extra: wallet
Requires-Dist: x402[evm,httpx]>=2.1.0; extra == "wallet"
Requires-Dist: eth-account>=0.13; extra == "wallet"
Dynamic: license-file

# x402-pay

Call any x402 API with one API key. No per-API wallet integration needed.

```python
from x402_pay import PayClient

async with PayClient(api_key="gw_your_topped_up_key") as client:
    resp = await client.get("https://weather.hugen.tokyo/weather/current?city=Tokyo")
    print(resp.json())
```

Routes requests through a broker that handles on-chain payment on your behalf. $0.01/call.

## Install

```bash
pip install x402-pay
```

## Modes

### API Key Mode (default, no wallet)

Get a key and top it up first:
```bash
# Create key (free, gets $0.05 search credit)
curl -X POST https://discovery.hugen.tokyo/keys/create
# Top up to unlock broker ($1.00 x402 payment)
curl -X POST "https://discovery.hugen.tokyo/keys/topup?key=gw_YOUR_KEY"
```

Then use it:
```python
from x402_pay import PayClient

async with PayClient(api_key="gw_YOUR_KEY") as client:
    # Any x402 API — broker pays upstream, deducts $0.01 from your key
    resp = await client.get("https://weather.hugen.tokyo/weather/current?city=Tokyo")
    print(resp.json())

    # Check remaining balance
    print(f"${await client.balance():.2f}")
```

### Wallet Mode (power users)

```bash
pip install x402-pay[wallet]
```

```python
from x402_pay import DirectClient

async with DirectClient(private_key="0x...") as client:
    # Pay upstream directly from your wallet — no broker fee
    resp = await client.get("https://weather.hugen.tokyo/weather/current?city=Tokyo")
    print(resp.json())
```

## Configuration

API keys are stored in `~/.x402-pay/config.json`. Override with environment variables:

| Variable | Default | Description |
|----------|---------|-------------|
| `X402_API_KEY` | auto-created | API key for broker mode |
| `X402_BROKER_URL` | `https://discovery.hugen.tokyo` | Broker endpoint |
| `X402_PAY_CONFIG_DIR` | `~/.x402-pay` | Config directory |

## API

### PayClient

- `PayClient(api_key="", broker_url="", timeout=60.0)` — create client
- `await client.get(url)` — GET request through broker
- `await client.post(url, json={...})` — POST request through broker
- `await client.balance()` — check key balance in USD
- `client.api_key` — current API key

### DirectClient

- `DirectClient(private_key="0x...")` — create wallet client
- `await client.get(url)` / `await client.post(url)` — direct x402 payment

### Exceptions

- `PayError` — base exception
- `InsufficientBalance` — key balance too low (`.balance`, `.needed`, `.topup_url`)
- `NotInCatalog` — URL not in x402 catalog (`.url`)
- `BrokerError` — upstream call failed (`.refunded`)

## License

MIT
