Integrate institutional agent payments

API base URL: Testnet https://xapg.io · Mainnet https://mainnet.xapg.io

Testnet and Mainnet use separate hosts. Before signing, confirm the environment and CAIP-2 network returned by GET /supported.

x402 v2 · exact · Base · USDC · EIP-3009
x402 v2 · batch-settlement · Base · USDC · payment channel

Get an institution API key first

Manage institution API keys

Use an institution API key for the selected environment. Grant supported for discovery, verify for validation, and settle only to the service authorized to submit settlement.

Exact · Quick Start · Testnet

Sign a Base Sepolia USDC authorization and call /verify. This example does not submit settlement.

Install

mkdir xapg-testnet && cd xapg-testnet
npm init -y
npm install --save-exact viem@2.55.19
mkdir scripts

// Base Sepolia only. Use a disposable Testnet wallet.
import { randomBytes } from 'node:crypto';
import { resolve } from 'node:path';
import { pathToFileURL } from 'node:url';
import { getAddress, formatUnits } from 'viem';
import { privateKeyToAccount } from 'viem/accounts';

const BASE = 'https://xapg.io';
const RESOURCE = `${BASE}/x402/resource`;
const NETWORK = 'eip155:84532';
const USDC = '0x036CbD53842c5426634e7929541eC2318f3dCF7e';
const same = (a, b) => a?.toLowerCase() === b?.toLowerCase();
const assert = (ok, message) => { if (!ok) throw new Error(message); };

export async function runQuickVerify(env, deps = {}) {
  const fetcher = deps.fetcher ?? fetch;
  const log = deps.log ?? console.log;
  const apiKey = env.XAPG_FACILITATOR_API_KEY;
  assert(/^xapg_(?:test|inst)_[A-Za-z0-9_-]+$/.test(apiKey ?? ''), 'Missing institution API key');

  const api = async (path, body) => {
    const response = await fetcher(`${BASE}${path}`, {
      method: body ? 'POST' : 'GET', redirect: 'error',
      headers: { 'X-API-Key': apiKey, Accept: 'application/json',
        ...(body ? { 'Content-Type': 'application/json' } : {}) },
      ...(body ? { body } : {}), signal: AbortSignal.timeout(20_000),
    });
    assert(response.status === 200, `${path} returned HTTP ${response.status}`);
    return response.json();
  };

  const supported = await api('/supported');
  assert(supported.kinds?.some(k => k.x402Version === 2 && k.scheme === 'exact' && k.network === NETWORK), 'Unsupported payment kind');
  assert(supported.assets?.some(a => a.network === NETWORK && same(a.address, USDC)), 'Unsupported asset');

  const challenge = await fetcher(RESOURCE, { redirect: 'error', signal: AbortSignal.timeout(20_000) });
  assert(challenge.status === 402, 'Expected HTTP 402');
  const encoded = challenge.headers.get('PAYMENT-REQUIRED');
  assert(encoded && encoded.length < 65_536, 'Missing payment requirements');
  const required = JSON.parse(Buffer.from(encoded, 'base64url').toString()).accepts
    ?.find(r => r.scheme === 'exact' && r.network === NETWORK && same(r.asset, USDC));
  assert(required, 'No supported payment requirement');
  getAddress(required.payTo);
  assert(BigInt(required.amount) > 0n && BigInt(required.amount) <= 10_000n, 'Amount exceeds 0.01 test USDC');

  if (env.inspect) {
    log(`INSPECT ONLY\nNetwork: Base Sepolia\nAsset: USDC\npayTo: ${required.payTo}\nAmount: ${formatUnits(BigInt(required.amount), 6)} USDC\nNO SIGNATURE · NO PAYMENT`);
    return { status: 'inspected', payTo: required.payTo, amount: required.amount };
  }

  assert(same(required.payTo, getAddress(env.XAPG_ALLOWED_PAY_TO)), 'Recipient is not approved');
  assert(/^0x[0-9a-fA-F]{64}$/.test(env.XAPG_TEST_PRIVATE_KEY ?? ''), 'Missing Testnet private key');
  log('1. DISCOVERED · Recipient and amount approved · NOT PAID.');

  const account = privateKeyToAccount(env.XAPG_TEST_PRIVATE_KEY);
  const now = deps.now ?? Math.floor(Date.now() / 1000);
  const authorization = { from: account.address, to: required.payTo, value: required.amount,
    validAfter: String(now - 60), validBefore: String(now + 120),
    nonce: `0x${randomBytes(32).toString('hex')}` };
  const signature = await account.signTypedData({
    domain: { name: 'USDC', version: '2', chainId: 84532, verifyingContract: USDC },
    types: { TransferWithAuthorization: [
      { name: 'from', type: 'address' }, { name: 'to', type: 'address' },
      { name: 'value', type: 'uint256' }, { name: 'validAfter', type: 'uint256' },
      { name: 'validBefore', type: 'uint256' }, { name: 'nonce', type: 'bytes32' },
    ] }, primaryType: 'TransferWithAuthorization', message: authorization,
  });
  log('2. SIGNED · EIP-3009 authorization signed locally · NOT PAID.');

  const body = JSON.stringify({ x402Version: 2, paymentPayload: { x402Version: 2,
    resource: { url: RESOURCE }, accepted: required, payload: { signature, authorization } },
    paymentRequirements: required });
  const verified = await api('/verify', body);
  assert(verified.isValid === true && same(verified.payer, account.address), verified.invalidReason ?? 'Verification failed');
  log('3. VERIFIED · isValid: true · NOT PAID.');
  return { status: 'verified', payer: account.address };
}

if (process.argv[1] && import.meta.url === pathToFileURL(resolve(process.argv[1])).href) {
  runQuickVerify({ ...process.env, inspect: process.argv.includes('--inspect') })
    .catch(error => { console.error(error.message); process.exitCode = 1; });
}

Create .env with your institution API key. Use a disposable Testnet wallet only.

XAPG_FACILITATOR_API_KEY=xapg_test_REPLACE_ME
XAPG_TEST_PRIVATE_KEY=0xREPLACE_WITH_TEST_PRIVATE_KEY
XAPG_ALLOWED_PAY_TO=

node --env-file=.env scripts/institution-quick-verify.mjs --inspect

INSPECT ONLY · NO SIGNATURE · NO PAYMENT

Exact EIP-3009: /verify validates authorization locally; /settle checks current chain state before submission. Successful verification does not guarantee payment.

node --env-file=.env scripts/institution-quick-verify.mjs

1. DISCOVERED · Recipient and amount approved · NOT PAID.
2. SIGNED · EIP-3009 authorization signed locally · NOT PAID.
3. VERIFIED · isValid: true · NOT PAID.

Two different keys

Exact · signing with EIP-712 / EIP-3009

The payer signs an EIP-3009 TransferWithAuthorization locally using EIP-712 typed data.

const signature = await account.signTypedData({
  domain,
  types,
  primaryType: "TransferWithAuthorization",
  message: authorization
});

name               USDC
version            2
chainId            84532
verifyingContract  0x036CbD53842c5426634e7929541eC2318f3dCF7e

name               USD Coin
version            2
chainId            8453
verifyingContract  0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913

TransferWithAuthorization · signed fields

from          address
to            address
value         uint256
validAfter    uint256
validBefore   uint256
nonce         bytes32

Amounts are decimal strings in USDC atomic units: 10000 = 0.01 USDC. Times are Unix seconds; the example expires 120 seconds after signing.

Field mapping

Exact + Batch · GET /supported

Shared API contract · Testnet and Mainnet

Both environments use the same methods, paths, headers and scopes. Capability discovery determines the available schemes and network; it does not authorize Mainnet access.

OpenAPI 3.1 JSON

not_submitted means no submission was attempted; failed means a known failure; unknown means the outcome must be reconciled by request ID before any resubmission. Retryability alone does not authorize resubmission.

Extension fields are accepted. Payload authorization and network compatibility are validated by the selected scheme adapter. Public responses omit internal diagnostics. API errors retain the string error field; additive errorDetail.code is present on standardized errors and optional for legacy authentication/CSRF errors. Local Mainnet execution refusal preserves its nested error.code variant. Successful settlements require network; legacy rejected operations may omit network.

X-Request-ID is optional on all endpoints. Supply a UUID or the server generates one; responses return it in X-Request-ID. Persist a client-generated UUID before settlement to recover a lost response through /settlements/:requestId.

Returns supported kinds, assets and adapters. Requires supported scope; no request body.

network = required network
scheme  = exact OR batch-settlement
asset   = required USDC
adapter = eip-3009

ALL MATCH → continue
OTHERWISE → stop

Match kinds, assets and extensions[].adapters by network.

{
  "kinds": [
    { "x402Version": 2, "scheme": "exact", "network": "eip155:CHAIN_ID" },
    { "x402Version": 2, "scheme": "batch-settlement", "network": "eip155:CHAIN_ID" }
  ],
  "extensions": [{
    "name": "xapg-payment-adapters",
    "version": "1",
    "adapters": [{
      "id": "eip-3009",
      "network": "eip155:CHAIN_ID",
      "asset": "0x…",
      "settlementSpenders": ["0x…"]
    }]
  }],
  "signers": { "eip155:*": ["0x…"] },
  "assets": [{
    "network": "eip155:CHAIN_ID",
    "address": "0x…",
    "symbol": "USDC",
    "decimals": 6,
    "protocols": ["x402"]
  }]
}

Exact · shared signed payment body

Exact extra.protocol selects an adapter: omitted or eip-3009 (case-insensitive). Batch extra.assetTransferMethod selects token funding: eip3009 only, required by this implementation. These fields have different purposes and are not interchangeable. Permit2 is only exposed for configured Polygon Amoy adapters; this Base Batch profile does not accept it.

paymentPayload.resource is optional on /verify and /settle. Its URL and metadata are not verified by these facilitator routes or signed by EIP-3009. Agent approval separately validates resourceUrl against its URL policy; institutions must bind the resource to the approved order.

paymentPayload.accepted must equal paymentRequirements. Keep the signed amount, recipient, nonce and validity window unchanged between /verify and /settle.

{
  "x402Version": 2,
  "paymentPayload": {
    "x402Version": 2,
    "resource": {
      "url": "https://merchant.example/resource",
      "description": "Order description",
      "mimeType": "application/json"
    },
    "accepted": {
      "scheme": "exact",
      "network": "eip155:CHAIN_ID",
      "amount": "10000",
      "asset": "0x…USDC from /supported…",
      "payTo": "0x…beneficiary…",
      "maxTimeoutSeconds": 120,
      "extra": { "name": "USDC", "version": "2", "protocol": "eip-3009" }
    },
    "payload": {
      "signature": "0x…EIP-712 signature…",
      "authorization": {
        "from": "0x…payer…",
        "to": "0x…same beneficiary…",
        "value": "10000",
        "validAfter": "…unix seconds…",
        "validBefore": "…unix seconds…",
        "nonce": "0x…32 bytes…"
      }
    }
  },
  "paymentRequirements": {
    "scheme": "exact",
    "network": "eip155:CHAIN_ID",
    "amount": "10000",
    "asset": "0x…USDC from /supported…",
    "payTo": "0x…beneficiary…",
    "maxTimeoutSeconds": 120,
    "extra": { "name": "USDC", "version": "2", "protocol": "eip-3009" }
  }
}

Batch Settlement · Base

Deposit USDC into a channel, sign cumulative vouchers, then claim and settle the merchant balance.

Create and identify a channel

Compute channelId locally with computeChannelId(channelConfig, network). Save both values before signing; changing the network or any channel field creates a new ID.

Wallet Demo uses the connected payer as both authorizers to demonstrate all operations. Merchant integrations use their agreed receiverAuthorizer.

Contract source and signing domains

Use @x402/evm 2.25.0 and import BATCH_SETTLEMENT_ADDRESS and BATCH_SETTLEMENT_DOMAIN for Batch signatures.

settlementSpenders contains facilitator signer addresses. Use BATCH_SETTLEMENT_ADDRESS as the Batch verifyingContract.

Use the selected network chainId in both domains. requirements.extra.name/version belongs to USDC. Deposit signs ReceiveWithAuthorization; Exact signs TransferWithAuthorization.

Public SDK package · 2.25.0

supported.signers lists facilitator transaction signers, not payer or merchant authorizers. settlementSpenders is the adapter-specific spender list; never substitute either for channel payerAuthorizer or receiverAuthorizer.

Operation map

Amounts by operation

All amounts use decimal strings in 6-decimal USDC atomic units. requirements.amount is the service charge. deposit.amount is channel funding; voucher.maxClaimableAmount and claim.totalClaimed are cumulative ceilings and targets, not incremental charges. Refund amount is the returned balance; settle transfers the receiver/token aggregate pending balance.

Batch · claim response

Each request accepts 1–100 claims and executes atomically. One transaction hash covers the entire request; partial success is not supported.

{
  "success": true,
  "network": "eip155:84532",
  "transaction": "0x...one transaction for the complete claim batch..."
}

Examples below follow the selected environment. The 0.03 USDC lifecycle example requires a deposit limit of at least 30000; confirm the deployed allowance before using it.

Shared requirements

Use identical paymentPayload.accepted and paymentRequirements. Generate payloads with the Batch SDK; amounts are decimal strings in USDC atomic units.

{
  "scheme": "batch-settlement",
  "network": "eip155:84532",
  "amount": "10000",
  "asset": "0x036CbD53842c5426634e7929541eC2318f3dCF7e",
  "payTo": "0x...merchant...",
  "maxTimeoutSeconds": 300,
  "extra": {
    "receiverAuthorizer": "0x...merchant authorizer...",
    "withdrawDelay": 900,
    "name": "USDC",
    "version": "2",
    "assetTransferMethod": "eip3009",
    "minDeposit": "{{minDeposit}}"
  }
}

Deposit must cover requirements.amount and minDeposit. The initial voucher still requires a separate claim after deposit.

Operation payload schema · SDK 2.25.0

Place these structures in paymentPayload.payload. Addresses and signatures use hex; amounts and nonces use decimal strings. withdrawDelay and withdrawRequestedAt are JSON numbers.

ChannelConfig = { payer: address, payerAuthorizer: address,
  receiver: address, receiverAuthorizer: address, token: address,
  withdrawDelay: number, salt: bytes32 }
Voucher = { channelId: bytes32, maxClaimableAmount: string, signature: hex }
Claim = { voucher: { channel: ChannelConfig, maxClaimableAmount: string },
  signature: hex, totalClaimed: string }

deposit = { type: "deposit", channelConfig: ChannelConfig, voucher: Voucher,
  deposit: { amount: string, authorization: { erc3009Authorization: {
    validAfter: string, validBefore: string, salt: bytes32, signature: hex
  } } } }
voucher = { type: "voucher", channelConfig: ChannelConfig, voucher: Voucher }
claim = { type: "claim", claims: Claim[], claimAuthorizerSignature: hex }
settle = { type: "settle", receiver: address, token: address }
refund (/verify) = { type: "refund", channelConfig: ChannelConfig,
  voucher: Voucher, amount?: string }
refund (/settle) = { type: "refund", channelConfig: ChannelConfig,
  voucher: Voucher, amount: string, refundNonce: string, claims: Claim[],
  refundAuthorizerSignature: hex, claimAuthorizerSignature?: hex }

Voucher signature

payerAuthorizer signs Voucher(channelId, maxClaimableAmount). Use signVoucher; maxClaimableAmount is a cumulative ceiling. Save the voucher before service delivery.

ClaimBatch signature

payerAuthorizer signs each voucher; receiverAuthorizer signs ClaimBatch. totalClaimed is the new cumulative target. Supply claimAuthorizerSignature and submit to /settle; /verify does not accept claim or settle.

Refund signature

Verify the refund to obtain refundNonce, then have receiverAuthorizer sign Refund(channelId, nonce, amount). Add refundAuthorizerSignature and claims to the settlement body; nonempty claims also require claimAuthorizerSignature.

Complete settlement envelope · illustrative

Settlement transfers the aggregate receiver/token balance after claims. Testnet illustration only: deposit 30000; claim cumulative 20000; settle 20000; refund unused 10000. Voucher ceilings are not added together.

{
  "x402Version": 2,
  "paymentPayload": {
    "x402Version": 2,
    "accepted": {
      "scheme": "batch-settlement",
      "network": "eip155:84532",
      "amount": "10000",
      "asset": "0x036CbD53842c5426634e7929541eC2318f3dCF7e",
      "payTo": "0x1111111111111111111111111111111111111111",
      "maxTimeoutSeconds": 300,
      "extra": {
        "receiverAuthorizer": "0x2222222222222222222222222222222222222222",
        "withdrawDelay": 900,
        "name": "USDC",
        "version": "2",
        "assetTransferMethod": "eip3009",
        "minDeposit": "{{minDeposit}}"
      }
    },
    "payload": {
      "type": "settle",
      "receiver": "0x1111111111111111111111111111111111111111",
      "token": "0x036CbD53842c5426634e7929541eC2318f3dCF7e"
    }
  },
  "paymentRequirements": {
    "scheme": "batch-settlement",
    "network": "eip155:84532",
    "amount": "10000",
    "asset": "0x036CbD53842c5426634e7929541eC2318f3dCF7e",
    "payTo": "0x1111111111111111111111111111111111111111",
    "maxTimeoutSeconds": 300,
    "extra": {
      "receiverAuthorizer": "0x2222222222222222222222222222222222222222",
      "withdrawDelay": 900,
      "name": "USDC",
      "version": "2",
      "assetTransferMethod": "eip3009",
      "minDeposit": "{{minDeposit}}"
    }
  }
}

Lifecycle signing example · integration skeleton

Lifecycle example: supply signers, authenticated transport and durable storage. Save each operation body and key before submission. Calling lifecycle again creates a new channel; retries use the saved operation.

import { computeChannelId, createBatchSettlementEIP3009DepositPayload,
  signVoucher } from "@x402/evm/batch-settlement/client";
import { BATCH_SETTLEMENT_ADDRESS, BATCH_SETTLEMENT_DOMAIN } from "@x402/evm";
import { toHex } from "viem";

// Inputs: institutional payerSigner and receiverSigner (ClientEvmSigner),
// merchant-approved requirements, authenticated post(path, body, headers),
// durable persist(record), and reconcile(stage, request, result).
// reconcile must verify the receipt and operation-specific state/movements.
// post returns parsed JSON only after checking the HTTP response status.
async function lifecycle({ payerSigner, receiverSigner, requirements, post, persist, reconcile }) {
  if (requirements.network !== "eip155:84532" ||
      requirements.amount !== "10000" ||
      requirements.extra.receiverAuthorizer.toLowerCase() !==
        receiverSigner.address.toLowerCase()) throw Error("Example configuration mismatch");
  const channelConfig = {
    payer: payerSigner.address, payerAuthorizer: payerSigner.address,
    receiver: requirements.payTo, receiverAuthorizer: receiverSigner.address,
    token: requirements.asset, withdrawDelay: requirements.extra.withdrawDelay,
    salt: toHex(crypto.getRandomValues(new Uint8Array(32)))
  };
  const channelId = computeChannelId(channelConfig, requirements.network);
  const domain = { ...BATCH_SETTLEMENT_DOMAIN, chainId: 84532,
    verifyingContract: BATCH_SETTLEMENT_ADDRESS };
  const body = payload => ({ x402Version: 2,
    paymentPayload: { x402Version: 2, accepted: requirements, payload },
    paymentRequirements: requirements });
  async function verify(payload) {
    const result = await post("/verify", body(payload), {});
    if (!result.isValid) throw Error(result.invalidReason);
    return result;
  }
  async function submit(stage, payload) {
    const request = body(payload), key = `batch-${crypto.randomUUID()}`;
    const requestId = crypto.randomUUID();
    const operation = { stage, channelId, channelConfig, request,
      idempotencyKey: key, requestId, status: "prepared" };
    await persist(operation); // Durable, before any network submission.
    let result;
    try {
      result = await post("/settle", request,
        { "Idempotency-Key": key, "X-Request-ID": requestId });
    } catch (error) {
      await persist({ ...operation, status: "unknown" });
      return { halted: true, requestId, settlementStatus: "unknown" };
    }
    await persist({ ...operation, result, status: result.success ? "submitted"
      : result.failure?.settlementStatus ?? "unknown" });
    if (!result.success) {
      const state = result.failure?.settlementStatus;
      if (state === "unknown" || !state)
        return { halted: true, requestId, settlementStatus: "unknown" };
      throw Error(result.errorReason ?? result.failure?.code ?? "Settlement rejected");
    }
    await reconcile(stage, request, result);
    await persist({ ...operation, result, status: "reconciled" });
    return result;
  }
  await persist({ channelConfig, channelId });
  // First 0.01 USDC commitment, backed by a 0.03 USDC deposit.
  const deposit = await createBatchSettlementEIP3009DepositPayload(
    payerSigner, 2, requirements, channelConfig, "30000", "10000");
  await verify(deposit.payload);
  const depositResult = await submit("deposit", deposit.payload);
  if (depositResult.halted) return depositResult;
  // Second charge raises the cumulative ceiling to 0.02 USDC.
  const voucher = await signVoucher(payerSigner, channelId, "20000", requirements.network);
  await verify({ type: "voucher", channelConfig, voucher });
  await persist({ channelId, voucher, chargedCumulativeAmount: "20000" });
  const claims = [{ voucher: { channel: channelConfig, maxClaimableAmount: "20000" },
    signature: voucher.signature, totalClaimed: "20000" }];
  const claimAuthorizerSignature = await receiverSigner.signTypedData({ domain,
    types: { ClaimBatch: [{ name: "claims", type: "ClaimEntry[]" }], ClaimEntry: [
      { name: "channelId", type: "bytes32" },
      { name: "maxClaimableAmount", type: "uint128" },
      { name: "totalClaimed", type: "uint128" }] },
    primaryType: "ClaimBatch", message: { claims: [
      { channelId, maxClaimableAmount: 20000n, totalClaimed: 20000n }] } });
  const claimResult = await submit("claim", { type: "claim", claims, claimAuthorizerSignature });
  if (claimResult.halted) return claimResult;
  const settleResult = await submit("settle", { type: "settle", receiver: requirements.payTo, token: requirements.asset });
  if (settleResult.halted) return settleResult;
  // Claims have already been reconciled, so this refund needs no additional claims.
  const refund = { type: "refund", channelConfig, voucher, amount: "10000" };
  const checked = await verify(refund);
  const refundNonce = checked.extra.refundNonce;
  const refundAuthorizerSignature = await receiverSigner.signTypedData({ domain,
    types: { Refund: [{ name: "channelId", type: "bytes32" },
      { name: "nonce", type: "uint256" }, { name: "amount", type: "uint128" }] },
    primaryType: "Refund", message: { channelId, nonce: BigInt(refundNonce), amount: 10000n } });
  await submit("refund", { ...refund, refundNonce, claims: [], refundAuthorizerSignature });
}

Batch validates requirements network, asset, payTo, positive amount within the configured cap, timeout and all supported extra fields; accepted must match these values. Claim, settle and refund retain these requirements as validation context. Their actual onchain amounts come from claims, receiver/token aggregate balance or refund.amount, not requirements.amount.

Mainnet exposes the operation contracts and envelope examples. The complete 0.03 USDC lifecycle construction is available on Testnet; it is hidden on Mainnet because this template cannot establish your deployed allowance or institutional signer.

Open Testnet lifecycle example

Responses and state

Batch verification returns isValid, payer and optional extra channel state. extra includes channelId, balance, totalClaimed, withdrawRequestedAt and refundNonce; it is a current-state read, not a funds reservation.

Read success and network before accepting the response. transaction identifies the onchain operation; payer and extra depend on operation. Submitting voucher to /settle returns HTTP 400 invalid_operation; use /verify for vouchers.

Idempotency-Key

Every Batch /settle requires Idempotency-Key: 8–128 letters, numbers or . _ : -. Reuse the same key and identical body for a retry; different content requires a new operation.

curl https://xapg.io/settle \
  -H "X-API-Key: xapg_inst_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: channel-abc-claim-0001" \
  --data-binary @batch-claim.json

Accumulation, limits and reconciliation

The merchant stores the latest voucher and accepted cumulative amount, locks each channel and deduplicates orders. /verify does not deduplicate service delivery; the merchant chooses when to claim.

Limits: 1–100 claims; maxTimeoutSeconds 1–3600; withdrawDelay 900–2592000 seconds. Payment and deposit ceilings follow server configuration. Deposit must cover requirements.amount and optional minDeposit.

Save the request, Idempotency-Key, channelId, voucher ceiling and transaction hash. Reconcile channel state and USDC movements before advancing the order; see Retry policy for unknown outcomes.

Exact + Batch · POST /verify

Validates Exact authorizations or Batch deposit, voucher and refund payloads without submitting a transaction. Requires verify scope.

{
  "isValid": true,
  "payer": "0x..."
}

Require HTTP 200 and isValid:true. Check payer when returned; verification does not authorize business approval or reserve funds.

Exact + Batch · POST /settle

Submit the same payment body that passed /verify.

Submit a deposit, claim, settle or refund operation with its required signatures and Idempotency-Key.

Requires settle scope and institutional approval.

{
  "success": true,
  "network": "eip155:CHAIN_ID",
  "payer": "0x...",
  "transaction": "0x..."
}

Require success:true and the expected network. Save transaction and reconcile the successful receipt and USDC movement.

Exact + Batch · errors

Payment failures may include failure. Use code for handling, settlementStatus for reconciliation and requestId for support. Authentication and rate-limit errors use a separate error response.

{
  "failure": {
    "code": "invalid_signature",
    "stage": "authorization_validation",
    "message": "The wallet signature could not be recovered or validated.",
    "retryable": false,
    "settlementStatus": "not_submitted",
    "requestId": "..."
  }
}

For /verify, handler failures use not_submitted. /settle may return failed before transaction submission; use the transaction hash and chain receipt to establish the outcome. Batch wrapper errors use verification_failed or settlement_failed; invalid_batch_settlement_evm_* identifies SDK-returned validation errors.

Authentication errors retain error as a string; errorDetail.code and requestId may be provided. HTTP 429 includes Retry-After. These are transport/authentication responses, not payment failure envelopes. Do not infer settlement submission from an authentication error or retryable flag.

Authentication and rate limiting

Institution limits for /verify and /settle are configured by the administrator. Settlement queries (/settlements/:requestId and /settlements/pending) follow the institution’s /settle limit with a separate shared query counter; polling does not consume the submission quota. When that limit is disabled, neither settlement submissions nor queries have an application request limit. RPC provider limits still apply.

HTTP 401
{ "error": "environment_mismatch",
  "errorDetail": { "code": "environment_mismatch" },
  "requestId": "<request UUID>" }

HTTP 403
{ "error": "facilitator_scope_not_authorized",
  "errorDetail": { "code": "facilitator_scope_not_authorized" },
  "requestId": "<request UUID>", "requiredScope": "settle" }

HTTP 429
Retry-After: <seconds>
{ "error": "rate_limit_exceeded",
  "errorDetail": { "code": "rate_limit_exceeded" },
  "requestId": "<request UUID>" }

Institution keys must be bound to the selected environment. environment_mismatch rejects a key for another environment; institution_key_environment_unbound rejects an unbound legacy key. Reissue legacy keys with an explicit environment before migration; existing unbound keys will stop authenticating. Retry-After is provided for HTTP 429; do not assume this header on other errors.

settlement_provider_unavailable is missing deployment capability and needs operator configuration. rpc_unavailable is a transient RPC failure. Retry reads with backoff; for settlement, reconcile the original operation before any retry.

HTTP 401/403: check credentials, scope and browser CSRF. HTTP 429: respect Retry-After when present. HTTP 200 may contain isValid:false or success:false.

Production & Security

Testnet
.env private key → viem signer

Production
Institution Backend
       ↓
HSM / MPC / KMS / Wallet Service
       ↓
EIP-712 Signature
       ↓
xAPG

node --env-file=.env scripts/institution-quickstart.mjs --settle --confirm-settlement BASE_SEPOLIA --out-dir payment-attempt-001

{
  "requestId": "<saved UUID>",
  "environment": "{{environment}}",
  "network": "{{network}}",
  "scheme": "exact",
  "status": "unknown",
  "createdAt": "<stored timestamp>",
  "updatedAt": "<stored timestamp>"
}

payer wallet → initiateWithdraw(originalChannelConfig, amount)
read pendingWithdrawals(channelId)
wait configured withdrawDelay from initiatedAt
payer wallet → finalizeWithdraw(originalChannelConfig)
confirm receipt and token balance

async function resumeDeposit(saved, { post, persist, reconcile }) {
  if (saved.stage !== "deposit") throw Error("Reconcile this operation first");
  const attempt = { ...saved, requestId: crypto.randomUUID() };
  await persist(attempt); // Keep the original request and Idempotency-Key.
  const result = await post("/settle", saved.request, {
    "Idempotency-Key": saved.idempotencyKey, "X-Request-ID": attempt.requestId
  });
  await persist({ ...attempt, result });
  if (!result.success) return { halted: true, result };
  await reconcile(saved.stage, saved.request, result);
  return result;
}

Compliance controls are separate from payment signature validation. This API does not perform payer/payTo sanctions screening, exchange Travel Rule data or file suspicious transaction reports. The institution controls pre-sign screening and required counterparty data; the institution and xAPG operator must each assess and document their own applicable reporting and service obligations before production.