AgentWallet ·

The AgentWallet Protocol

Company → Principal → Agent. Identity → Mandate → Money. The AgentWallet Protocol is an open contract that stitches four open standards — MCP for tool calls, AP2 for signed mandates, x402 for HTTP-native payment, ACP for discoverable agent identity — into a single trace ID that survives every payment rail. The trace pulls fiat (Payouts.com on 17 rails), card (PCI-vaulted Visa/Mastercard) and USDC (Coinbase CDP on Base) into one row per payment, anchored on Base for replay-safe audit. Every dollar an autonomous agent moves is traceable from the IntentMandate that authorized it, through the policy gate that approved it, through the rail that executed it, all the way to the on-chain receipt that proves it. No proprietary lock-in, no closed mandates, no rail-specific reconciliation — just a clean separation of identity, authorization and execution that lets any LLM, any client and any merchant participate.

  • Three-tier identity model — Company is the KYB'd legal entity that owns the AgentWallet account; Principal is a KYC'd human with a WebAuthn passkey, accountable for an agent's actions; Agent is software identity (ACP Agent Card with DID and signed capability set) cryptographically bound to a Principal.
  • MCP (Model Context Protocol) — the open Anthropic standard for typed tool calls between an LLM and a service. Each agent's MCP endpoint exposes 14 typed tools (balance, charge, refund, payout, usdc.transfer, x402.pay, mandate.sign, trace.query, inbox.read and more) so the LLM can spend without knowing the underlying rail.
  • AP2 (Agent Payments Protocol) — the open Google-led standard for signed payment mandates. AgentWallet implements IntentMandate (what the user wants), CartMandate (the specific cart they approved) and PaymentMandate (the bound execution), each signed by the Principal's WebAuthn key and verifiable by any counterparty.
  • x402 — HTTP 402 Payment Required turned into a one-shot signed USDC settlement over EIP-3009. AgentWallet ships native client and server middleware so an agent can pay a paid API in a single round-trip with no wallet pop-ups, no gas, no two-step approvals.
  • ACP (Agent Card Protocol) — discoverable identity for autonomous software. Every AgentWallet agent publishes a signed Agent Card at a stable URL with its DID, public key, capability set, supported tools and the Principal binding so any counterparty can verify who they're transacting with.
  • Unified trace ID — one ULID per payment, written into the fiat ledger, the card authorization, the USDC settlement and the on-chain anchor. Filter the ledger by trace_id and you get a complete cross-rail view of one logical payment without joins.
  • Open on both sides — AgentWallet talks the protocol with any MCP client (Cursor, Claude Desktop, Devin, LangChain, OpenAI Agents SDK), any AP2 verifier, any x402-aware merchant. Nothing in the spec is AgentWallet-proprietary.
  • Replay-safe audit — every IntentMandate, CartMandate, PaymentMandate and execution receipt is content-addressable, signed and anchored. Disputes resolve against signed evidence, not screenshots.

Frequently asked questions

What is the AgentWallet Protocol?
An open four-layer contract for autonomous agent commerce. Identity (Company → Principal → Agent), Tool calls (MCP), Mandates (AP2: IntentMandate / CartMandate / PaymentMandate), and Settlement (x402 over EIP-3009 for USDC plus 17 fiat rails through Payouts.com and PCI-vaulted virtual cards). The four layers compose: an LLM calls an MCP tool, the call is authorized by a signed AP2 mandate, executed on the appropriate rail, and written into a single trace row anchored on Base.
Is the AgentWallet Protocol open?
Yes. MCP is an open Anthropic standard, AP2 is an open Google-led standard with a public working group, x402 is an open HTTP-native payments spec built on EIP-3009 (a USDC primitive), and ACP is an open agent-identity spec. AgentWallet implements all four; nothing in the contract is proprietary to us. Any LLM client, any verifier and any merchant can participate without integrating an AgentWallet SDK.
How does the protocol enforce human accountability?
Every Agent is cryptographically bound to a Principal (a KYC'd human with a WebAuthn passkey), and every spend mandate is signed by that Principal's key. The signing chain — Principal → IntentMandate → CartMandate → PaymentMandate → execution receipt — is preserved end-to-end and anchored on Base. Revoking a Principal pauses every agent they own atomically and marks every mandate they signed as revoked, while keeping the historical chain intact for audits.
What is an AP2 IntentMandate vs a CartMandate vs a PaymentMandate?
IntentMandate encodes what the user authorized in natural-language terms (e.g. "book a flight to NYC under $400 this week"), signed by the Principal once at authorization time. CartMandate is the specific cart the agent proposes — itemized lines, merchant, total — signed before execution and verifiable against the original IntentMandate. PaymentMandate is the bound execution: cart ID, exact amount, rail, idempotency key, counterparty, signed and ready to hand to the rail.
How is the trace ID generated and what does it cover?
One ULID per logical payment, allocated by AgentWallet at the moment a PaymentMandate is created. The same trace_id is written into the fiat ledger row (Payouts.com), the card authorization (if the rail is card), the USDC settlement row (Coinbase CDP), and the on-chain anchor on Base. Filter any of those four systems by trace_id and you get a complete cross-rail view of one payment — no joins, no reconciliation.
Does the protocol work with any LLM?
Yes. The MCP layer is vendor-neutral by design — the same per-agent MCP endpoint works with Anthropic Claude, OpenAI GPT, Google Gemini, xAI Grok, Cursor, Devin, LangChain, the OpenAI Agents SDK and any future MCP-compatible runtime. The 14 typed tools are the same regardless of which model is calling them, and the policy gate runs server-side so model choice has no impact on safety.
How does x402 fit into the protocol?
x402 is the protocol's machine-to-machine settlement primitive for paid APIs and agent-to-agent payments. When an agent calls a paid endpoint, the endpoint returns HTTP 402 Payment Required with a payment offer; the agent's x402 client signs an EIP-3009 transferWithAuthorization for USDC on Base and replays the request with the signed authorization in the X-PAYMENT header. Settlement is one round-trip, sub-3-second, gas-sponsored, and the receipt anchors into the unified trace.
Can I publish my own AP2-signed mandates that AgentWallet will accept?
Yes. AP2 is an open spec — any verifier can validate a mandate signed by a registered Principal's WebAuthn key against its public Agent Card. AgentWallet's mandate verifier follows the AP2 spec exactly, so mandates signed by a third-party signer compliant with AP2 are accepted by AgentWallet rails (and vice versa).
What's anchored on-chain and why?
Every PaymentMandate hash and execution-receipt hash is anchored on Base — not the full payload, just a content-addressable Merkle leaf — so a counterparty can later prove (in court, in a dispute, in an audit) that a specific mandate was signed at a specific time and that a specific receipt corresponds to it. The full payloads stay in Postgres; the on-chain anchor is a tiny, cheap, censorship-resistant proof-of-existence layer.
How does the agent reputation score work?
Every Agent has a public 0–1000 score that decays without activity and grows with clean settled volume. The score is derived from eight signals: cumulative settled volume in USD-equivalent over 90 days (max +250), successful-settlement / proposed-mandate ratio (max +200), disputes and chargebacks over a rolling 180 days (max −300), mandate revocations and fraud flags (max −250), the parent Principal's KYB tier (max +150), agent age in days since identity issuance (max +100), policy compliance — declared vs actual spend pattern — (max +150), and inactivity decay of −2 per day with no settled volume in the last 30 days. The score is published as an ERC-1155 metadata field on the Agent's optional identity NFT and exposed as an MCP tool — agentwallet.score(agent_id) → { score, tier, last_updated, anchor_tx } — so counterparties can require a minimum score for an Agent to call their service, just like a card network checks a BIN.
Which ERC standards does the protocol interop with?
Eight, each mapped to a specific primitive in the Mandate → Policy → Rail pipeline. ERC-20 for USDC, EURC, USDT and 50+ stablecoin balances (the crypto wallet itself, x402 settlement). ERC-721 for unique identity NFTs per Agent (optional cross-platform portability, score-metadata anchor). ERC-1155 for multi-token bundles of capability grants, licenses and credentials plus historical score snapshots. EIP-712 for typed-data signing — every AP2 mandate and policy decision uses human-readable signatures. EIP-2612 for ERC-20 permit (no separate approve transaction, gas-efficient stablecoin spends). EIP-3009 for transferWithAuthorization — the signed-transfer-over-HTTP primitive that x402 settlement is built on. ERC-4337 for account abstraction, gas sponsorship and batched ops. ERC-5267 for EIP-712 domain discovery so any cross-platform verifier can validate AgentWallet mandates without a hard-coded domain.
What's the difference between AP2, ACP and MCP?
Three orthogonal layers of the same protocol stack. MCP (Model Context Protocol, Anthropic) is the typed tool-call interface — how the LLM expresses intent to a service. ACP (Agent Card Protocol) is the discoverable identity layer — every agent publishes a signed Agent Card at /.well-known/agent.json with its DID, public keys, supported capabilities and Principal binding so any counterparty can verify who they're transacting with. AP2 (Agent Payments Protocol, Google-led) is the mandate layer — cryptographic authorization for what the agent is allowed to spend, in the form of a chained IntentMandate → CartMandate → PaymentMandate signed by the Principal's WebAuthn key. They compose: an LLM uses MCP to call a tool, ACP to discover the counterparty, and AP2 to prove the spend was authorized, then x402 (or a fiat rail) to actually settle.
What's the six-verb programming model the protocol exposes?
Same six verbs at every identity tier, exposed identically as MCP tools, REST endpoints and TypeScript SDK methods. (1) Identity: company.create / company.principal.create / principal.agent.create returns the (company_id, principal_id, agent_id) tuple plus the agent's pak_… key and MCP URL. (2) Mandate: principal.mandate.intent signs an IntentMandate with the Principal's WebAuthn key; agent.mandate.cart proposes a cart (requires Principal sig if over cap); agent.mandate.payment binds the cart to a rail. (3) Policy: policy.evaluate returns {decision:'allow'|'deny'|'escalate', rule, cap_consumed}; policy.upsert sets rules at company / principal / agent scope. (4) Rail: rail.dispatch is the only verb that touches money — returns {rail, settlement_ref, trace_id, state}. (5) Trace: trace.get returns the full audit object; trace.list filters by agent, principal, company, time window. (6) Score: agent.score is read-only public — counterparties query it before accepting a 402, just like a card network checks a BIN.