# x402 API Payments

Fetch a paid API endpoint, paying automatically from the agent wallet. x402 is a payment protocol: the server returns HTTP 402, the CLI pays, and the server returns the content.

**x402 only works on Base.** The agent must be registered on the `base` network and hold USDC on Base. If the active agent is on a different chain (e.g. Solana), register a new agent on Base first — chain is fixed per agent.

## Before fetching — check balance

Run: `lobstercash crypto balance`

If the USDC balance on Base is 0 or below the expected payment amount, stop and tell the user funds are needed first. Use `lobstercash crypto request --amount <n> --description "<desc>"` to top up.

## Command

```bash
lobstercash crypto x402 fetch <url>
```

For POST requests add: `--json '{"key": "value"}'`
For custom headers add: `--header "Authorization: Bearer <token>"`
To raise the signature timeout add: `--timeout <ms>` (default 120000, minimum 5000).
To see the full payment negotiation on stderr add: `--debug`.

There is no `--network` flag — payment always happens on Base using the active agent's wallet.

## Reading the output

Key fields:

- `status`: HTTP response status code (200 = success)
- `body`: the response body as a string — parse as JSON if needed
- `paymentSucceeded`: boolean — true means payment succeeded and content received
- `contentType`: the response content type

## If the fetch fails

Add `--debug` to the same command and run it again. Debug output goes to stderr and shows the 402 `accepts` array, the signed payment payload, and the phase-2 response — exactly where the payment flow broke.

Common failures:

- `"x402 payment failed: server returned 402 after payment attempt"`: the facilitator rejected the signed authorization. Verify the agent is registered as an `external-wallet` delegated signer on the Base smart wallet, and that the 402 `accepts` entry targets Base USDC.
- Network error before 402: the URL is wrong or the server is down.
- Balance insufficient: top up via `lobstercash crypto request` or lobster.cash/dashboard.
- Agent not on Base: register a new agent on the `base` network — x402 will not run against Solana or other chains.

## Reporting to the user

Report what the API returned (`body`), not the payment mechanics. Only mention payment if the user asks.