# Tollex for agents Instructions for an AI agent or coding agent integrating Tollex. Use the structured endpoints below; do not scrape the website. ## The canonical path (do these in order) 1. **Discover**: `GET https://api.tollex.org/.well-known/tollex.json`. 2. **Inspect capabilities**: `GET https://api.tollex.org/v1/catalog` (ids, input schemas, prices). 3. **Plan for the need**: `POST https://api.tollex.org/v1/resolve` `{"need": "..."}`. Free. 4. **Get the terms**: `POST https://api.tollex.org/tools/{toolId}` without payment, read the `402`. 5. **Pick the rail your wallet holds**: USDC on Base (`eip155:8453`) or USDG on Robinhood Chain (`eip155:4663`). Pin the asset address of that rail (table below). If the payer holds neither, stop and tell the human. 6. **Enforce the ceiling**: refuse when `amount` > the ceiling the human configured. Never pick a ceiling yourself. 7. **Ask before paying** unless the human has explicitly enabled autonomous payment with that ceiling. 8. **Pay**: sign EIP-3009 for exactly `amount` to `payTo` and resend with `PAYMENT-SIGNATURE` (details below). 9. **Use the result** and **verify the receipt** (below). Show the Blockscout link. 10. **On rejection or uncertainty**: follow the outcomes table; never re-sign before checking the operation. First success, no wallet needed (steps 1 to 4): ```bash curl -s https://api.tollex.org/v1/resolve -H 'content-type: application/json' -d '{"need":"latest block on Robinhood Chain"}' curl -s -D - -o /dev/null -X POST https://api.tollex.org/tools/chain_get_block -H 'content-type: application/json' -d '{"block":"latest"}' | grep -i '^payment-required:' ``` Minimum integration to build when a human asks you to "integrate Tollex": a `plan(need)` function (step 3), a `terms(toolId, input)` function (step 4), a `buy(toolId, input)` function gated by a configured ceiling and an explicit opt-in (steps 5 to 8), and `verifyReceipt(receipt)` (step 9). Reference implementations: [TypeScript](examples/typescript/src/tollex.ts), [Python](examples/python/tollex_client.py). ## What Tollex is A paid-capability service for autonomous software, live on mainnet. An agent plans for free, pays per call with **x402 v2** (`exact` scheme, EIP-3009) in **USDC on Base** or **USDG on Robinhood Chain**, and receives the result with a **signed receipt**. Tollex enforces price and terms before money moves, settles with its own facilitator, and reconciles every settlement on chain. ## Payment rails (both accepted; the 402 lists one option per rail) | Rail | Network | Asset | EIP-712 domain | Notes | | --- | --- | --- | --- | --- | | Base | `eip155:8453` | USDC `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913` (6 decimals) | "USD Coin" / "2" | an `@x402` default asset: stock clients pay it with no extra config | | Robinhood Chain | `eip155:4663` | USDG `0x5fc5360D0400a0Fd4f2af552ADD042D716F1d168` (6 decimals) | "Global Dollar" / "1" | allow it explicitly in `@x402` `spendControls.allowedAssets` | Same price on both rails. Same capabilities, receipts and recovery. The receipt's `payment.network` names the rail. A quote (`/v1/quote`, or `/v1/resolve` with `quote: true`) is priced on ONE rail: pass `"network"` (quote) or `constraints.networks` (resolve, A2A `execute_intent`) for the rail you will pay on; a quote-bound 402 offers only that rail. **Try a real mainnet call:** [docs/TRY.md](docs/TRY.md), one command with `uv run` or any x402 client. **As an agent skill:** `npx skills add ShiftAboveCtrl/tollex` ([skills/tollex/SKILL.md](skills/tollex/SKILL.md)). **First real payment:** `GET https://api.tollex.org/v1/agent-check` (no body; the cheapest paid call). It returns which rail you paid on, every rail's live state and the chain heads, with a signed receipt. ## Inspect first (all free, no auth) | Step | Request | Use it for | | --- | --- | --- | | 1 | `GET https://api.tollex.org/.well-known/tollex.json` | network, asset, endpoints, receipt format | | 2 | `GET https://api.tollex.org/openapi.json` | every operation and input schema | | 3 | `GET https://api.tollex.org/v1/catalog` | capabilities, input schemas, current prices | | 4 | `POST https://api.tollex.org/v1/resolve` `{"need": "...", "input": {...}, "constraints": {"maxCost": ""}}` | which capability fits; never spends | | 5 | `POST https://api.tollex.org/v1/quote` `{"toolId": "...", "input": {...}}` | a priced quote for one call | | A2A | `GET https://api.tollex.org/.well-known/agent-card.json`, JSON-RPC at `https://api.tollex.org/a2a` | agent-to-agent; skills `tollex.resolve_intent`, `tollex.execute_intent`, `tollex.operation` | | Text | `GET https://api.tollex.org/llms.txt` | short summary for language models | ## Pay (real money: only with the operator's explicit permission and ceiling) 1. `POST https://api.tollex.org/tools/{toolId}` with the JSON input and **no** payment header. Expect `402` and a `PAYMENT-REQUIRED` header (base64 JSON, x402 v2). Those live terms are authoritative. 2. Choose the option whose `network` and `asset` match the rail you pinned (table above). Refuse if `amount` (atomic units, 6 decimals) is above your ceiling, or if no option matches. 3. Sign an EIP-3009 `TransferWithAuthorization` for exactly `amount` to `payTo`, with the EIP-712 domain `{name: extra.name, version: extra.version, chainId: <8453 for Base, 4663 for Robinhood Chain>, verifyingContract: asset}`, `validAfter = 0`, `validBefore = now + maxTimeoutSeconds`, a random 32-byte nonce. 4. Repeat the request with `PAYMENT-SIGNATURE: base64(JSON{x402Version: 2, accepted: