# AuthProof

> API auth for AI agents. Replaces reusable API keys with cryptographic, per-request signing using ERC-8128.

AuthProof is the API auth layer for AI agents. Instead of carrying a long-lived API key that can leak through logs, prompts, or tool configs, each agent gets a crypto wallet. Every HTTP request is signed with the wallet's private key, verified server-side, and protected against replay attacks. The private key never leaves the agent's environment.

## Autonomous agent onboarding (zero human touch)

An agent can discover, register, and start making signed requests without any human involvement:

```text
1. Discover projects     -> GET  /api/agents/discover
2. Self-register         -> POST /api/agents/request-access
3. Check approval status -> GET  /api/agents/request-access?walletAddress=0x...&projectId=...
4. Make signed requests  -> SDK  signedFetch()
```

Projects with `autoApprove: true` approve agents instantly on registration. Others require manual owner approval.

### Quick start (TypeScript)

```typescript
import { bootstrap } from "@authproof/sdk";

// With invite code (instant access)
const { client, privateKey } = await bootstrap({
  server: "https://agent-auth-mu.vercel.app",
  inviteCode: "sa_inv_a1b2c3d4",
  name: "my-agent"
});

// Or self-register (may require approval)
const res = await fetch("https://agent-auth-mu.vercel.app/api/agents/request-access", {
  method: "POST",
  headers: { "content-type": "application/json" },
  body: JSON.stringify({
    projectId: "clx...",
    walletAddress: "0x...",
    name: "my-agent"
  })
});
```

### Quick start (manual SDK usage)

```typescript
import { createAuthProofClient, privateKeyToWallet } from "@authproof/sdk";

const wallet = privateKeyToWallet(process.env.AGENT_PRIVATE_KEY);
const client = createAuthProofClient({ wallet });

await client.signedFetch("https://api.example.com/action", {
  method: "POST",
  headers: { "content-type": "application/json" },
  body: JSON.stringify({ query: "find top wallets" })
});
```

## MCP server

The `@authproof/mcp-server` package provides tools for Claude, Cursor, and other MCP clients:

- `discover_projects` - browse projects accepting agents
- `register_self` - self-register with a project
- `check_status` - poll registration approval
- `signed_fetch` - make ERC-8128 signed requests
- `paid_fetch` - signed request with automatic 402 payment handling (requires AUTHPROOF_RPC_URL)
- `get_wallet_info` - get wallet address and chain

## Key facts

- Protocol: ERC-8128 (HTTP Message Signatures, built on IETF RFC 9421)
- Private keys never leave the agent's environment and are never transmitted
- Each signature includes a one-time nonce and expires in 60 seconds
- Smart contract wallets supported via ERC-1271 fallback
- Supported chains: Ethereum, Base, Base Sepolia, Arbitrum, Optimism, Polygon

## Agent API endpoints (public, no session required)

| Method | Path | Description |
|---|---|---|
| GET | `/api/agents/discover` | List projects accepting agent registrations |
| POST | `/api/agents/request-access` | Self-register with a project |
| GET | `/api/agents/request-access?walletAddress=&projectId=` | Poll registration status |
| POST | `/api/agents/register` | Register with an invite code |
| GET | `/.well-known/authproof` | Agent onboarding metadata |
| GET | `/.well-known/authproof?project=<slug>` | Project-specific discovery |
| GET | `/.well-known/erc8128` | ERC-8128 signing parameters |
| GET | `/api/autonomous/pricing?projectId=` | Payment requirements (asset, amount, recipient) |
| POST | `/api/autonomous/payments/quote` | Create payment quote |
| POST | `/api/autonomous/payments/verify` | Verify on-chain payment |
| POST | `/api/demo/echo?projectId=` | Demo endpoint (ERC-8128 protected) |

## Management API (session or API key)

All management routes accept either a browser session (SIWE) or a `Bearer sa_key_...` API key in the Authorization header.

| Method | Path | Description |
|---|---|---|
| GET | `/api/projects` | List projects |
| POST | `/api/projects` | Create project |
| GET | `/api/projects/[id]/agents` | List agents |
| POST | `/api/projects/[id]/agents` | Create agent (returns private key once) |
| PATCH | `/api/projects/[id]/policies` | Update policies (incl. autoApproveAgents) |
| GET | `/api/projects/[id]/logs` | Request logs |
| POST | `/api/projects/[id]/invite` | Create invite code |
| POST | `/api/projects/[id]/api-keys` | Create management API key |
| POST | `/api/projects/[id]/agents/[agentId]/rotate` | Rotate agent signing key |
| POST | `/api/user/api-keys` | Create user-level API key (for project creation) |
| GET | `/api/billing/balance` | Check credit balance |
| POST | `/api/billing/purchase` | Purchase credit pack |

## Autonomous payments (402 flow)

When an agent's owner runs out of credits, the server returns `402 credits_exhausted` with payment instructions. The agent can pay on-chain with USDC to restore access — no human needed.

### How it works

```text
1. Agent makes signed request           -> 402 { quoteEndpoint, verifyEndpoint, projectId }
2. Agent requests quote                  -> POST /api/autonomous/payments/quote
3. Agent sends USDC on-chain (Base)      -> ERC-20 transfer to recipient in quote
4. Agent verifies payment                -> POST /api/autonomous/payments/verify
5. Agent retries original request        -> 200 (credits restored)
```

### SDK auto-pay (handles 402 automatically)

```typescript
import { createAuthProofClient, privateKeyToWallet, createAutoPayment } from "@authproof/sdk";

const wallet = privateKeyToWallet(process.env.AGENT_PRIVATE_KEY);
const client = createAuthProofClient({
  wallet,
  payment: {
    handler: createAutoPayment(process.env.AGENT_PRIVATE_KEY, "https://mainnet.base.org"),
    onPayment: (result) => console.log("Paid:", result.txHash)
  }
});

// This automatically handles 402 → pay → verify → retry
await client.signedFetch("https://api.example.com/action", { method: "POST" });
```

### MCP auto-pay

Set `AUTHPROOF_RPC_URL` to enable automatic payments. Use `paid_fetch` instead of `signed_fetch`:

```text
paid_fetch({ url: "https://api.example.com/action", method: "POST" })
```

### Payment API endpoints (public)

| Method | Path | Description |
|---|---|---|
| GET | `/api/autonomous/pricing?projectId=` | Current payment requirements (asset, amount, recipient) |
| POST | `/api/autonomous/payments/quote` | Create a payment quote (5-min TTL) |
| POST | `/api/autonomous/payments/verify` | Verify on-chain payment against quote |

### Payment details

- Asset: USDC on Base (chain ID 8453)
- Amount: configured per server (check `/api/autonomous/pricing`)
- Quote TTL: 5 minutes
- Receipts are single-use

## Credits

Usage-based pricing. Each verified request costs 1 credit. Free plan: 10k/mo. Builder: 100k/mo. Credit packs: 10k=$5, 50k=$20, 200k=$60.

Check balance: `GET /api/billing/balance` (returns `{ balance, plan, monthlyAllotment }`)
Purchase: `POST /api/billing/purchase` with `{ pack: "10k" | "50k" | "200k" }`
When credits run out: 402 `credits_exhausted` with payment instructions (see above)

## Key rotation

Agents can rotate their signing key without losing identity:
`POST /api/projects/[id]/agents/[agentId]/rotate` with `{ walletAddress: "0xNewAddress" }`

## Response headers

All ERC-8128 responses include `x-request-id` for debugging correlation.
429 responses include `Retry-After` (seconds).

## Links

- Docs: https://agent-auth-mu.vercel.app/docs
- Full context for LLMs: https://agent-auth-mu.vercel.app/llms-full.txt
- Agent integration spec: https://agent-auth-mu.vercel.app/agents.json
- Error reference: https://agent-auth-mu.vercel.app/docs/errors
- Agent discovery: https://agent-auth-mu.vercel.app/.well-known/authproof
- ERC-8128 discovery: https://agent-auth-mu.vercel.app/.well-known/erc8128