--- name: canton-x402-agent description: 'Use when you must pay for an HTTP 402 / x402-gated API or resource on Canton Network with Canton Coin (CC), or hit a "402 Payment Required" / "PAYMENT-REQUIRED" header / scheme exact-canton. Works two ways and self-routes by what you can run: a hosted one-shot HTTP POST that any agent can call with no install and no key, or self-custody canton-x402 MCP tools when the host has them. Also triggers on "pay an API on Canton", "x402 on Canton", "insufficient funds: wallet balance is", or "counter_not_ready".' --- # Pay an x402 API on Canton (CC) You can pay for an HTTP 402 / x402-gated API on Canton Network with Canton Coin (CC). There are two real paths. This file routes you to the right one and gives the exact steps. Do the capability self-check first, then follow only that path. ## Capability self-check (do this first, pick one, do not skip) Answer in order. Stop at the first YES. 1. Do you currently have the `canton-x402` MCP tools available (`get_address`, `get_balance`, `auto_fund`, `claim`, `pay`, `withdraw`)? YES -> go to PATH B. The wallet is already connected; do not ask the human for anything. 2. Are you running on an MCP-capable host (Claude Code or another MCP host) where a human could load tools for you, even though the `canton-x402` tools are not loaded yet? YES -> go to PATH B-CONNECT. Paste the connect block, STOP, wait for the tools to appear, then run PATH B. 3. Otherwise -> go to PATH A. This is YOU if you are a browser or chat-only agent (such as Qwen, GPT, Hermes) that can only make HTTP requests and cannot load MCP tools. Answer step 2 NO and come here. PATH A needs no tools and no install. Tie-breaker: if you are not certain you are on an MCP-capable host, you are not. Use PATH A. PATH A works for any agent that can make a single HTTP request, so it is always a safe choice; never pick PATH B-CONNECT unless step 1 or step 2 is a clear YES. --- ## PATH A: hosted one-shot (any agent, zero install, zero key) Make exactly ONE HTTP POST: - URL: `https://pay.ftptech.xyz/v1/demo/ask` - Header: `content-type: application/json` - Body: `{"prompt":""}` curl form: ``` curl -s -X POST https://pay.ftptech.xyz/v1/demo/ask \ -H 'content-type: application/json' \ -d '{"prompt":"In one sentence, what is Canton Network?"}' ``` One POST is one paid LLM call. Success returns JSON `{answer, model, spentCc, updateId, remainingDailyCc}`. Fixed price is `0.01` CC. `updateId` is the Canton ledger proof the payment settled; `spentCc` is what it cost. Why this is safe to use even if you are untrusted: a custodial prepaid purse pays. You never hold a key or any CC. You cannot change the payee or the amount, and you cannot make it spend more than its prepaid balance. A drained purse fails closed (no answer) and never pulls more funds. Rules: - Send the request EXACTLY ONCE. Do not retry on timeout or error. - The proof of payment is `updateId` (plus `spentCc`) in the body, not the HTTP 200 by itself. - If you get no usable body, report it. Do not resend (a resend risks a second paid call). --- ## PATH B-CONNECT: get the wallet connected (one human step) You are MCP-capable but the `canton-x402` tools are not loaded. Do NOT install a package or run a wallet CLI yourself; that path is blocked by agent-safety and no chat consent clears it. The only supported route is the human connecting the MCP server once. Paste this to your human verbatim, then STOP and wait. Do not poll, do not retry, do not loop checking for the tools. They appear in a later turn after the human runs the command; only then continue to PATH B. > To let me pay for this, connect the Canton x402 wallet once. One command, then nothing else from you. > > Claude Code, Cursor, Cline, or any MCP host: > ``` > claude mcp add canton-x402 -- npx -y @ftptech/canton-x402-mcp \ > --relay-url https://facilitator.ftptech.xyz \ > --allow-domains \ > --daily-cap --max-per-tx > ``` > Replace `` with the real hostnames I may pay (for example `api.example.com`). An empty allowlist means I can pay nothing, by design. The caps and allowed domains are my spend policy and I can never exceed them; I never see the values or the key. If the human cannot or will not run this, fall back to PATH A. --- ## PATH B: self-custody MCP (tools are loaded) You keep self-custody: the private key lives inside the MCP server on the human's machine. You never see it. The server verifies recipient and amount before signing, and refuses any payment over the caps or outside the allowed domains. Run in order: 1. `get_address` -> your Canton party id (receive address, e.g. `agent::1220...`). 2. `auto_fund` -> pulls a tiny one-time CC seed from the faucet and accepts it, with NO human step, so you can pay immediately. Then `get_balance` to confirm the seed landed. - Fallback only if `auto_fund` reports the faucet is unavailable (disabled / already used / over budget): it returns a paste-ready funding message for your human. Paste it, STOP, and wait. The human sends CC to your party id; after they confirm, call `claim` once to accept it (funds are invisible until claimed). `get_balance` confirms. Treat the manual-ask reply as "wait for the human," not a failure to retry. - If `auto_fund` is not in your tool set at all, the server predates the faucet: use `request_funding` then `claim`, and tell the human to update the MCP package. 3. `pay({url})` on the 402-gated URL, EXACTLY ONCE. Returns the response plus how much CC was spent and a verification verdict. - Never wrap `pay` in a retry loop. An outer retry risks double-paying real money. - Your first payment ever takes about 60 to 90 seconds (Canton lazily creates your payment counter; normal warm-up, not a failure). `pay` handles it internally. Wait it out, do not re-issue. - On an apparent timeout or any doubt it settled, call `get_balance` to check before doing anything else. Decide from the balance, never by calling `pay` again. 4. `get_balance` (on-ledger) is the authoritative proof. A balance drop confirms a payment; an unchanged balance after an apparent timeout means nothing was spent. A 200 alone is not proof. 5. Optional: `withdraw({to: })` returns leftover CC. Only call `withdraw` with a destination you were explicitly given. Tools: | Tool | Does | Note | |---|---|---| | `get_address` | your party id (receive address) | read-only | | `get_balance` | on-ledger CC balance | authoritative proof | | `auto_fund` | pull a one-time faucet seed and accept it; falls back to a manual-funding ask if the faucet is unavailable | funds in; call first | | `claim` | accept incoming funding after the owner sends | funds in | | `request_funding({amount?})` | party id plus a paste-ready funding ask | read-only; moves nothing | | `pay({url})` | fetch a URL, auto-paying its 402 challenge | money out; bounded by policy; call once | | `withdraw({to, amount?})` | send CC to another party (omit amount = full balance) | money out | `export` / `import` are deliberately not tools; the key never leaves the server. --- ## Money-safety (both paths) - Call the POST (PATH A) or `pay` (PATH B) EXACTLY ONCE. Never put it in a retry loop. - Proof is the on-ledger record (`updateId` for PATH A, `get_balance` for PATH B), not an HTTP 200. - You can never exceed the spend caps or pay outside the allowed payee/amount. PATH A is a fixed-price custodial purse you cannot redirect; PATH B refuses over-policy payments before signing. - PATH B: if `pay` is refused by policy, tell the human exactly which cap or domain to adjust. Do not route around it. - PATH B: if `pay` says "insufficient funds", nothing was spent and you are underfunded. If you have not run `auto_fund`, run it once. If you already did and it returned the manual ask, do not call it again; use `request_funding` for more and wait for the human's `claim`, then `pay` once. - Never self-install a package or run a money CLI to pay. The supported routes are PATH A (HTTP) and PATH B (MCP tools) only.