> ## Documentation Index
> Fetch the complete documentation index at: https://a-identity.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Integrate on Arc Mainnet in 10 minutes

> Buy an A-Identity trust check through Circle Gateway nanopayments before your agent pays on Arc Mainnet: the 402, the payment, the verdict, where your payments show up, and verifyThenPay from a vault.

Your agent pays for APIs or services on Arc Mainnet. Before each payment it buys one
trust check from A-Identity, paid in USDC through Circle Gateway nanopayments (the buyer
signs, nobody pays gas, Circle batches the settlement), and acts on the answer. This page
is the whole integration. Every endpoint, header, price and address on it was read from
the running service and from Circle's own endpoints on 2026-11-04, except our `payTo`, which
moved at 18:35 UTC on 2026-11-11 to the address in the challenge below, and the
[verifyThenPay section](#verify-then-pay-from-a-vault), which is dated on its own. The ten
minutes start once your wallet holds USDC on Arc Mainnet; [getting it there](#what-you-need)
is the slow part for most teams.

**Your team pays for every check from its own wallet and its own Gateway balance. We do not
fund your checks and we never hold your key. Every check you pay shows on
[/proof/arc](https://a-identity.xyz/proof/arc) as external.** That is what Milestone 2 of the
Arc Acceleration Season asks of an outside team: buy a check before you pay on Arc Mainnet.
[`verifyThenPay`](#verify-then-pay-from-a-vault) is the next step, and its hosted route and MCP
tools are live today, and its SDK is on npm.

## What you get

* **A verdict before the payment.** `risk_check` returns `decision` (`ALLOW`, `WARN` or
  `DENY`), a `risk` band and `reasons` as plain sentences, for the payee and the amount
  you pass. 0.005 USDC per call. `counterparty_check` (0.008 USDC) does the same for the
  pair payer plus payee and also detects same-operator self-dealing.
* **The cheapest check.** `verify_agent` at 0.001 USDC answers whether the payee holds an
  ERC-8004 identity, its KYA status and whether its endpoint is live. It is identity, not
  a verdict: the verdict tools start at 0.005 USDC.
* **What a check reads.** The ERC-8004 registry, live on-chain (owner and registration
  URI), the KYA wallet-control attestation, a deterministic 0 to 1000 reputation computed
  from settled payments, validation and tenure with a Sybil check, whether the agent is
  revoked, and the `txContext.amountUsd` you pass, because a payee that is fine for one
  dollar may not be fine for ten thousand. Nothing in a verdict is a language-model guess.

The free preview is coarse on purpose: `GET /api/x402/gateway/tools/trust_preview?agentId=...`
returns a band and flags, no verdict and no reasons, and is rate limited.

## What you need

**1. An Arc Mainnet wallet holding USDC**

Arc Mainnet is `eip155:5042` (chain id 5042), RPC `https://rpc.mainnet.arc.io`, no
API key. Gas on Arc is USDC itself, so keep a little USDC beyond what you deposit.
The payer address is the one that will appear on our proof page, so use a wallet
you are happy to be attributed by. With the SDK or the reference script that is your
key's own address. With a Circle CLI agent wallet it is the wallet's backing EOA, not the
`--address` you pass, so that is the address to send us.

**Getting USDC onto Arc Mainnet.** We do not supply it, and this is usually the first
thing that stops a team. What we know, read on 2026-11-04:

* The route is Circle's Cross-Chain Transfer Protocol (CCTP), which
  [Arc names as its canonical bridge](https://docs.arc.io/integrate/infrastructure/bridges):
  USDC is burned on the source chain and minted natively on Arc, CCTP domain `26`.
* [Arc's Get USDC section](https://docs.arc.io/arc-chain#get-usdc) lists the USDC Bridge
  app at `bridge.usdc.com`, Bridge Kit for doing it from code, and
  [USDC providers](https://www.usdc.com/providers) for buying USDC. Our proof log holds no
  transfer through that app and no purchase from a provider, so we cannot tell you their
  fees or timing.
* What we have done ourselves is a CCTP V2 burn on Base that Circle's Forwarding Service
  minted on Arc Mainnet; the receipts are on [/proof/arc](https://a-identity.xyz/proof/arc).
  A plain CCTP transfer ends with a `receiveMessage` call on Arc, and a wallet with no USDC
  on Arc cannot pay the gas for it. The
  [Forwarding Service](https://docs.arc.io/app-kit/tutorials/bridge/use-forwarding-service)
  submits that mint for you and takes its fee from the transfer.

> [!WARNING]
>
> Fake bridge sites are a common way to lose a wallet. Open a bridge only from the link on
> [Arc's docs](https://docs.arc.io/arc-chain#get-usdc), never from a search ad or a message,
> and that includes a message that claims to come from us. Read what your wallet asks you to
> sign, and send a small amount first. No bridge, and nobody from A-Identity, needs your seed
> phrase or private key. USDC on Arc Mainnet is only the contract in the table below: Arc has
> no wrapped USDC, so a token offered as wrapped USDC on Arc is not it.

Bring a little more than you plan to deposit. The code below deposits 1 USDC, which is 200
`risk_check` calls, and the Circle CLI refuses a Gateway deposit under 0.5 USDC.

**2. USDC in a Circle Gateway balance on Arc Mainnet**

A nanopayment spends a Gateway balance, not your wallet balance. The deposit is one
on-chain transaction pair: `approve` the GatewayWallet on the USDC contract, then call
`deposit(token, value)` on the GatewayWallet. Circle credits it after about one block
(its supported-blockchains table lists Arc at about 0.5 seconds). 1 USDC covers 1000
`verify_agent` calls or 200 `risk_check` calls.

| Item | Value |
| - | - |
| USDC on Arc Mainnet (ERC-20 interface, 6 decimals) | `0x3600000000000000000000000000000000000000` |
| Circle GatewayWallet on Arc Mainnet | `0x77777777Dcc4d5A8B6E418Fd04D8997ef11000eE` |
| Gateway domain for Arc | `26` |
| Gateway API | `https://gateway-api.circle.com` |

> [!WARNING]
>
> The Arc **testnet** GatewayWallet is a different contract
> (`0x0077777d7EBA4688BDeF3E311b846F25870A19B9`); use the mainnet address above. And
> never send USDC to the GatewayWallet with a plain ERC-20 transfer: Circle's docs say
> it is not credited and is lost. Only `deposit()` creates a balance.

Check the balance, no key needed:

```bash theme={null}
curl -s -X POST https://gateway-api.circle.com/v1/balances \
  -H 'content-type: application/json' \
  -d '{"token":"USDC","sources":[{"domain":26,"depositor":"0xYourWallet"}]}'
# {"token":"USDC","balances":[{"domain":26,"depositor":"0x...","balance":"1.000000","pendingBatch":"0"}]}
```

**3. A client that can answer a 402**

Two easy ways, and one readable reference:

* **`@circle-fin/x402-batching`**, the one to use if your team already holds a key:
  `GatewayClient` deposits and pays from Node.js or TypeScript. For Arc Mainnet its chain
  name is `arc`. Version 4.0.0, which a fresh install gets today, defaults to the public RPC
  above. Version 3.x, which our own server still depends on, throws without an `rpcUrl`, and
  passing one works on both.
* **Circle CLI** (`npm install -g @circle-fin/cli`): `circle gateway deposit` and
  `circle services pay` do the deposit and the payment from the command line, from a Circle
  agent wallet. `circle wallet login` registers a Circle user the first time and creates
  that wallet. The CLI asks you to accept Circle's terms on first run; in a script or an
  agent's shell it stops there until you set `CIRCLE_ACCEPT_TERMS=1`, which accepts them.
* **Our reference buyer**, the buyer script we run ourselves:
  [`mcp/scripts/x402-gateway-buyer.mjs`](https://github.com/getA-Identity/A-Identity/blob/main/mcp/scripts/x402-gateway-buyer.mjs)
  reads the 402, re-proves the signing domain against Gateway's own `/v1/x402/supported`,
  signs with the SDK's `BatchEvmScheme` and pays;
  [`mcp/scripts/gateway-deposit.mjs`](https://github.com/getA-Identity/A-Identity/blob/main/mcp/scripts/gateway-deposit.mjs)
  is the deposit. Both print the exact calls and exit when no key is set.

## The 10-minute flow

**1. Call the tool and read the 402**

Every paid tool answers `GET` (query parameters) and `POST` (JSON body). Unpaid, both
answer `402` with the requirements in the body and, base64-encoded, in the
`PAYMENT-REQUIRED` header; the two are identical. This is the live challenge:

```bash theme={null}
curl -s -D - 'https://a-identity.xyz/api/x402/gateway/tools/risk_check?agentId=0x4e26Ae66840134Ac5979c56ba2509F3956b93431&amountUsd=25'
```

Trimmed response. The second `accepts` entry (Base `eip155:8453`), the descriptions, the
other assets in `extra.assets` and some extra fields in `accepts` and `tool` are cut; the call
above returns all of it:

```json theme={null}
{
  "x402Version": 2,
  "error": "payment required",
  "resource": { "url": "https://a-identity.xyz/api/x402/gateway/tools/risk_check", "mimeType": "application/json" },
  "accepts": [
    {
      "scheme": "exact",
      "network": "eip155:5042",
      "asset": "0x3600000000000000000000000000000000000000",
      "amount": "5000",
      "payTo": "0xcb8824ffaf30687e36374c08ec52298b62871bdf",
      "maxTimeoutSeconds": 3600,
      "resource": "https://a-identity.xyz/api/x402/gateway/tools/risk_check",
      "extra": {
        "name": "GatewayWalletBatched",
        "version": "1",
        "verifyingContract": "0x77777777dcc4d5a8b6e418fd04d8997ef11000ee",
        "minValiditySeconds": 604800,
        "assets": [{ "symbol": "USDC", "address": "0x3600000000000000000000000000000000000000", "decimals": 6 }],
        "registryWallet": "0x77777777Dcc4d5A8B6E418Fd04D8997ef11000eE",
        "domainVerified": true,
        "provenAt": "2026-10-19T18:21:33.580Z"
      }
    }
  ],
  "tool": {
    "name": "risk_check",
    "price": { "totalUsd": 0.005, "settlementFeeUsd": 0 },
    "required": ["agentId"],
    "example": { "agentId": "#73232", "txContext": { "amountUsd": 25 } }
  }
}
```

`amount` is in USDC base units (6 decimals): `5000` is 0.005 USDC. `settlementFeeUsd`
is 0 on this rail; the price is the whole cost. `domainVerified` and `provenAt` say that
before this challenge was served we read Gateway's live `/v1/x402/supported` and found
the same `verifyingContract` and the same USDC the registry expects. Pick the
`eip155:5042` entry.

**2. Pay**

Sign an EIP-3009 authorization against the `GatewayWalletBatched` domain (name
`GatewayWalletBatched`, version `1`, chainId `5042`, verifyingContract
`0x77777777Dcc4d5A8B6E418Fd04D8997ef11000eE`) for exactly `amount`, to `payTo`, and
retry the same request with the signed payload. Any of the three clients does this
for you. With a key your team already holds, use the `@circle-fin/x402-batching` tab:
the Circle CLI pays only from a wallet you log in to with `circle wallet login`, and a
key added with `circle wallet import` cannot run `circle services pay`.

From an empty folder, on Node 24, the SDK path is:

```bash theme={null}
npm init -y && npm pkg set type=module
npm install @circle-fin/x402-batching
# save the first tab below as check.ts, then, with a key that holds USDC on Arc Mainnet:
BUYER_KEY=0x... node check.ts
```

```ts @circle-fin/x402-batching theme={null}
import { GatewayClient } from '@circle-fin/x402-batching/client'

const gateway = new GatewayClient({
  chain: 'arc',                                 // Arc Mainnet, Gateway domain 26
  privateKey: process.env.BUYER_KEY as `0x${string}`,
  rpcUrl: 'https://rpc.mainnet.arc.io',         // optional on 4.x, required on 3.x
})
await gateway.deposit('1')                      // once, then remove: approve + deposit on the GatewayWallet

const { data } = await gateway.pay('https://a-identity.xyz/api/x402/gateway/tools/risk_check', {
  method: 'POST',
  body: { agentId: '0x4e26Ae66840134Ac5979c56ba2509F3956b93431', txContext: { amountUsd: 25 } },
})
console.log('payer', gateway.address, data)     // send us this payer address
```

```bash Circle CLI theme={null}
npm install -g @circle-fin/cli
circle wallet login you@yourteam.com        # a Circle wallet login; an imported key cannot run services pay
circle gateway deposit --amount 1 --address 0xYourWallet --chain ARC --method direct
circle gateway balance --address 0xYourWallet --chain ARC
circle services pay https://a-identity.xyz/api/x402/gateway/tools/risk_check \
  --address 0xYourWallet --chain ARC --max-amount 0.005 \
  -X POST -d '{"agentId":"0x4e26Ae66840134Ac5979c56ba2509F3956b93431","txContext":{"amountUsd":25}}'
```

```bash Reference script theme={null}
git clone https://github.com/getA-Identity/A-Identity && cd A-Identity/mcp && npm install && npm run build
# X402_GATEWAY_BUYER_KEY=0x... in mcp/.env
node --env-file=.env scripts/gateway-deposit.mjs --chain arc-mainnet --amount 1 --key-env X402_GATEWAY_BUYER_KEY
node --env-file=.env scripts/x402-gateway-buyer.mjs \
  --url https://a-identity.xyz/api/x402/gateway/tools/risk_check \
  --agent 0x4e26Ae66840134Ac5979c56ba2509F3956b93431 --network eip155:5042 --dry-run   # drop --dry-run to pay
```

The script sends `agentId` only; pass `txContext` through the CLI or the SDK. If you
write your own client, the retry carries one header, `PAYMENT-SIGNATURE`, whose value
is base64 of this JSON (the older `X-PAYMENT` name is accepted too):

```json theme={null}
{
  "x402Version": 2,
  "accepted": "the accepts entry you chose, unchanged",
  "payload": {
    "signature": "0x...",
    "authorization": {
      "from": "0xYourWallet",
      "to": "0xcb8824ffaf30687e36374c08ec52298b62871bdf",
      "value": "5000",
      "validAfter": "<unix seconds>",
      "validBefore": "<unix seconds>",
      "nonce": "0x<32 random bytes>"
    }
  }
}
```

`value` must be exactly the price and `to` exactly our `payTo`; anything else is
refused with a fresh 402 and nothing is settled.

**3. Read the verdict**

A paid call answers `200` with the tool result plus a `settlement` record, and a
`PAYMENT-RESPONSE` header (base64 JSON: `success`, `transaction`, `network`, `payer`,
`amount`). The shape, with illustrative values for the verdict fields:

```json theme={null}
{
  "tool": "risk_check",
  "agentId": "0x4e26Ae66840134Ac5979c56ba2509F3956b93431",
  "decision": "WARN",
  "risk": "medium",
  "reasons": ["Moderate reputation (470): not enough for us to vouch for it"],
  "signals": { "...": "the inputs the verdict was computed from" },
  "checkedAt": "2026-11-01T18:30:00.000Z",
  "_meta": { "network": "Arc Mainnet (eip155:5042)", "proof": "/api/x402/gateway/proof" },
  "settlement": {
    "ts": "2026-09-24T16:43:58.731Z",
    "outcome": "completed",
    "tool": "verify_agent",
    "network": "eip155:5042",
    "assetSymbol": "USDC",
    "value": "1000",
    "amountUsd": 0.001,
    "payer": "0x8c8d9cd12d8896a40cf2115ee731258bb4983349",
    "payTo": "0xd305607510e0db2c95807173c7a05bea53c1ed36",
    "authNonce": "0xd232cc9d...a709d8481",
    "transferId": "e06f2175-132f-4f5f-af3f-04ed42b9a028",
    "gatewayStatus": "completed",
    "confirmedBy": "gateway-transfers-api",
    "tx": "0x1338762a8203452d75dfeea76a33fa296c299c6e9fc297bec9112bbe801e0413",
    "explorerUrl": "https://explorer.arc.io/tx/0x1338762a8203452d75dfeea76a33fa296c299c6e9fc297bec9112bbe801e0413"
  }
}
```

`decision` is `ALLOW`, `WARN` or `DENY`. On `DENY`, do not make the payment. `WARN` is not
a go-ahead: hold the payment for a person, which is what `verifyThenPay` does by itself. The
`settlement` block above is a real row from the proof log (a `verify_agent` call our own
wallet paid on 2026-09-24, labeled internal there, to `0xd305...ed36`, the former operating
wallet, which A-Identity retired on 2026-11-11 because someone else holds its key; since
2026-11-11 `payTo` is the address in the challenge above); yours carries your payer and your
tool. A fresh call comes back as `credited` with no `tx` until Gateway's on-chain batch
lands, and the proof page upgrades the row to `completed` with the batch hash when it does.

| Status | Meaning |
| - | - |
| `400` | A required input is missing. Checked before any payment is taken. |
| `402` | No header, a malformed header, `to` not our `payTo`, `value` not exactly the price, or Gateway refused. The body is the challenge again plus `verifyError`. |
| `503` | Gateway's kind for Arc could not be proven against the registry right now. No challenge is served rather than one nobody could settle. |
| `502` | Gateway answered success but its transfers API returned no matching transfer inside the window, or the settle call itself got no usable answer. Whether money moved is not known, so no challenge is served: do not sign again before looking the nonce up. Nothing served, nothing counted; the row is recorded as `unconfirmed` on the proof so it can be resolved. |
| `500` | Credited and recorded, but the tool failed on our side. The body names the transfer. |

## The tools

Six paid tools and one free preview, at `https://a-identity.xyz/api/x402/gateway/tools/<name>`.
`agentId`, `from` and `to` each accept a platform agent id, an ERC-8004 token id (`#73232`), a
CAIP id (`eip155:<chain>:8004/<token>`) or a 0x address; the next paragraph says what each form
gets you. `txContext` is optional and takes
`{ "amountUsd": number, "payee": "0x address" }`; on `GET`, pass it as a JSON string or use
`amountUsd=25` as a shortcut. Prices are the ones the 402 charges; the OpenAPI document at
[/api/x402/gateway/openapi.json](https://a-identity.xyz/api/x402/gateway/openapi.json) is
generated from the same source.

**Send the payee's 0x address as `agentId`.** It needs no chain read. `risk_check` also takes a
platform id, a token id, a CAIP token id and a CAIP-10 account, and they reach the same record: a token
answers on the chain it names, or through the record that proved the address holding it. A token we
hold no record of gets `WARN`. An id that reaches no record and no identity was never looked up, so it
stays strict: `DENY`, with reasons that say we could not look and hold no evidence, and to ask again
with the 0x address.

**Who gets what.** `DENY` means we hold evidence against the payee: KYA revoked, Sybil high, or, on an
agent on our platform whose record holds rejected settlements or guardrail override attempts, a
reputation under 200 or a payment over 100 USD with reputation under 400. It also comes out when we could
not read our record and stayed strict, and the reasons say which. A contested job lowers the score and is
named in the reasons, and it is not evidence by itself: it costs the client nothing while we fund the
escrow, so counting it would let a stranger write a `DENY` on a vendor. A low score alone
is not evidence: an agent on our platform with nothing against it gets `WARN` at those lines, with
reasons that say our record holds nothing against it and not enough to vouch for it, and the amount
named when it is over 100 USD. A payee with no on-chain identity, or with an identity and no record on
our platform, is not known bad, so it gets `WARN`, with reasons that say what we do not know.
A high-value or large payment to such a payee stays `WARN`, with the amount named. `ALLOW` needs
a platform agent with reputation of at least 500, attested KYA and at least 7 days of tenure.
A real seller who simply has not registered with us scores at most 60 because we have no history
for it, and that gets `WARN`, and signing up with us does not make that worse. Until 2026-11-04 it got `DENY`; anything dated before that day on
this page or on [/proof/arc](https://a-identity.xyz/proof/arc) was answered under the older rule.

**What that line cannot see.** `DENY` binds an address we hold a proven record of. A record counts
at an address only once it proved control of it, so a registration that merely names a wallet does
not count. A payee with a bad record can appear under a new address and get `WARN`, so `WARN` means
unknown, not clean. Read the reasons before you pay on one.

| Tool | Price | What it answers | Required input |
| - | - | - | - |
| `verify_agent` | 0.001 USDC | ERC-8004 identity, KYA status, endpoint liveness | `agentId` |
| `reputation_score` | 0.002 USDC | Deterministic 0 to 1000 reputation with a full breakdown and its on-chain attestation | `agentId` |
| `risk_check` | 0.005 USDC | Pre-transaction ALLOW / WARN / DENY verdict on a counterparty, with reasons | `agentId` (`txContext` optional) |
| `guardrail_check` | 0.005 USDC | Whether the agent operates under an enforced spend or trade policy and respects verdicts; bands only, no caps, allowlists, symbols, amounts or holdings disclosed | `agentId` |
| `counterparty_check` | 0.008 USDC | Deal-specific verdict between two agents: counterparty risk plus same-operator self-deal detection | `from`, `to` (`txContext` optional) |
| `agent_passport` | 0.01 USDC | The full passport: identity, KYA, reputation and risk in one call | `agentId` |
| `trust_preview` | free, rate limited | Coarse trust band, flags and the price list; `GET` only | `agentId` |

The same tools, at the same prices, are sold on Base (`eip155:8453`) through the same
rail; the 402 lists both and you pick by `network`.

## Where your payments show up

Your wallet pays, from its own Gateway balance, and it is labeled **external** automatically:
our own buyer wallets are on the rail's published internal list, and every other payer is external.
The Arc season report below also reads as internal the owner of a vault labeled team, and the agent key
on a recorded flow through such a vault: a person on our team is not a wallet we do not control. An
agent key with no recorded flow through that vault stays external until it is on the list, and the
rail's own proof reads the list alone. Nothing is counted until the
transfer has been read back from Gateway's transfers API for the authorization's nonce,
to our `payTo`, for the price.

* [a-identity.xyz/proof/arc](https://a-identity.xyz/proof/arc) shows the totals for Arc
  Mainnet and the newest eight settled checks, each with the tool, the amount, "via Circle
  Gateway" and the batch transaction once it lands. Rows paid by our wallets carry an
  "internal" tag; yours carry none. The counter reads "Circle Gateway internal / external
  (all networks)".
* [/api/x402/gateway/proof](https://a-identity.xyz/api/x402/gateway/proof) is the JSON
  behind it: `internalSettlements`, `externalSettlements`, the `internalPayers` list and
  the last 50 rows with their `payer`.
* `GET https://a-identity.xyz/api/arc/season` is the Arc Acceleration Season report,
  computed from the same logs on every request: `usage.internal` and `usage.external`,
  external usage per wallet (`checks`, `usd`, first and last payment, `activeDays`), and
  the Milestone 2 counts against their targets (external teams live, 30 external checks,
  a team active on more than one day, a publicly referenceable integration). Each owner-held
  vault under `milestone1.vaults.items` lists the freezes and withdrawals its owner's wallet
  signed, with hashes, and `actionsRead` says how far the chain was read.
  `milestone1.vaults.owners` and `milestone2.externalChecks.payers` say how many owner and
  paying wallets stand behind those counts and how many of them are linked on chain, so a
  wallet is not read as a separate user; `linkedWallets` is the hand trace behind them, with
  its transactions and how far it goes.
* `POST https://a-identity.xyz/api/arc/vaults` with `{"deployTx": "0x..."}` admits an
  owner-held vault on Arc Mainnet by its deploy transaction, or refuses with the reasons. It
  signs nothing, needs no session, and the same hash twice is a no-op. The vault page at
  `/app/vault/arc` does this for you. `GET` on the same path lists the admitted vaults. The server
  also looks on the chain by itself for vaults whose agent key has an end date, and puts each one
  through the same checks, so a vault deployed from any browser can be counted without this post.

Send your payer address and your team name to
[hello@a-identity.xyz](mailto:hello@a-identity.xyz) so the usage is attributed to you by
name, and say whether we may reference the integration in public. That attribution is a
list we keep by hand, and a team is added only after its wallet has paid a check; the
external label itself needs nothing from you.

## Verify, then pay from a vault

`verifyThenPay` puts the check and the payment in one flow on Arc Mainnet. An
[AgentSpendPolicy](https://a-identity.mintlify.site/chains/arc.md) vault pays, its limits hold on chain, and the check is bought
first, for 0.005 USDC, from a Gateway balance. Checked on 2026-11-04:

| Path | Status |
| - | - |
| Hosted routes | **Live.** They validate input and serve flow records. 100 flows have run on Arc Mainnet, all through the launch-day vault A-Identity deployed (retired on 2026-11-11, not ours any more), to payees that were ours when the flows ran, and labeled so: 75 `ALLOW` flows that the vault paid to our own agents, and 25 `DENY` flows stopped before signing, answered on 2026-11-01 and 2026-11-02 UTC under the rule of that day, which named the operating wallet of the time, an address A-Identity has since retired because someone else holds its key. Each is listed on [/proof/arc](https://a-identity.xyz/proof/arc). |
| MCP tools | **Live** on `https://a-identity.xyz/mcp`, which lists both. The stdio server does not carry them. |
| SDK, `@a-identity/trust-guard` 0.4.0 | **On npm**, with the `/arc` entry point. An earlier build of this code ran our own 100 flows, on its `pay()` path. No outside team has run the published package yet. `ownerOnly`, `approvalUrl` and the hand-off of a payment above the ceiling or off the allowlist come with 0.5.0, which is in the repo and not on npm yet; the hosted route already answers with all of them. |

> [!NOTE]
>
> A vault payment is a direct USDC transfer to the checked payee, not an x402 settlement. The vault
> cannot settle an x402 offer: its agent payment path is `pay(to, amount)`, sent plainly, with no
> Memo. So a payment names no check; the server links them by vault, payee, amount and block order.

**Whose keys.** A vault you deploy at [/app/vault/arc](https://a-identity.xyz/app/vault/arc) is
yours: your wallet is the owner, your own agent is the operator, and A-Identity holds neither key.
The check's payer defaults to the operator and can be a separate key. Our own flows ran
through the launch-day vault we deployed, `0xe07819e6d28a5dfd5a9f4cd94dc6dc9aeeda4146`, whose
owner is the former operating wallet and whose operator was our env-gated key, so they are not
owner-held and are labeled internal. That vault is retired and not ours: A-Identity retired its
owner on 2026-11-11 because someone else holds that key (since at least 2026-11-01), and the
contract has no owner transfer, so the founder emptied it at about 00:38 UTC on 2026-11-11
(withdraw tx `0xaa4714de40e7b0f47736b13df013e770fa52e569f3b5fc3568559194282913d1`). Do not fund it.

**Five things the contract does that an owner should know.** Each is pinned by a test in
`mcp/test-sol/AgentSpendPolicy.olx.t.sol`. The vault page says them where you act on them, but a call
from an explorer or a script reaches the contract with none of the page's checks.

* **The daily cap is a calendar day, so up to twice it can go around 00:00 UTC.** The day resets at
  00:00 UTC, and the agent key can spend a full cap in the last second of one day and another in the
  first second of the next. With a cap that does not change, `pay` moves at most 2x the cap between
  any two moments up to 24 hours apart; one second more can touch a third day and reach 3x. Set the cap
  to half the most you would accept losing quickly. Lowering the cap does not undo what was already
  spent today, and the new cap applies again after 00:00 UTC, so to stop an agent now, freeze the
  vault. The cap binds `pay` only: `ownerPay` and `withdraw` are the owner's and are not capped by it.
* **An owner payment counts toward the agent's day.** `ownerPay` adds to the same day counter that
  `pay` checks, with no cap check of its own, so it can stop the agent until 00:00 UTC. The owner can
  lift that by raising the cap, and the higher cap then stays until the owner lowers it. `withdraw`
  does not count, so the counter records `Paid` events, not all money leaving the vault. The counter
  limits the agent only when the owner paid first: an agent that goes first can spend its whole cap,
  and the owner can still pay on top.
* **`setPolicy` writes both limits and the allowlist setting in one call.** There is no way to change
  only the caps, and the contract writes whatever flag it is sent, so a caps change that sends `false`
  turns the allowlist off. The list itself survives, so turning the flag on again restores it. The
  vault page follows the latest read and re-reads the chain before it signs, and says so when the
  allowlist is about to go off. A script has to read the flag first.
* **0 means no limit, not no spending.** A `dailyCap` or `autoApproveMax` of 0 removes that gate, and a
  `sessionKeyExpiry` of 0 means no time limit, even for a key that had expired. Each 0 removes only its
  own gate. The vault page and our backend refuse a 0, and one that rounds to 0, but the contract
  accepts it. To stop an agent, call `setFrozen(true)`, replace the key, or set an end date already
  past, such as 1.
* **The end date belongs to the vault, not to one key.** `sessionKeyExpiry` is one value that `pay`
  checks against whichever key is the operator now. A new end date after a revoke turns the same key
  back on, up to the cap on every UTC day until it ends. A new key keeps the end date already on the
  vault. If a key may have leaked, call `setOperator` first, which stops the old key at once, and set
  a new end date after.

### What it checks, in order

**1. Free checks, nothing signed**

The asset is the registry's USDC and the vault's. An agent named in `payeeAgentId` is the
payee's. The vault's policy and a simulated `pay()` from its operator accept the payment (not
frozen, session key valid, payee allowed, within auto-approve, daily cap and balance). The
operator can pay the gas. If the vault would refuse, the answer is a refusal named after the
vault's own error, and the check is not bought. A payee that holds no agent is not refused, and
neither is a payment the operator cannot make and the owner can (see below).

**2. The check, 0.005 USDC**

`risk_check` through Circle Gateway, with the payee's address as `agentId` and the amount in
`txContext`. Never a CAIP id. It is the same settlement row as a direct `risk_check`, so your
wallet shows on [/proof/arc](https://a-identity.xyz/proof/arc) as external here too.

**3. The decision**

Read from the table below. Anything that is not a usable verdict counts as `DENY`.

**4. The payment, from your key**

The caller sends the prepared call with its own key. Nothing is retried with a new nonce.

**5. The record**

The transaction hash is posted to the flow. The server reads the receipt itself and records
only what it proves.

| Verdict | What happens | Paid by |
| - | - | - |
| `DENY` | Nothing to sign. The refusal is public on the flow record. You have paid for the check and nothing else. | Nobody |
| `WARN` | No automatic payment. The answer is the verdict plus a prepared `ownerPay` for the vault's owner (`awaiting_human`). Set `payOnWarn` to true to prepare `pay()` for the operator instead; it is off unless you ask. A payee we know nothing about gets `WARN`, so `payOnWarn` on such a payee is your own explicit choice to pay it. | The owner, or the operator with `payOnWarn` |
| `ALLOW` | The exact `pay(payee, amount)` for the operator to send. | The operator |
| `ALLOW` or `WARN`, on a payment above the vault's ceiling or off its allowlist | No automatic payment, whatever `payOnWarn` says: the vault would refuse the operator. The answer is the verdict plus a prepared `ownerPay` (`awaiting_human`, `ownerHandoff.ownerOnly` names the gate). | The owner |

Three real addresses show the verdicts, each with the day it was read. A check on any of them costs
0.005 USDC. The first two are ours, a payment to either is a real transfer to us, and their
reputations come from our own demo payments, so they show the rule path, not independent trust.

| Payee | What it is | Verdict |
| - | - | - |
| Simon, `0x03f1fb189E461B88f3e8bA7100B29B594E5f98A9` | A platform agent in our own account, holding Arc Mainnet ERC-8004 #104498 | `ALLOW`, reputation 555, on 2026-11-02; the free read shows 553 on 2026-11-04, still over the 500 it needs, and this one moves with its reputation, so read the live answer |
| Meridian, `0x4e26Ae66840134Ac5979c56ba2509F3956b93431` | Our showcase agent, a platform agent holding Arc Mainnet ERC-8004 #4306 | `WARN`, reputation 469 (below 500), on 2026-11-02, and the same on the free read of 2026-11-04; this one moves with its reputation, so read the live answer |
| `0xA65F35B21aB90D088c1197728cDd0563c1308735` | An agent on our platform named `test`, which we are not vouching for in any way | `DENY` by the rule, from the free reads on 2026-11-04 (`/api/reputation`: Sybil high, both of its 2 jobs hired by its own operator, reputation 90). The Sybil flag is the evidence: the low score alone would be `WARN`. No check was bought on it, so read the live answer, and do not pay it to see |

Do not pay `0xd305...ed36` or `0xF43F...742D`: A-Identity retired both on 2026-11-11 because someone else holds their keys, and neither is A-Identity's. On Arc Mainnet, payments to A-Identity go to `0xCB8824ffAF30687E36374C08eC52298b62871bdf`.

A payee that holds no agent on Arc Mainnet passes the free checks, and the check is then bought for
0.005 USDC. Unless it is an agent on our platform, the
answer is `WARN`, so it reaches `awaiting_human` with the owner's prepared payment. The same goes
for one that holds an agent but has no record on our platform. On a vault whose owner and operator
are one key, that `WARN` stops at `warn_no_human_gate` instead, with the check paid and nothing
prepared. An agent named in `payeeAgentId` that the payee does not own
(`PAYEE_AGENT_MISMATCH`) and a registry that does not answer (`REGISTRY_UNREADABLE`) are still
refused at the free checks, with nothing bought.

**What the operator cannot pay, the owner can.** A payment above the vault's per-payment ceiling
(`AboveAutoApprove`; a vault deployed at [/app/vault/arc](https://a-identity.xyz/app/vault/arc)
starts at 0.25 USDC), or to a payee off an allowlist that is on (`PayeeNotAllowed`), is one `pay()`
would revert and `ownerPay()` would not. So it is not refused at the free checks. The `402` says up
front that this applies, that the check is still charged, and that only the owner can settle it, and
`checks.vault.ownerOnly` names the gate. The flow then buys the check. A usable `ALLOW` or `WARN`
answers `awaiting_human` with `ownerPay`, a `DENY` refuses as usual, and `payOnWarn` cannot make the
operator pay what the vault would refuse. Since `ownerPay` has no cap check, a real invoice above the
ceiling reaches the owner even if it is above the daily cap too.

Every other refusal stays one, with nothing charged: a frozen vault, an expired session key, no
operator, a daily cap the payment would pass inside the ceiling, too little in the vault. On a vault
whose owner is its operator there is no human to hand anything to, so `AboveAutoApprove` and
`PayeeNotAllowed` stay refusals there as well.

### When a payment waits for its owner

Sending `ownerPay` counts toward the agent's day on the vault. If it uses up today's room, the agent
cannot pay until 00:00 UTC unless the owner raises the cap, and a verify-then-pay request for that vault
within the ceiling and on the allowlist is refused at the free checks until then.

`awaiting_human` hands back the exact call for the owner's key, and that key has to send it. If you
deployed from the vault page your wallet is the owner, so the vault page is where you do that.

Open your vault at [/app/vault/arc](https://a-identity.xyz/app/vault/arc) with the owner wallet
connected, and it lists the payments waiting for you. Or follow the link your agent sends you:
`ownerHandoff.approvalUrl` from the hosted route, `out.approvalUrl` from `verifyThenPay` 0.5.0, always on
`https://a-identity.xyz`. That link is `null` where the server can already see the page would refuse: a
check the operator key did not pay for, or a payment to the operator key itself. Then `next` says why, and
`ownerPay` from the owner key is the way. A link is no promise that the page will act. The page reads the
chain when it opens, and it can still refuse for what the server does not look at: a vault that is ours or
not the build the page deploys, a key stopped or replaced since the check, or a check older than 24 hours.
`GET /api/x402/gateway/flows/<flowId>` reads no chain, so it keeps naming the link through all of those.
For a vault the page does not act on, `ownerPay` from the owner key is the way then too. A stopped or
replaced key and a check that old are refused for the request itself, for the reasons below, so a new
check from a working agent key is the way there. For each payment the page says who gets paid, how much,
what the check said and why, when it was checked, and that approving counts toward today's budget. `ownerPay` adds to the
day's spending with no cap check, so an approval can use up the budget and stop your agent until 00:00
UTC. It works while the vault is frozen, by design, and the page says that too. You review it, your
wallet signs it, the page waits for the receipt and posts it, and the server reads it from the chain.
Nothing shows as paid before that.

What the page refuses, each for a reason:

* **A check your agent's key did not pay for.** A check costs 0.005 USDC and can name any vault, so a
  stranger can open a flow on yours with a payee of their own, and send you a link to it. A flow counts as
  a request from your agent only when its check was paid by this vault's operator as the chain reads it
  now, and by the operator of the moment it was checked. Anything else gets no action. The list shows
  only a count of them. A direct link shows a plain warning that the page cannot show it came from your
  agent, and neither the payee nor the amount. So pay for the check from the operator key, which is the
  default, if you want the page to offer the approval: a flow whose check a separate `payer` paid gets no
  action on the page and no approval link, and the sample below is the path for that.
* **A key you have stopped.** A request from a key that has since been revoked or has run out gets no
  action either: the server refuses a new request from that key, and one made just before does not go on
  asking. Replacing the key has the same effect. Freezing does not: `ownerPay` works on a frozen vault by
  design, so a request stays on the page, and the card says that it came from the key you may have frozen
  the vault to stop. None of these changes the public record, which still reads as waiting.
* **A record that does not match.** `owner()`, the operator and the balance are read from the chain, and
  `ownerPay` is encoded from the payee and the amount on screen and compared with the call the record
  prepared. On any difference there is no action. The connected wallet has to be the vault's owner, on
  the registry's chain.
* **A second send.** The contract knows nothing of flows, so two sends pay twice. The page keeps the hash
  by flow in your browser, from before your wallet is asked, shared by tabs and kept across a reload, and
  offers no second send until that hash has a final answer. It also reads the vault's own `Paid` events
  before it offers anything, so a payment you made from another browser or wallet is not made again. A
  wallet's speed-up gives the payment a new hash, and the page finds that one the same way. A vault payment
  names no check, so an owner's payment answers the latest check the operator paid for, ahead of any other
  key's, and a stranger's identical check cannot take it. A check that comes after a payment is a new
  request, because that is how a second payment is meant to happen, so the page offers it, and says
  plainly when the vault paid the same amount to the same payee in the 6 hours before that check. What the
  page cannot stop is a wallet prompt answered after you told it nothing was sent and sent again: sign both,
  and both pay. It keeps and follows each hash your wallet hands back to it, and each payment its read of the
  vault finds while it waits on your wallet, from your key or your agent's, and says so when there are two.
  It tells you to decline the last prompt it opened once the payment has left, or once a transaction your
  wallet sent for an earlier prompt is on its way. The flow's public record holds one of them. Once a hash for
  that request is on its way, the page follows that hash, so a second payment made after that from anywhere
  else, or one whose hash never reaches the page, shows only in the vault's activity on the page.
* **A check older than 24 hours**, by the chain's clock. An owner has to be able to find a request in a
  working day, and past that our answer may be wrong without anyone having seen it change. A new check
  costs your agent 0.005 USDC.
* **A failed practice run.** The call is simulated from your account right before each send, and if that
  fails the page says why and sends nothing.
* **`DENY` and refused flows** never get an action, and neither does a payment to your agent's own key.

**Saying no.** A flow has no state for it, so nothing records your answer. The page hides the payment in
your browser, and that is all: your agent is not told, the public record still says it is waiting, and the
agent can ask again. It stops being offered 24 hours after the check. Saying no does not stop your agent:
use Freeze or Revoke on the same page for that. On this page only your own wallet can send the payment, but
a payment within your agent's limits is one its key can still send by itself, because the contract knows
nothing of flows. Only a payment above the ceiling or off the allowlist is one it cannot.

What only a person with a real wallet can see is how that wallet shows the call. The page has been run
against a real backend and a real browser on a local fork of Arc Mainnet with a stand-in wallet, and that
does not show a real wallet's own screens or how it prices a transaction.

**A key held by a script, or a browser wallet with no page.** The flow id is what your agent got back:
`out.flowId` from `verifyThenPay`, or `flowId` from the hosted route. `GET /api/x402/gateway/flows?vault=0x...`
lists what waits on a vault. The flow record is public, so nothing here needs a secret, and the sample
encodes the call itself rather than trusting the record. Read the verdict's reasons first, and check
`flow.check.payer` against the vault's `operator()`: nothing below does that for you.

```ts theme={null}
import { createPublicClient, createWalletClient, custom, encodeFunctionData, http, parseAbi } from 'viem'
import { ARC_MAINNET, arcViemChain } from '@a-identity/trust-guard/arc'

const base = 'https://a-identity.xyz/api/x402/gateway'
const { flow } = await (await fetch(`${base}/flows/${flowId}`)).json()
if (flow?.outcome !== 'awaiting_human') throw new Error('this flow is not waiting for its owner')
console.log(flow.verdict.reasons) // read these before you pay

const abi = parseAbi(['function ownerPay(address to, uint256 amount)'])
const args = [flow.payee, BigInt(flow.amount)] as const
const data = encodeFunctionData({ abi, functionName: 'ownerPay', args })
if (data !== flow.prepared.data) throw new Error('the record prepared a different call than the one it describes')

const [owner] = await window.ethereum.request({ method: 'eth_requestAccounts' })
const reader = createPublicClient({ chain: arcViemChain, transport: http() })
// Throws if the vault would refuse it right now: sending it then would revert and cost gas.
await reader.simulateContract({ account: owner, address: flow.vault, abi, functionName: 'ownerPay', args })

const wallet = createWalletClient({ account: owner, chain: arcViemChain, transport: custom(window.ethereum) })
const txHash = await wallet.sendTransaction({
  to: flow.vault,
  data,
  value: 0n,
  maxFeePerGas: ARC_MAINNET.minMaxFeePerGasWei * 2n,
  maxPriorityFeePerGas: 1_000_000_000n,
})
await fetch(`${base}/flows/${flowId}/receipt`, {
  method: 'POST',
  headers: { 'content-type': 'application/json' },
  body: JSON.stringify({ txHash }),
})
```

A script holding the owner key does the same with `privateKeyToAccount` in place of `custom(window.ethereum)`,
and with what `verifyThenPay` returned in `out.ownerPay` when it runs in the owner's process. Do not put a
browser wallet's key into a file to do this. Over the hosted route the same call is
`ownerHandoff.ownerPay`, with its fee under `fees`; send it, then POST the hash to `/flows/<flowId>/receipt`.

### The hosted route

`POST https://a-identity.xyz/api/x402/gateway/verify-then-pay` takes the vault, the payee and the
amount in USDC base units (6 decimals, digits only). It never signs and never broadcasts. The
answer is always `executed: false`.

```bash theme={null}
curl -s -X POST https://a-identity.xyz/api/x402/gateway/verify-then-pay \
  -H 'content-type: application/json' \
  -d '{"vault":"0xYourVault","payee":"0x4e26Ae66840134Ac5979c56ba2509F3956b93431","amount":"250000"}'
```

Unpaid, it answers `402` with the Arc Mainnet offer in `challenge`. Sign it as in
[Pay](#the-10-minute-flow), from your Gateway balance, and send the same body again with the
`PAYMENT-SIGNATURE` header. Optional fields are `asset`, `payeeAgentId` (checked on chain only, and
never sent to `risk_check`) and `payOnWarn`. The body's `stage` says where the flow stands:

| Status | `stage` | Meaning |
| - | - | - |
| `400`, `422` | `refused` | Bad input, a named agent that is not the payee's, or the vault would refuse and this flow hands nothing to its owner, whose `ownerPay` is a separate act. `code` names why. Nothing charged, and no verdict comes back. |
| `409` | `refused` | `NONCE_ALREADY_USED`: this authorization already opened a flow. This request charged nothing, but the first request with this nonce may have been charged and may hold a verdict, or may still be running. Read `GET /api/x402/gateway/flows/<nonce>`. A flow there that names this vault, payee and amount is your answer, so do not sign again. One that names others does not answer this request, and when the server can compare them it says so outright: sign a new authorization for this request, which costs another 0.005 USDC. If that read answers `404`, look the nonce up on the Gateway proof log, which lists only the newest 50 rows, and read both again in a minute, because a request still running shows in neither. If neither shows the nonce by then, or the proof log says it failed, sign a new authorization. If the proof log reads `credited`, `completed` or `unconfirmed` and the flow still answers `404`, treat this nonce as giving no flow: a new authorization costs another 0.005 USDC, and one that reads `unconfirmed` may still settle until it expires. |
| `402` | `payment_required` | The free checks passed. Nothing charged yet. A payee that holds no agent passes them, with `checks.payee.agentsHeld` 0, and `next` says what to expect. So does a payment only the owner can settle, with `checks.vault.ownerOnly` set, and `next` says the check is still charged. |
| `402` | `check_failed` | Gateway refused the signed payment, for example for too small a balance. `charged` is false, no flow was recorded, and `reason` says why. A fresh offer comes back in `challenge`, but this nonce has had its one attempt, and sending it again answers `409`: fix what `reason` names, then sign a new authorization. Do not re-sign on any `402` without reading `stage`. |
| `200` | `prepared` | Send `prepared` from the operator key, unless `prepared.simulation.ok` is false, which means the vault would refuse it right now. |
| `200` | `awaiting_human` | `WARN`, or a usable verdict on a payment only the owner can settle: send the owner `ownerHandoff.approvalUrl`, which is `null` where the server can see the vault page would refuse this, and which the page can still refuse for what the server does not look at, or send `ownerHandoff.ownerPay` from the owner key, unless `ownerHandoff.ownerPay.simulation.ok` is false, which means the vault would refuse it right now. A payee we know nothing about ends here. |
| `200` | `deny`, `verdict_unusable` | Do not pay. Nothing was prepared. |
| `200` | `warn_no_human_gate` | `WARN`, and the vault's owner and operator are one key, so there is nobody to hand it to. The check was paid. Do not pay. Nothing was prepared. |
| `409`, `500` | `deny`, `verdict_unusable` | Do not pay. The check was paid and answered, but the flow log does not hold the refusal, so it is not public. |
| `429` | none over HTTP, `refused` over MCP | Over the budget of 30 calls a minute per address, so nothing was read and nothing charged, and the same request can go again after the wait. Over HTTP the body is only `{"error": "..."}` with a `Retry-After` header, so it has no `stage`, `code` or `charged`: `stage` `refused` with `code` `RATE_LIMITED` is the MCP tool's answer alone. The SDK reads a limited signed POST as `NETWORK` with `paid` null, because that body does not say, and `recordFlowReceipt` waits as `Retry-After` says, up to a minute, and posts again, at most 3 posts. |
| `503` | `refused` | The chain or the flow log did not answer, so nothing could be decided. Nothing charged. Ask again shortly. |
| `409`, `500`, `502`, `503` | `check_failed`, `unavailable` | No payment to send. `charged` says whether the check was paid, and `null` means that is not known: do not sign again before looking the nonce up on the Gateway proof log, which lists only the newest 50 rows. If it reads `unconfirmed`, treat this nonce as giving no flow: a new authorization costs another 0.005 USDC, and this one may still settle until it expires. |
| `501` | `unavailable` | The rail is not selling on Arc Mainnet right now. Nothing charged. |

If you send the transaction yourself, three things about Arc matter. A `maxFeePerGas` below 20 gwei
is dropped silently, with no error. One RPC can answer null for a receipt that exists, so a null
does not mean the transaction is gone; never resend it with a new nonce. And USDC has 6 decimals as
an ERC-20 but 18 as native gas, so the amount here is always the 6-decimal one.

### The MCP tools

`verify_then_pay` and `verify_then_pay_receipt` are these routes through the
[MCP server](https://a-identity.mintlify.site/developers/mcp-server.md). They never sign. Call `verify_then_pay` without `payment` to
get the challenge, then again with `payment` set to the base64 signature your own key made. Then
send the prepared call yourself and pass the hash to `verify_then_pay_receipt`.

### The public flow record

`GET https://a-identity.xyz/api/x402/gateway/flows/<flowId>` needs no key. The `flowId` is the
check's authorization nonce. The record holds the vault with its owner and operator, the payee, the
amount, the check, the verdict with its reasons, the prepared call, and the payment once proven.
It is public on purpose, for every flow, because a `DENY` has no transaction and this record is the
evidence it happened. Do not use this route for a payment you need to keep private.

`GET https://a-identity.xyz/api/x402/gateway/flows?vault=0x...` needs no key either, and publishes
nothing new. `waiting` holds the flows waiting for that vault's owner whose check was paid by the key
that was its operator when checked, newest first, at most 20, and `truncated` says when there were
more. Only a receipt closes a flow, and saying no on the page records nothing, so neither age nor a no
makes room: a request past the newest 20 is not listed. The approval link your agent sent for it still
opens it on the page until 24 hours after its check, and `GET .../flows/<flowId>` still reads it.
Compare a row with the vault's operator now before you treat one as a request. `notFromOperator`
only counts the rest, up to 100: anyone can buy a check naming any vault, so those are not requests,
and they cannot crowd out the ones that are. It allows 30 reads a minute per address.

`POST .../flows/<flowId>/receipt` with `{"txHash":"0x..."}` closes a flow. The server reads the
receipt from every RPC and marks the flow `executed` only on the vault's `Paid` event and USDC's
`Transfer` to the checked payee for the checked amount, in a block after the verdict. A flow waiting
for its owner is closed only by the owner's call.

### The SDK

`verifyThenPay` from `@a-identity/trust-guard/arc` runs all of this with your keys: it encodes the
payment from your own inputs, compares it byte for byte with what the server prepared, sends it, and
posts the receipt. A compromised server cannot redirect the payment. The verdict itself is not
signed, so you still trust our server and the TLS connection for what it says.

Install it with `npm install @a-identity/trust-guard viem @circle-fin/x402-batching`. `verifyThenPay`
needs version 0.4.0 or later. `ownerOnly`, `out.approvalUrl` and the hand-off of a payment above the
ceiling or off the allowlist need 0.5.0, which is in the repo and not on npm yet, so that command gets
0.4.0 for now: there `out.approvalUrl` is undefined, and such a payment throws `VaultPolicyError` before
anything is signed. The [README](https://github.com/getA-Identity/A-Identity/blob/main/trust-guard/README.md)
describes 0.5.0, with the code and every error it throws. For Milestone 2, the direct check at the top
of this page is the shortest path.

## Free reads

Identity and reputation reads cost nothing and need no key. The MCP server at
`https://a-identity.xyz/mcp` (Streamable HTTP, stateless) exposes them to any MCP client:

```bash theme={null}
claude mcp add --transport http a-identity https://a-identity.xyz/mcp
```

`resolve_agent` reads an ERC-8004 identity live from the registry, `get_reputation`
returns the deterministic score with its breakdown, `merchant_check` returns a free
ALLOW / WARN / DENY for a merchant-side agent before a checkout, and `get_chain_status`
lists every chain in the registry with its live status. The free `trust_preview` on this rail is the same
idea over plain HTTP. Free reads do not appear on the proof page, because there is no
payment to record, and they do not count as usage for Milestone 2, which counts paid checks only.
The full tool list is on the [MCP server](https://a-identity.mintlify.site/developers/mcp-server.md) page.

Two free reads need the chain named. Without `chain`, `evm_pay_check` reads a bare address, a `#0`
id or a link on Robinhood Chain, so pass `chain: "arc-mainnet"` for those; a full id such as
`eip155:5042:8004/0` names its own chain. `resolve_agent` with a bare token id
such as `#0` can match agents on several chains, so pass the full id, `eip155:5042:8004/0`.

## What we never do

* **No keys of yours on our servers.** You sign locally, in the CLI, the SDK or your own
  code; we receive a signed authorization that can move exactly the price to exactly our
  `payTo`, and nothing else.
* **No payment counted without a Gateway read-back.** Gateway's settle response saying
  success is not enough: the transfer must come back from Gateway's transfers API for your
  nonce, to our `payTo`, for the price, before the result is served or the row is recorded
  as revenue. A read-back that fails is a 502 and an `unconfirmed` row in public.
* **No challenge we could not settle.** Before any 402 we read Gateway's live
  `/v1/x402/supported` and refuse to sell if the advertised `verifyingContract` or USDC
  differs from the registry.
* **Internal traffic labeled, never hidden.** Our own payments are on the same proof page
  as yours, tagged internal, and the season report counts them separately.
* **No settlement fee on this rail.** Through Circle Gateway the price in the 402 is the
  whole cost. Our other rail on Arc Mainnet, the EIP-3009 facilitator on
  [/arc](https://a-identity.xyz/arc), adds a settlement fee for the gas we pay, so the same tool
  costs more there; [/api/facilitator/status](https://a-identity.xyz/api/facilitator/status?network=eip155:5042)
  states the fee.

> [card] [Circle Nanopayments](https://a-identity.mintlify.site/protocols/nanopayments.md)
>
> How the batched rail settles, and what it gives up next to on-chain x402.

> [card] [Build on Arc](https://a-identity.mintlify.site/chains/arc.md)
>
> Network config, the mainnet registry entry and everything else we run on Arc.


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