x402 Agent Integration

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:

POST /v2/interactive-submission/prepare → gets preparedTransactionHash
Agent signs the hash with its Ed25519 key (does not execute/submit)
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.

Get Started

Guides

Install

CLI Commands

Create a wallet

Address

Balance

Claim

Pay

Withdraw

Registry tokens (e.g. USDCx)

Export / Import

Environment Variables

SDK Usage

Wallet File

How Payment Works

First-Request Latency

​Install

​CLI Commands

​Create a wallet

​Address

​Balance

​Claim

​Pay

​Withdraw

​Registry tokens (e.g. USDCx)

​Export / Import

​Environment Variables

​SDK Usage

​Wallet File

​How Payment Works

​First-Request Latency

Install

CLI Commands

Create a wallet

Address

Balance

Claim

Pay

Withdraw

Registry tokens (e.g. USDCx)

Export / Import

Environment Variables

SDK Usage

Wallet File

How Payment Works

First-Request Latency