x402 Agent Integration

Make automated Canton Coin or CIP-56 token payments from an agent or backend service using the canton-agent-wallet CLI and SDK.

An agent (or payer) is any client that calls x402-gated endpoints. When the server returns 402 Payment Required, the agent signs a TransferFactory_Transfer (naming the merchant as receiver) but does not submit it — it attaches the payer-signed transfer as the payment proof and retries automatically. The facilitator relays that signed transfer and pays the network traffic fee; because the merchant holds a standing TransferPreapproval, it settles directly to the merchant in a single transaction.

Install

npm i -g @ftptech/canton-agent-wallet@latest

These examples target mainnet via the facilitator.ftptech.xyz relay. The CLI defaults to canton:testnet, so select mainnet first, otherwise a testnet wallet hits the mainnet facilitator and payments fail with a network mismatch:

export CANTON_AGENT_NETWORK=canton:mainnet

CLI Commands

Create a wallet

Generates an Ed25519 key pair, allocates a Canton party, and saves the wallet to ~/.canton-agent/wallet.json.

canton-agent-wallet create --relay-url https://facilitator.ftptech.xyz
# wallet ready (canton:mainnet)
#   party:   my-agent::1220...
#   fund me: send CC to that party id, then run: canton-agent-wallet claim
#   keyfile: ~/.canton-agent/wallet.json  <- back it up

Address

Print the party ID. Use this to receive CC from a wallet or another agent.

canton-agent-wallet address
# my-agent::1220...

Balance

canton-agent-wallet balance --relay-url https://facilitator.ftptech.xyz
# <amount> CC  (<n> holdings)

Claim

Accept incoming CC transfers (e.g. the initial funding from a wallet):

canton-agent-wallet claim --relay-url https://facilitator.ftptech.xyz
# claimed 1 incoming transfer(s)

Pay

Fetch a URL, automatically paying any x402 402 challenge:

canton-agent-wallet pay --relay-url https://facilitator.ftptech.xyz https://api.example.com/resource

For POST endpoints (e.g. LLM inference with a request body), use makePayingFetch from the SDK instead.

Withdraw

Send CC to any Canton party:

# Partial amount
canton-agent-wallet withdraw --relay-url https://facilitator.ftptech.xyz --to "recipient::1220..." --amount 5.0000000000

# Full balance
canton-agent-wallet withdraw --relay-url https://facilitator.ftptech.xyz --to "recipient::1220..."

--amount is in CC (decimal), so 5.0 = 5 CC. This differs from PaymentRequirements.amount in the 402 challenge, which is in atomic units (10^10 per CC).

Registry tokens (e.g. USDCx)

The wallet handles CIP-56 registry tokens (like USDCx) alongside Canton Coin. Two independent opt-ins keep them safe by default:

• Trust a token’s registrar to verify and receive it — set CANTON_AGENT_REGISTRY_TRUSTED_PARTIES (USDCx’s registrar is trusted out of the box). An untrusted registrar’s incoming transfers are skipped by claim.
• Consent to spend a token — set CANTON_AGENT_PAYABLE_INSTRUMENTS="<registrar>|USDCx". The default is Canton Coin only, so a merchant cannot make you pay in a token you did not opt into.

# See every instrument held (CC + registry tokens)
canton-agent-wallet balance

# Receive USDCx one-shot (direct): self-provision your own registry preapproval
canton-agent-wallet preapproval --admin <registrar>::1220... --id USDCx

# Accept a pending incoming USDCx transfer (registrar must be trusted)
canton-agent-wallet claim

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

# Withdraw a registry token instead of CC
canton-agent-wallet withdraw --to "recipient::1220..." --amount 1.0 --admin <registrar>::1220... --id USDCx

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

Export / Import

Back up and restore the wallet key:

# Export (prints private key; store securely)
canton-agent-wallet export > my-agent.pem

# Restore on a new machine
canton-agent-wallet import --relay-url https://facilitator.ftptech.xyz --key-file my-agent.pem

Environment Variables

Variable	Description
CANTON_AGENT_RELAY_URL	Facilitator URL (alternative to --relay-url on every command)
CANTON_AGENT_NETWORK	Canton network (default: canton:testnet; set to canton:mainnet for mainnet)
CANTON_AGENT_API_KEY	API key if the facilitator requires one
CANTON_AGENT_REGISTRY_TRUSTED_PARTIES	Registrars to trust for verifying/claiming CIP-56 tokens (USDCx is built in)
CANTON_AGENT_PAYABLE_INSTRUMENTS	Registry tokens you consent to spend, e.g. "<registrar>|USDCx" (default: Canton Coin only)
HTTPS_PROXY	HTTP proxy for outbound requests

CANTON_AGENT_NETWORK defaults to canton:testnet. Always set it to canton:mainnet when connecting to mainnet.

SDK Usage

For programmatic use (e.g. embedding payments in a backend service):

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

// Creates or loads wallet, resolves Canton party
const payFetch = await makePayingFetch({
  relayUrl: "https://facilitator.ftptech.xyz",
  network:  "canton:mainnet",
});

// Drop-in fetch replacement; 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" }),
});
const data = await res.json();

Wallet File

The wallet is stored at ~/.canton-agent/wallet.json with permissions 0600. It contains the Ed25519 private key and the allocated Canton party ID. Back it up; losing the file loses access to the funds it holds.

How Payment Works

Payment settles in a single transaction. When the agent pays an x402-gated URL it signs — but does not submit — a TransferFactory_Transfer (CIP-56 Token Standard transfer instruction) naming the merchant as receiver:

1. POST /v2/interactive-submission/prepare → gets preparedTransactionHash
2. Agent signs the hash with its Ed25519 key (does not execute/submit)
3. Retries the original request with PAYMENT-SIGNATURE: <base64 PaymentPayload> carrying the payer-signed transfer inline (the prepared transaction plus the signature)

The merchant’s server then calls the facilitator’s /verify and /settle. The facilitator relays the payer-signed transfer — it submits the transaction and pays the sequencer traffic fee. Because the merchant holds a live TransferPreapproval, the transfer resolves directly and moves CC from the payer’s own holdings to the merchant in one transaction. The agent never pays gas; the facilitator never holds custody and signs nothing on the payer’s behalf.

First-Request Latency

The first payment after a cold start is slower than subsequent ones. SV Scan caches AmuletRules (5 min TTL) and OpenMiningRound (30 s TTL); these caches are empty on startup, so the first request warms them. Subsequent payments typically complete in 10 to 25 seconds on Canton mainnet.