x402 Agent Integration

An agent is any client that pays x402-gated endpoints. On a 402, it signs a TransferFactory_Transfer, attaches it as proof, and retries automatically. The facilitator relays it and pays the traffic fee, so you never pay gas. See How Payments Work for the full flow.

Quickstart

npm i -g @ftptech/canton-agent-wallet@latest
export CANTON_AGENT_NETWORK=canton:mainnet          # CLI defaults to testnet
export CANTON_AGENT_RELAY_URL=https://facilitator.ftptech.xyz

canton-agent-wallet create                          # make a wallet + Canton party
# fund the printed party id with CC, then:
canton-agent-wallet claim                           # accept the incoming CC
canton-agent-wallet pay https://api.example.com/resource   # auto-pays the 402

CANTON_AGENT_NETWORK defaults to canton:testnet. Set it to canton:mainnet for mainnet, or a testnet wallet hitting the mainnet facilitator fails with a network mismatch.

CLI reference

All commands read the relay from CANTON_AGENT_RELAY_URL (or --relay-url).

Command	Does
`create`	Generate an Ed25519 key, allocate a Canton party, save to `~/.canton-agent/wallet.json`.
`address`	Print the party id (share it to receive CC).
`balance`	Show holdings (CC and any registry tokens).
`claim`	Accept incoming transfers (e.g. initial funding).
`pay <url>`	Fetch a URL, auto-paying any `402` challenge.
`withdraw --to <party> [--amount <cc>]`	Send CC out. `--amount` is decimal CC (`5.0` = 5 CC); omit it to send the full balance.
`export` / `import`	Back up / restore the wallet key (`export` prints the private key).

For POST bodies (e.g. LLM inference), use makePayingFetch from the SDK instead of pay.

SDK usage

import { makePayingFetch } from "@ftptech/canton-agent-wallet";

const payFetch = await makePayingFetch({
  relayUrl: "https://facilitator.ftptech.xyz",
  network:  "canton:mainnet",
});

// Drop-in fetch: a 402 is detected, paid, and retried automatically
const res = await payFetch("https://api.example.com/resource", {
  method:  "POST",
  headers: { "Content-Type": "application/json" },
  body:    JSON.stringify({ prompt: "hello" }),
});

Registry tokens (e.g. USDCx)

The wallet handles CIP-56 registry tokens alongside CC, with two safe-by-default opt-ins:

Receive: trust a token’s registrar with CANTON_AGENT_REGISTRY_TRUSTED_PARTIES (USDCx is built in). Untrusted registrars’ transfers are skipped by claim.
Spend: consent with CANTON_AGENT_PAYABLE_INSTRUMENTS="<registrar>::1220...|USDCx" (default: CC only), so a merchant cannot make you pay in a token you did not opt into.

# receive USDCx directly (self-provision your own registry preapproval), then claim it
canton-agent-wallet preapproval --admin <registrar>::1220... --id USDCx
canton-agent-wallet claim

# pay an endpoint priced in USDCx (opt in to spending first)
export CANTON_AGENT_PAYABLE_INSTRUMENTS="<registrar>::1220...|USDCx"
canton-agent-wallet pay https://api.example.com/resource

pay needs no --admin/--id - the instrument comes from the merchant’s 402; you only opt in to spending it.

Reference

Environment variables

Variable	Description
`CANTON_AGENT_RELAY_URL`	Facilitator URL (alternative to `--relay-url`).
`CANTON_AGENT_NETWORK`	Canton network (default `canton:testnet`).
`CANTON_AGENT_API_KEY`	API key, if the facilitator requires one.
`CANTON_AGENT_REGISTRY_TRUSTED_PARTIES`	Registrars trusted to verify/claim CIP-56 tokens (USDCx built in).
`CANTON_AGENT_PAYABLE_INSTRUMENTS`	Registry tokens you consent to spend (default: CC only).
`HTTPS_PROXY`	HTTP proxy for outbound requests.

Wallet file - ~/.canton-agent/wallet.json, mode 0600, holds the Ed25519 key and party id. Back it up; losing it loses the funds it holds. First-request latency - the first payment after a cold start warms the SV Scan caches (AmuletRules 5 min TTL, OpenMiningRound 30 s TTL); subsequent payments typically complete in 10 to 25 seconds on mainnet.

Get Started

Guides

Legal

Quickstart

CLI reference

SDK usage

Registry tokens (e.g. USDCx)

Reference

​Quickstart

​CLI reference

​SDK usage

​Registry tokens (e.g. USDCx)

​Reference

Quickstart

CLI reference

SDK usage

Registry tokens (e.g. USDCx)

Reference