@curless/agentbank-protocols

Agent-runtime client helpers for the agent-commerce protocols agentbank supports. One package, one subpath per protocol — import only what you actually use, no forced heavy deps.

Pair with @curless/agentbank-sdk on the agent's backend (API calls) and @curless/agentbank-merchant-sdk on the merchant's backend.

Subpaths

| Subpath | What it does | Extra dep | |---|---|---| | /x402 | Sign EIP-3009 transferWithAuthorization + auto-retry 402 with X-PAYMENT (USDC on Base/EVM); usdcBalance, USDC_EIP712_DOMAIN. | viem (peer, optional); @coinbase/cdp-sdk (peer, optional — only for cdpAccountSigner) | | /xrpl | Pay RLUSD over the XRP Ledger: payXrplWithFetch (auto-retry a 402 with an X-PAYMENT) + X-PAYMENT encode/decode. | xrpl (peer, optional) | | /solana | Sign a Solana USDC x402 payment: signSolanaX402Payment, secretKeyFromString, addressFromSecretKey. | x402 and @solana/kit (peers, optional — both needed to sign: the x402 SVM client builds the transfer, the kit signs it) | | /tempo | Pay an MPP · Tempo HTTP-402 challenge on-chain: payMppTempoChallenge (broadcasts transferWithMemo, returns the Payment credential) + parseMppChallenge, decodeMppRequest, tempoAddressFromKey. | viem (peer, optional) | | /ap2 | Real ES256 JWS signing for AP2 mandates: signPaymentMandate (bound to a cart) + signIntentMandate (a standing spend authorization). Embedded-JWK, Web Crypto, no deps. | — | | /acp | Read a merchant-quoted checkout session and complete it with a delegated credential: readCheckoutSession, totalOf, completeCheckout, purchaseOf (first line) and linesOf (every line — use it for a cart). | — | | /uaag | UnionPay Agent Pay, agent side, in three calls: createIntent → checkout (a URL the cardholder opens) → checkoutState (has the credential actually arrived? — stopping at checkout stops before anything is authorised). startUaagCheckoutForLines does the first two for a whole order (every line, ≤10 items — UnionPay's limit, refused before anything is sent; a refusal carries step). Takes no card data and never names a buyer — card binding lives in the buyer's own wallet (@curless/agentbank-sdk). ⚠️ checkout returns a credential the merchant charges: the gateway is not in that settlement path. | — |

/x402 quick start

npm i @curless/agentbank-protocols viem

import { payWithFetch, signerFromPrivateKey } from '@curless/agentbank-protocols/x402';

// async — viem loads lazily on first signing use
const signer = await signerFromPrivateKey(process.env.AGENT_PRIVATE_KEY as `0x${string}`);

// Auto-handle 402 → sign → retry. Just replace your fetch().
const res = await payWithFetch(
  'https://shop.example/api/buy/latte',
  { method: 'POST', body: JSON.stringify({ qty: 1 }) },
  { signer },
);
const order = await res.json();

signer is any viem LocalAccount-shaped object ({ address, signTypedData }), so an agent runtime can plug in an HSM or a Curless-managed wallet later without changing call sites.

Design

• viem is a peer-dependency, marked optional, loaded lazily. Only code paths that actually SIGN (signX402Payment / signerFromPrivateKey) touch it — importing /x402 just to encode/decode X-PAYMENT headers works without viem installed at all.
• Edge-safe: header encode/decode uses @curless/agentbank-core's portable base64 (no raw Buffer), so it runs on Workers / Deno.
• One subpath per protocol keeps imports and discovery clean. Adding a protocol = adding a sibling folder, not a new npm package.

History

This package supersedes an earlier internal agentbank-x402-client design (never published to npm). The x402 wire shapes and exported symbols are the same; the home is now @curless/agentbank-protocols/x402.