# AgentWallet — Agent Guide

> AgentWallet is the financial identity layer for autonomous AI agents. Every
> agent gets a fiat wallet, a virtual Mastercard, a USDC wallet on Base, an MCP
> endpoint, an AP2-signed principal, a real email/phone/WhatsApp inbox, and
> policy guardrails.

This file is for **autonomous agents and their developers**. It points at the
machine-readable surfaces you need to discover, authenticate, and call
AgentWallet without a human in the loop.

- Base URL: `https://agentwallet.ai`
- API base: `https://agentwallet.ai/api`
- Status: production

## Discovery endpoints

| Purpose | URL |
| --- | --- |
| OpenAPI 3.1 spec | `https://agentwallet.ai/openapi.json` |
| Agent skills (tools + input schemas) | `https://agentwallet.ai/.well-known/agent-skills` |
| Agent manifest (A2A) | `https://agentwallet.ai/.well-known/agent.json` |
| MCP manifest | `https://agentwallet.ai/.well-known/mcp.json` |
| MCP server card | `https://agentwallet.ai/.well-known/mcp/server-card.json` |
| OAuth Authorization Server metadata | `https://agentwallet.ai/.well-known/oauth-authorization-server` |
| OAuth Protected Resource metadata (RFC 9728) | `https://agentwallet.ai/.well-known/oauth-protected-resource` |
| UCP discovery profile | `https://agentwallet.ai/.well-known/ucp` |
| AP2 signing keys (JWKS) | `https://agentwallet.ai/.well-known/ap2-keys.json` |
| Long-form context for LLMs | `https://agentwallet.ai/llms-full.txt` |

## MCP

- Endpoint: `https://agentwallet.ai/mcp/agent` (streamable HTTP)
- Auth: OAuth 2.1 + PKCE (S256) with Dynamic Client Registration, or a
  `pak_…` API key as a bearer token.
- Discover tools without a handshake at `/.well-known/agent-skills`.

## Authentication

Machine agents authenticate in one of two ways:

1. **API key** — send a `pak_…` key as `Authorization: Bearer pak_…` (or
   `x-api-key: pak_…`).
2. **OAuth 2.1 + PKCE** — discover endpoints at
   `/.well-known/oauth-authorization-server`; anonymous Dynamic Client
   Registration is supported at `/oauth/register`.

## Quickstart

```bash
# 1. Read the machine-readable capability set
curl https://agentwallet.ai/.well-known/agent-skills

# 2. Read the full API contract
curl https://agentwallet.ai/openapi.json

# 3. Call the API with your key (example: list payout rails)
curl https://agentwallet.ai/api/catalog/payouts \
  -H "Authorization: Bearer pak_your_key"
```

Unknown API paths return an RFC 7807 `application/problem+json` error, so your
error handling can rely on structured JSON.

## Capabilities

Wallets, virtual cards, USDC on Base, payout execution across 17 rails,
AP2 mandates (IntentMandate / CartMandate / PaymentMandate), x402 (HTTP 402
over EIP-3009 USDC), ACP (Shared Payment Tokens), UCP payment handlers,
browser-based shopping, and per-agent spending policies with approval queues.

## Webhooks

AgentWallet sends signed outbound webhooks for account events. Each delivery is
signed with an HMAC-SHA256 signature over the raw body; verify it against your
endpoint secret before trusting the payload. Configure endpoints and see the
event catalog in the documentation.

## More

- Developers: `https://agentwallet.ai/developers`
- Documentation: `https://agentwallet.ai/docs`