# tools402

> 159 HTTP micro-APIs for AI agents. No account required to start (pay x402 direct). Optional API key for agents — sign once, one header per call. API: https://api.tools402.dev · Site: https://tools402.dev

## Instructions for agents

**Start without an account** — call any paid endpoint and pay the live `402` quote (path a).  
**Automate seller/account calls** — sign once to mint an API key (path b), then send `Authorization: Bearer t402_live_…` per request.

### (a) x402 per call (default buyer path)

1. **Quote** — request the endpoint without payment → `402 Payment Required` with `accepts[]`.
2. **Pay** — satisfy the quote on-chain or via facilitator (see [Buy-side flow](#buy-side-flow-x402) and [Payment rails](#payment-rails-3)).
3. **Retry** — same request + `X-Payment` or `X-Session-Token` → `200`.

The `pay` scope on an API key does **not** replace `X-Payment` / `X-Session-Token` on paid endpoints — x402 proof is still required per call.

### (b) API key (optional machine auth)

1. **Sign once** — EIP-712 `SellerAction` (domain below): `action: "issue_api_key"`, `payloadHash = keccak256(toBytes(JSON.stringify({ label, scopes: scopes.sort() })))` (`label` = `null` if omitted), `timestamp` in `[now − 300s, now + 60s]`.
2. **POST** `https://api.tools402.dev/v1/keys` — JSON body: `wallet`, `label?`, `scopes[]`, `signature`, `timestamp`. **No** `Authorization: Bearer` header (Bearer on this route → `403 signature_required`).
3. **201** — store `api_key` (`t402_live_…`); it is shown **only once**.
4. **Later calls** — `Authorization: Bearer t402_live_…` on routes that accept Bearer auth.

### Reading errors and retrying

Responses use JSON `{ "error": "…", "hint"?: "…", "message"?: "…" }`.

| HTTP | `error` | Agent action |
| --- | --- | --- |
| 402 | (x402 body) | Read `accepts[]`, pay, retry with payment proof |
| 401 | `invalid_api_key` | Fix or re-issue key (revoked/expired/wrong token) |
| 401 | `invalid_signature` | Re-sign; check timestamp window |
| 401 | `unauthorized` | Add Bearer or wallet signature query params |
| 403 | `insufficient_scope` | Re-issue key with required scope, or use wallet signature |
| 403 | `signature_required` | Wallet signature required — remove Bearer (see signature-only guards) |
| 400 | `invalid_input` / `invalid_scopes` | Fix request body |

## API keys (optional, live)

Wallet remains root identity. A key is a derived credential — sign once, one header per call.

### Issue — POST `/v1/keys`

- **Creation auth**: wallet signature only (`issue_api_key`; no Bearer).
- **201 response**: `api_key`, `key_prefix`, `scopes`, `warning` (secret never shown again).
- **GET** `https://api.tools402.dev/v1/keys` — scope `read` (Bearer or wallet signature).

### Account — GET `/v1/account`

- **Auth**: `Authorization: Bearer t402_live_…` + scope `balance:read`, or wallet signature (`action: "stats"`).
- **Response**: `wallet`, `earned_atomic`, `spent_atomic`, `withdrawable_atomic`, `payout_chain`, `endpoints_count`, `scopes`.
- **`withdrawable_atomic`**: net of ledger rows where `settlement_id IS NULL` (FK to `settlements.id`, migration 015).

### Scopes (5)

| Scope | Allows |
| --- | --- |
| `read` | list endpoints, stats, list key prefixes |
| `balance:read` | GET `/v1/account` |
| `endpoints:write` | POST/DELETE seller endpoints |
| `pay` | buyer identity scope — x402 payment proof still required per paid call |
| `payout:request` | POST payout toward **registered** payout address only |

Suggested profiles: **consumer** `read`, `pay` · **seller** `read`, `balance:read`, `endpoints:write` · **full** = all five (read, balance:read, endpoints:write, pay, payout:request).

### Signature-only guards (never Bearer)

A key can spend toward an already-approved payout destination; it cannot designate a new one or mint sibling keys.

| Route | Guard |
| --- | --- |
| **POST** `https://api.tools402.dev/v1/keys` | `403 signature_required` if Bearer present |
| **PUT** `https://api.tools402.dev/v1/_seller/<wallet>/payout-address` | `403 signature_required` if Bearer present |

## Buy-side flow (x402)

1. **Quote** — `POST` (or `GET`) the endpoint without payment → `402 Payment Required` with `accepts[]` (atomic USDC price, `payTo`, asset, scheme, network).
2. **Pay** — pick one rail (see below), satisfy the quote off-chain or on-chain.
3. **Retry** — same request + `X-Payment: <base64url(JSON)>` (or `X-Session-Token` for pre-signed EIP-3009 session mode) → `200` + `X-Payment-Confirmed` tx proof when applicable.

Always trust the live `402` quote (`payTo`, `maxAmountRequired`, `asset`) — never hardcode amounts in production.

## Payment rails (3)

| Scheme | Chains | Agent action | Snippet |
| --- | --- | --- | --- |
| `exact` | base, polygon, solana | Broadcast USDC transfer; send tx hash / receipt in `X-Payment` | [curl exact Base/Polygon](https://tools402.dev/docs/integrations#curl) · [buy-side guide](https://tools402.dev/buy-side) |
| `transfer-with-authorization` (EIP-3009) | base, polygon | Pre-sign `transferWithAuthorization`; facilitator submits gaslessly per call (`X-Session-Token` or `X-Payment`) | [session token snippets](https://tools402.dev/docs/integrations#session-token) |
| `spl-transfer` | solana | Partial-sign SPL transfer; facilitator is fee payer (do not self-broadcast) | [Solana spl-transfer](https://tools402.dev/docs/integrations#curl) |

## Chain matrix

**Buyer payment (3 chains)** — same-chain settlement at call time:

- **base**: schemes `exact, transfer-with-authorization` · USDC `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913` · payTo `0xD6E8aF2F65B4C9ACC7BF14A3096056e89E312878`
- **polygon**: schemes `exact, transfer-with-authorization` · USDC `0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359` · payTo `0xD6E8aF2F65B4C9ACC7BF14A3096056e89E312878`
- **solana**: schemes `exact, spl-transfer` · USDC `EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v` · payTo `Gt9EC4XYqD9pUmTFAfBy9b3gbGG8eiv3ZNLMLCuyU8w8`

**Seller payout (6 chains)** — `payout_chain` at register; cross-chain buyer→seller via CCTP V2 settlement:

- **base**: seller payout via CCTP V2 daily settlement
- **polygon**: seller payout via CCTP V2 daily settlement
- **arbitrum**: seller payout via CCTP V2 daily settlement
- **optimism**: seller payout via CCTP V2 daily settlement
- **avalanche**: seller payout via CCTP V2 daily settlement
- **solana**: seller payout via CCTP V2 daily settlement

## Sell-side flow

Free onboarding (no x402). Seller/account automation may use optional API keys (see [Instructions for agents](#instructions-for-agents)). Registration itself remains signature-only. EIP-712 domain: `{"name":"tools402","version":"1","chainId":8453}`. Timestamp window: `[now − 300s, now + 60s]` (Unix seconds).

### register

- **POST** `https://api.tools402.dev/v1/_seller/register`
- **payloadHash** = `keccak256(toBytes(`${slug}:${payout_chain}`))` (Model A — slug + payout chain bound together)
- **EIP-712** `SellerAction`: `wallet`, `action: "register"`, `payloadHash`, `timestamp`
- Slug: `^[a-z0-9-]{3,32}$`, globally unique
- Guide: [sell-side register](https://tools402.dev/docs/sell-side#register) · [home register snippet](https://tools402.dev/#seller)

### add_endpoint

- **POST** `https://api.tools402.dev/v1/_seller/<wallet>/endpoints`
- Canonical JSON (exact key order before hash): `path_suffix`, `upstream_url`, `atomic_price`, `unit`, `desc`, `mode` — optional `sample_body`, `alert_email` appended when present
- **payloadHash** = `keccak256(toBytes(canonicalJSON))`
- **EIP-712** `SellerAction`: `action: "add_endpoint"`
- Live path after probe pass: `/v1/<slug>/<path_suffix>`
- Guide: [sell-side add endpoint](https://tools402.dev/docs/sell-side#endpoint)

## Utility endpoints

- [GET /v1/_meta](https://api.tools402.dev/v1/_meta): live catalog (159 endpoints), pricing, `accepted_chains`
- [GET /v1/_health](https://api.tools402.dev/v1/_health): liveness + facilitator stack summary
- [GET /v1/_status](https://api.tools402.dev/v1/_status): operational status, cross-chain settlement state
- [GET /v1/keys](https://api.tools402.dev/v1/keys): list key prefixes (scope `read`)
- [GET /v1/account](https://api.tools402.dev/v1/account): unified balance (scope `balance:read`)
- [openapi.json](https://tools402.dev/openapi.json): OpenAPI 3.1 machine-readable contract (bun scripts/build-openapi.ts --write)

## Integration snippets (copy-paste)

- [Integrations hub](https://tools402.dev/docs/integrations): curl / session-token / Python / Node raw HTTP
- [Multi-chain](https://tools402.dev/docs/multi-chain): buyer vs payout chains, CCTP settlement
- [Buy-side](https://tools402.dev/buy-side): full `exact` flows
- [Sell-side](https://tools402.dev/docs/sell-side): register + add_endpoint + stats
- [Publish](https://tools402.dev/publish): seller onboarding walkthrough


## Full catalog

- [llms-full.txt](https://tools402.dev/llms-full.txt): all 159 endpoints with atomic price, unit, category (bun scripts/build-llms-txt.ts)