AgentWallet ·

Build agents that actually transact

MCP, AP2, x402 and ACP wired into one TypeScript-first SDK. A per-agent MCP server scoped to one row in agent_identities with ~15 typed tools. AP2 over JWS for cryptographically provable agent intent (ES256-signed IntentMandate → CartMandate → PaymentMandate chain). x402 over EIP-3009 for one-round-trip USDC settlement on Base. Shared Payment Tokens for card-rail merchants, PCI-vaulted card-token aliases for everyone else. Every protocol an autonomous agent needs, wired into one Express process and one ledger, with sandbox keys in 30 seconds and full feature parity to production. Drop the URL and pak_… key into any MCP-compatible client — frontier LLM, coding agent, open-source model, your own host — and the agent is online: wallet, card, channels, AP2 signing, x402, all surfaced as tools, all gated by the same velocity caps.

  • Per-agent MCP endpoint at /mcp/agent, scoped to one agent_identities.id, authenticated by a pak_… bearer key. Auto-advertises its tool catalog via JSON-RPC tools/list — drop the URL into ~/.config/mcp.json and any MCP-compatible client picks it up.
  • ~15 typed tools per agent: wallet.status (computed balance + holds + headroom), wallet.send_payment (fiat payout via available rail, limit-gated), wallet.send_usdc (USDC transfer on Base via CDP, limit-gated), wallet.x402_pay (sign EIP-3009 auth for x402 endpoint, limit-gated), wallet.list_activity, wallet.request_approval, card.details (last4 + balance, no PAN), card.recent_authorizations, comms.send_sms, comms.send_email, comms.list_inbox, identity.who_am_i (metadata + AP2 public key), identity.sign_mandate (ES256 sign an AP2 IntentMandate), identity.discover (resolve another agent via /.well-known), approvals.poll.
  • AP2 mandate chain — Intent → Cart → Payment, all ES256-signed JWS. IntentMandate signed by the Principal. CartMandate signed by the agent under that intent. PaymentMandate signed by the agent under that cart. Every signature is verified against the agent's published JWK and audited into ap2_mandate_audit.
  • JWS structure: alg pinned to ES256, kid bound to the agent's key ID, iss as did:agentwallet:ag_…, sub as the counterparty handle, jti as a UUIDv7 (replay-protected via unique index on (jti, action='execute')), exp short (IntentMandate 24h, CartMandate 1h, PaymentMandate 1h), clockTolerance capped at 30s.
  • Inbound verification flow — resolve issuer via /.well-known/agent.json on the agent's domain → jwtVerify with strict algorithms:['ES256'] → verify CartMandate references existing IntentMandate, PaymentMandate references existing Cart, all unexpired → verify cart total ≤ intent cap and merchant in intent allowlist → audit row → hand verified PaymentMandate to the rail processor.
  • x402 over EIP-3009 round trip — merchant returns HTTP 402 Payment Required with {x402: {amount, currency, network:'base', recipient, validBefore}} → agent's CDP-managed key signs an EIP-3009 transferWithAuthorization → agent replays request with X-PAYMENT header containing the signed authorization → merchant validates and settles → unified trace row written. Sub-3-second end-to-end on Base.
  • Shared Payment Tokens (SPT) — for card-rail merchants that accept network-issued single-use tokens. Request an SPT scoped to one merchant + one amount + 300s expiry. Persist (agent_identity_id, token_id, cart_mandate_id, amount_cents) into acp_spt_issuances. Replay is structurally impossible (single-use enforced at issuer).
  • PCI-vaulted card tokens — for merchants without modern token APIs. The agent gets a vault-tokenized card alias; the outbound proxy substitutes back to a real PAN at the network edge. The agent never sees the PAN; the application server never holds it.
  • Discovery via /.well-known/agent.json — every agent publishes a discovery document with agent_id (did:agentwallet:ag_…), public_keys (ES256 JWK), endpoints (ap2_inbound, a2a), accepts (x402_usdc_base, spt, ach…), and optional erc8004 (chainId, tokenId) for on-chain identity. Other agents resolve it to verify mandates and learn capabilities.
  • Three-cap velocity gate — every wallet action evaluates per-transaction → daily (rolling 24h) → monthly (rolling 30d) in that order. If any cap is exceeded, the action enters the approval queue and the Principal is notified via SMS/email/widget. Force-approve override exists for admin-permitted operators (double-logged into agent_identity_activity_log + admin_audit_log).
  • Agent Portal API — Principal-scoped routes under /api/agent-portal, gated by verifyAgentAccess middleware (Principal session cookie + agentId linked in agent_principal_links with sufficient role). Magic-link OTP auth (no passwords). 30-day sliding sessions, silently rotated on each request.
  • Webhook signing — outbound events signed with X-Payouts-Signature: t=…,v1=hex over the JSON body keyed by per-endpoint secret. Stripe-compatible scheme. Retry with exponential backoff (30 s → 1 h cap) for up to 8 attempts, then dead-letter. Every attempt auditable in the dashboard with full request/response capture.
  • Idempotency — every write accepts an Idempotency-Key header; we de-dupe by (account_id, key) for 24 hours and replay the original response on retry. Payouts also dedupe upstream via Payouts.com idempotency keys. Replays return replayed:true so you can distinguish a retry from a new write.
  • Sandbox keys with full feature parity — fund, charge, refund, USDC transfer, mandate signing, MCP, virtual cards, all instant and resettable. No real money, no real KYB required for development. The same API surface, the same tool catalog, the same AP2 chain as production.
  • Bootstrap an MCP client in seconds — add to ~/.config/mcp.json: {"mcpServers":{"agentwallet":{"url":"https://api.agentwallet.ai/mcp/agent","headers":{"Authorization":"Bearer pak_live_a1f9c2…"}}}}. Restart your MCP host. The tool catalog appears automatically.

Frequently asked questions

How do I add payments to my AI agent?
Two paths. (1) MCP — drop the per-agent MCP URL into Cursor, Claude Desktop, Devin or LangChain and the LLM gets 14 typed tools (charge, payout, usdc.transfer, x402.pay, mandate.sign…). (2) REST — call our TypeScript SDK directly from your agent runtime. Both paths share the same policy gate, idempotency and trace ID.
What languages does the SDK support?
TypeScript / JavaScript is first-class with strongly-typed clients generated from our OpenAPI spec. Any language can hit the REST API; the OpenAPI spec at /docs/openapi.yaml lets you generate idiomatic clients for Python, Go, Rust, Java, etc.
How do I get a sandbox key?
Sign up at /sign-up, click 'create sandbox', and you have a full-feature parity sandbox in 30 seconds — fund, charge, refund, USDC, mandates, MCP, virtual cards, all instant, all reset-able. No real money, no real KYB required to develop against.
How do I integrate AgentWallet with Cursor or Claude Desktop?
In Cursor or Claude Desktop, add an MCP server with the per-agent URL we issue at /agents/:id/mcp. The 14 typed tools appear automatically in the LLM's tool catalog. No SDK install, no auth dance — the URL itself is the credential.
Does AgentWallet work with LangChain and the OpenAI Agents SDK?
Yes. The MCP endpoint plugs into LangChain via the langchain-mcp adapter; for the OpenAI Agents SDK we ship a typed wrapper that exposes our tools through the SDK's Tool interface. Same trace ID and policy gate behind both.
How are webhooks signed?
Outbound webhooks are signed with X-Payouts-Signature: t=…,v1=hex (Stripe-compatible scheme) keyed by your per-endpoint secret. We retry with exponential backoff (30 s → 1 h cap) for up to 8 attempts, then dead-letter — every attempt is auditable in the dashboard.
Is there an idempotency model?
Yes. Every write accepts an Idempotency-Key header; we de-dupe by (account_id, key) for 24 hours and replay the original response on retry. Payouts also dedupe upstream via Payouts.com idempotency.
What does an AP2 JWS actually look like under the hood?
A compact JWS with alg pinned to ES256 (alg:none and HS-confusion are structurally rejected by strict algorithms:['ES256'] in jwtVerify), kid bound to the agent's published key ID, iss as did:agentwallet:ag_…, sub as the counterparty handle, jti as a UUIDv7 (replay-protected via a unique index on (jti, action='execute')), and exp short — IntentMandate 24 h, CartMandate 1 h, PaymentMandate 1 h — with clockTolerance capped at 30 s. The inbound verification flow resolves the issuer via /.well-known/agent.json on the agent's domain, jwtVerifies with the strict alg list, verifies that the CartMandate references an existing IntentMandate and the PaymentMandate references an existing Cart, checks all are unexpired, verifies the cart total is ≤ the intent cap and the merchant is in the intent allowlist, writes an audit row to ap2_mandate_audit, and only then hands the verified PaymentMandate to the rail processor.
How do x402 round trips work end-to-end?
Four steps, sub-3-seconds on Base. (1) The agent's HTTP client hits a paid endpoint and gets back HTTP 402 Payment Required with {x402:{amount, currency, network:'base', recipient, validBefore}}. (2) The agent's CDP-managed key (custodied inside a Trusted Execution Environment) signs an EIP-3009 transferWithAuthorization for the offered amount. (3) The agent replays the original request with an X-PAYMENT header containing the signed authorization. (4) The merchant validates the signature, submits the auth on Base, and returns the actual response payload. Gas is sponsored by AgentWallet (capped per agent), the settlement writes a unified trace row identical in shape to a fiat or card row, and the inbound webhook handler reverses spend if the on-chain auth ever fails or is double-spent.
How does an agent discover another agent?
Via /.well-known/agent.json — the ACP discovery document at the agent's stable URL. The document includes agent_id (did:agentwallet:ag_…), public_keys (ES256 JWK so the consumer can verify any AP2 mandate signed by this agent), endpoints (ap2_inbound for receiving mandates, a2a for direct agent-to-agent messaging), accepts (the rail set the agent will settle on — x402_usdc_base, spt, ach, etc.), and optionally erc8004 (chainId + tokenId) if the agent has minted an on-chain identity. The identity.discover MCP tool wraps this resolution: call it with another agent's handle and get back a verified, schema-validated discovery document plus a freshness timestamp.
What about Shared Payment Tokens and PCI-vaulted card tokens?
Two card-rail equivalents to x402, used when the counterparty is a card-accepting merchant rather than an HTTP-native agent. SPTs (Stripe Shared Payment Tokens) are single-use, merchant-scoped, amount-bound tokens with a ~300 s expiry — request one scoped to one merchant + one amount, persist (agent_identity_id, token_id, cart_mandate_id, amount_cents) into acp_spt_issuances, present at checkout. Replay is structurally impossible (single-use enforced at issuer). For merchants without modern token APIs, the agent gets a vault-tokenized card alias (tok_card_…) that the outbound PCI proxy substitutes back to a real PAN at the network edge — the agent never sees the PAN, the application server never holds it, and the substitution is logged into the trace ledger.