Metadata-Version: 2.4
Name: x402-pay
Version: 0.3.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"
Provides-Extra: langchain
Requires-Dist: langchain-core>=0.3; extra == "langchain"
Dynamic: license-file

# x402-pay

Call any x402 API with one line of Python. No wallet needed.

```python
import x402_pay

resp = x402_pay.get("https://weather.hugen.tokyo/weather/current?city=Tokyo")
print(resp.json())
```

Auto-provisions an API key with $0.05 trial credit on first use.
Routes requests through a broker that handles on-chain payment on your behalf.

## Install

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

## Usage

### One-liner (sync)

```python
import x402_pay

resp = x402_pay.get("https://weather.hugen.tokyo/weather/current?city=Tokyo")
print(resp.json())

resp = x402_pay.post("https://defi.hugen.tokyo/defi/simulate", json={
    "chain_id": "1", "from": "0xABC...", "to": "0xDEF...",
})
```

### Async client

```python
from x402_pay import PayClient

async with PayClient() as client:
    resp = await client.get("https://weather.hugen.tokyo/weather/current?city=Tokyo")
    print(resp.json())
    print(f"Balance: ${await client.balance():.2f}")
```

### Explicit API key

```python
from x402_pay import PayClient

async with PayClient(api_key="gw_YOUR_KEY") as client:
    resp = await client.get("https://defi.hugen.tokyo/defi/token?chain=ethereum&address=0x...")
```

### Wallet mode (power users)

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

```python
from x402_pay import DirectClient

async with DirectClient(private_key="0x...") as client:
    resp = await client.get("https://weather.hugen.tokyo/weather/current?city=Tokyo")
```

## API Key Lifecycle

1. First call auto-creates a key with $0.05 trial balance (10 calls at $0.005)
2. Key saved to `~/.x402-pay/config.json`
3. After trial: top up at the URL from `await client.topup_url()` ($1.00 x402 payment)
4. Or bring your own key: `PayClient(api_key="gw_...")`

## Configuration

| 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 Reference

### Module-level (sync)

- `x402_pay.get(url, **kwargs)` -- sync GET through broker
- `x402_pay.post(url, **kwargs)` -- sync POST through broker
- `x402_pay.balance(api_key="")` -- check balance

### PayClient (async)

- `PayClient(api_key="", broker_url="", timeout=60.0)`
- `await client.get(url, **kwargs)` -- GET through broker
- `await client.post(url, **kwargs)` -- POST through broker
- `await client.balance()` -- balance in USD
- `await client.topup_url()` -- URL to top up key balance

### DirectClient (async, requires `[wallet]`)

- `DirectClient(private_key="0x...")`
- `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
