Metadata-Version: 2.4
Name: x402-pay
Version: 0.4.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/bartonguestier1725-collab/x402-pay
Project-URL: Documentation, https://discovery.hugen.tokyo/llms.txt
Project-URL: Issues, https://github.com/bartonguestier1725-collab/x402-pay/issues
Keywords: x402,micropayments,api,pay-per-call,usdc,ai-agent,broker,base-chain
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
```

## Quick Demo

```bash
python -m x402_pay demo
```

Walks through key creation, API call, and balance check in 10 seconds.

## 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...",
})
```

### Discover APIs

```python
import x402_pay

apis = x402_pay.discover("token security")
for api in apis:
    print(f"{api['description']} — {api['price']}")
    resp = x402_pay.get(api["url"])
```

### 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")
```

## How Billing Works

1. **First call** auto-creates an API key with $0.05 trial credit
2. Key saved to `~/.x402-pay/config.json`
3. Each API call deducts from your balance ($0.005–$0.50 depending on the API)
4. **Low balance warning** prints to stderr when you have ~1 call left
5. When balance runs out, `InsufficientBalance` is raised with a topup URL

### Topping up

```python
try:
    resp = x402_pay.get("https://scout.hugen.tokyo/scout/hn?q=AI")
except x402_pay.InsufficientBalance as e:
    print(f"Balance: ${e.balance:.2f}, need: ${e.needed:.2f}")
    print(f"Top up ($1.00 USDC on Base): {e.topup_url}")
```

The topup URL accepts a **$1.00 x402 payment** (USDC on Base chain).
After payment, your key is credited immediately and you can retry the call.

Check your balance anytime:

```bash
python -m x402_pay balance
```

## Verbose Mode

See cost and balance after every call:

```python
import x402_pay
x402_pay.set_verbose()

resp = x402_pay.get("https://weather.hugen.tokyo/weather/current?city=Tokyo")
# stderr: [x402-pay] cost=$0.0050 balance=$0.0450
```

Or via environment variable:

```bash
X402_VERBOSE=1 python my_script.py
```

## 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 |
| `X402_VERBOSE` | off | Print cost/balance to stderr |

## CLI

```
python -m x402_pay demo     # live walkthrough
python -m x402_pay balance  # check credit
python -m x402_pay info     # show config details
```

## 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()` — check balance in USD
- `x402_pay.discover(query, limit=5)` — search API catalog
- `x402_pay.set_verbose(True)` — enable cost/balance output

### PayClient (async)

- `PayClient(api_key="", broker_url="", timeout=60.0)`
- `await client.get(url)` / `await client.post(url)` — API calls
- `await client.balance()` — balance in USD
- `await client.topup_url()` — URL to add credit
- `await client.discover(query)` — search API catalog

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

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

### Exceptions

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

## License

MIT
