p402-protocol

P402 Protocol

      

AI payment router. Route across 300+ models, settle per request in USDC on Base or USDC.e on Tempo.

P402 sits between your AI application and every LLM provider. It handles intelligent multi-provider routing (cost / quality / speed / balanced), on-chain micropayment settlement via the x402 protocol and mppx on Base and Tempo, and spending guardrails for autonomous agents.

---

Why P402

| Problem | P402 Solution | |---|---| | Hardcoded to one AI provider | Route across 300+ models automatically | | $0.30 payment fees kill micropayments | USDC on Base: fractions of a cent per settlement | | No spending limits for AI agents | Session budgets + AP2 mandate governance | | Fragmented provider APIs | One OpenAI-compatible endpoint | | No visibility into AI costs | Real-time analytics + optimization suggestions |

---

Quick Start (VS Code / Cursor / Windsurf)

Install the extension — the MCP server is embedded, tools appear in Copilot agent mode immediately, no config files required:

ext install p402-protocol.p402

Then run P402: Configure API Key from the command palette.

→ VS Code Marketplace · Open VSX

---

Quick Start (Claude Desktop / any MCP client)

{
  "mcpServers": {
    "p402": {
      "command": "npx",
      "args": ["-y", "@p402/mcp-server"],
      "env": { "P402_API_KEY": "p402_live_..." }
    }
  }
}

→ MCP docs · MCP Registry

---

Quick Start (SDK)

npm install @p402/sdk

import P402Client from '@p402/sdk';

const p402 = new P402Client({ apiKey: process.env.P402_API_KEY });

// Drop-in OpenAI replacement — P402 picks the best provider
const response = await p402.chat({
  messages: [{ role: 'user', content: 'Explain x402 payments in one sentence.' }],
  p402: { mode: 'cost' }   // cost | quality | speed | balanced
});

console.log(response.choices[0].message.content);
// p402_metadata: { provider: 'deepseek', cost_usd: 0.00031, latency_ms: 412 }

---

Quick Start (CLI)

# Authenticate once
npx p402 login

# Chat using the cheapest provider
npx p402 chat "What is x402?" --mode cost

# Check facilitator health
npx p402 health

---

Routing Modes

| Mode | Optimizes For | Typical Provider | |---|---|---| | cost | Lowest price | DeepSeek V3, Haiku 4.5, GPT-4o-mini | | quality | Best output | Claude Opus 4.6, GPT-5, Gemini 3 Pro | | speed | Lowest latency | Groq LPU, Flash models | | balanced | Equal weight (default) | Sonnet 4.6, GPT-4o, Gemini Flash |

---

Session Budgets

Enforce hard spending caps for autonomous agents:

// Create a $10 session — agent cannot spend a cent more
const session = await p402.createSession({ budget_usd: 10 });

// All chat requests are deducted from the session
const response = await p402.chat({
  messages,
  p402: { session_id: session.id, mode: 'cost' }
});

// Check remaining budget
const { budget } = await p402.getSession(session.id);
console.log(`$${budget.remaining_usd} remaining`);

---

x402 Payments

x402 is a machine-native payment protocol using HTTP 402. AI agents pay for resources using gasless EIP-3009 USDC transfers on Base L2.

Client → signs EIP-3009 authorization
       → POST /api/v1/facilitator/verify
       → POST /api/v1/facilitator/settle
Facilitator → executes transferWithAuthorization
            → pays gas (user pays zero gas)
            → returns { success, txHash, receipt }

Network: Base Mainnet (Chain ID: 8453) · Asset: USDC 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913

→ x402 payments guide

---

A2A Protocol

P402 implements the Google A2A spec over JSON-RPC 2.0. Agents communicate through structured tasks, discover capabilities via /.well-known/agent.json, and settle payments via the x402 extension.

// Discover P402's capabilities
GET https://p402.io/.well-known/agent.json

// Submit a task
POST https://p402.io/api/a2a
{ "jsonrpc": "2.0", "method": "tasks/send", "params": { ... } }

→ A2A protocol guide

---

Packages

| Package | Description | Version | |---|---|---| | @p402/sdk | TypeScript SDK — P402Client, types, EIP-712 mandate helpers |  | | @p402/cli | CLI tool — login, chat, sessions, mandates, analytics |  | | @p402/mcp-server | stdio MCP server — 6 tools over Model Context Protocol |  | | @p402/mpp-method | mppx payment methods — Base EIP-3009 and Tempo TIP-20 multi-rail settlement |  | | p402 VS Code extension | Embedded MCP server for VS Code, Cursor, and Windsurf — zero config |  |

---

Examples

| Example | What It Shows | |---|---| | 01-quickstart | Login → chat → view spend in ~20 lines | | 02-openai-migration | Drop-in OpenAI SDK replacement | | 03-nextjs-session-budget | Budget-capped AI in a Next.js App Router project | | 04-a2a-agents | Two agents communicating with x402 payment gate |

---

Docs

| Guide | | |---|---| | Getting Started | Account, API key, first request | | Authentication | API keys, env vars, security | | Routing Guide | Modes, scoring, providers, models | | x402 Payments | EIP-3009, wire format, settlement | | Sessions | Session lifecycle + budget enforcement | | A2A Protocol | JSON-RPC, mandates, Bazaar | | CLI Reference | Full CLI command reference | | OpenAPI Spec | Machine-readable API schema |

---

Community

• Dashboard: p402.io/dashboard
• Docs: p402.io/docs
• Issues: GitHub Issues
• Security: See SECURITY.md for responsible disclosure
• Contributing: See CONTRIBUTING.md

---

License

MIT © P402 Protocol