> ## Documentation Index
> Fetch the complete documentation index at: https://x402-docs.ftptech.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# x402 Agent Integration

> Pay x402-gated endpoints in Canton Coin or a CIP-56 token from an agent or backend, via the canton-agent-wallet CLI and SDK.

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](/x402-payments) for the full flow.

## Quickstart

```bash theme={null}
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
```

<Warning>
  `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.
</Warning>

## 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

```typescript theme={null}
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.

```bash theme={null}
# 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.