llms.txt
# P402.io
> AI infrastructure for payment processing, token metering, intelligent routing, distributed tracing, compliance auditing, and spend optimization. Production-grade. OpenAI-compatible. Settles micropayments on-chain.
P402 is the infrastructure layer that sits between AI applications and AI providers — the same way a payment network sits between merchants and banks. It handles routing, authorization, metering, settlement, and governance so your application makes one API call and P402 handles the rest.
---
## What P402 Does
**Payment Processing** — EIP-3009 gasless USDC settlement on Base L2. HTTP 402 becomes a machine-native payment primitive. Facilitators execute on-chain transfers; users pay zero gas.
**Token Metering** — Per-token AI billing tracked at request granularity. Every token counted, costed, and attributed to a department, project, or employee. Real-time dashboards. Budget enforcement. Overage alerts.
**Intelligent Routing** — 300+ models across 13 providers. Four routing modes: `cost`, `speed`, `quality`, `balanced`. Semantic cache cuts redundant LLM calls. Gemini-powered Protocol Economist optimizes routing decisions asynchronously.
**Distributed Tracing** — Every request traced end-to-end: model selected, provider latency, tokens used, cost incurred, cache hit/miss, routing decision, settlement result. SSE real-time trace viewer. Full audit trail in `traffic_events`.
**Compliance Auditing** — Immutable audit log for every AI interaction. Department attribution via `X-P402-Department`, `X-P402-Project`, `X-P402-Employee` headers. Proof-of-settlement receipts. HIPAA-ready audit trails for healthcare. Compliance bundles for legal. Verifiable spend records for finance.
**Spend Optimization** — AI-generated recommendations from Gemini Protocol Economist. Model mix analysis. Budget pacing (day-of-month projection). Semantic cache ROI. Provider cost comparisons. Enterprise dashboard with department budgets, top spenders, project breakdown.
---
## P402 Meter — Per-Token AI Billing
P402 Meter is the per-token billing system built on Tempo mainnet (chain 4217) using TIP-20 stablecoins (USDC.e, USDT0, cUSD, pathUSD, and 6 more).
**Key capabilities:**
- Per-request token counting with department/project/employee attribution
- Budget caps enforced in real time — requests blocked when budget exhausted
- On-chain settlement proofs (Tempo USDC.e, ERC-20 `transfer`)
- Full model mix analytics: which models each team is using and what it costs
- Semantic cache: identical or near-identical queries served from cache, cost = $0
- Enterprise dashboard: department budgets, top employees by spend, project breakdown, recent sessions, optimization findings
**Industry demos (live):**
- `/meter/healthcare` — HIPAA-grade audit trail, clinical AI compliance, department cost allocation
- `/meter/legal` — matter-level billing, privilege log, multi-jurisdictional routing, per-token invoicing
- `/meter/real-estate` — property-contextual AI, MLS enrichment, deal pipeline cost tracking
- `/meter/enterprise` — full CFO dashboard: department budgets, spend forecasting, model mix optimization
**Tempo chain details:**
- Chain ID: 4217 (CAIP-2: `eip155:4217`)
- No native gas token — gas paid in TIP-20 stablecoins via FeeAMM
- `eth_getCode` returns `0xef` for TIP-20 contracts (EIP-7702 delegation designator, not an error)
- Settlement uses standard ERC-20 `transfer(to, amount)` — never `msg.value`
---
## Privacy — P402 Meters Economics, Not Content
P402 does not need your prompts to make AI spend accountable. The product supports five privacy modes; the default is `metadata_only`. Customers control storage, redaction, and retention per scope.
**Privacy modes (V5 §27):**
- `metadata_only` — economic metadata only (owner, action, model, tokens, cost, governance, evidence status). NEVER stores prompt, response, files, documents, chat history, PHI, PII, secrets, or source code. **Default for enterprise.**
- `fingerprint_only` — adds HMAC fingerprints (keyed by tenant secret, never plain SHA-256) for duplicate / retry-loop detection. Still no raw content.
- `redacted_trace` — redacted prompt + response samples and trace summaries; customer runs redaction before sending. Tenant must enable `store_prompts` / `store_responses` for sample retention. Adds context, retry, and prompt-structure analysis to Optimize.
- `private_gateway` — P402 gateway runs inside customer VPC. P402 cloud receives aggregates and evidence hashes only. Strongest enterprise answer.
- `full_trace` — explicit opt-in only. Receives prompt, response, tool calls, full trace. Retention-bound, role-gated, audit-logged. Never the default.
**Widening rule:** admin-saved scope overrides in `privacy_scope_overrides` CAN widen the tenant default (e.g. tenant `metadata_only` + workflow `full_trace` for a debug surface). Per-request callers CANNOT widen — `privacy_mode` in a request body only ratchets tighter.
**Endpoints:**
- `POST /api/v2/meter/events` — meter-only event ingestion. Customer apps call the model provider directly, then POST the economic event here. The endpoint REJECTS any prompt / response / content / file / messages / chat_history / transcript / document field with INVALID_INPUT.
- `GET /api/v2/meter/events` — paged list with privacy / owner / model / evidence filters.
- `GET /api/v2/meter/events/{id}` — detail with full privacy posture (privacy_mode, prompt_stored, response_stored, redaction_applied, retention_expires_at, response_capture_status).
- `POST /api/v2/outcomes` — record what happened to a request (accepted / rejected / retried / escalated / human_reviewed / failed) plus optional quality_score.
- `GET/PUT /api/v2/privacy/settings` — tenant default. PUT is tenant-admin only.
- `GET/POST /api/v2/privacy/scope-overrides`, `DELETE /.../{id}` — per-scope overrides. POST / DELETE are tenant-admin only and audit who saved each row.
**Hosted routing privacy:** when a request flows through `/api/v2/chat/completions`, the writer resolves the same `tenant_privacy_settings` + scope overrides. Under `metadata_only` the prompt and response are not persisted regardless of what the body contained. Streaming responses stamp `response_capture_status: not_available_streaming` so audit cannot misread an empty payload as "policy denied storage."
**Evidence bundles:** the export (`/api/v1/analytics/evidence-bundle`) includes a `privacy` block (`mode`, `promptStored`, `responseStored`, `redactionApplied`, `retentionExpiresAt`, `responseCaptureStatus`, plus 16-hex fingerprint excerpts) so finance / procurement / compliance exports always show what posture governed the event.
---
## Core Routing
POST `/api/v2/chat/completions` — OpenAI-compatible. Drop-in replacement for the OpenAI SDK (change one URL). P402 selects the optimal provider, executes the request, settles payment, and logs telemetry.
```typescript
import OpenAI from 'openai';
const client = new OpenAI({
baseURL: 'https://p402.io/api/v2',
apiKey: process.env.P402_API_KEY,
});
const response = await client.chat.completions.create({
model: 'auto', // P402 picks the optimal model
messages: [{ role: 'user', content: 'Hello' }],
// P402 routing extensions (via extra_body):
// x_routing_mode: 'cost' // 'cost' | 'speed' | 'quality' | 'balanced'
// x_session_id: 'sess_...' // budget-capped session
});
```
**Enterprise attribution headers:**
```
X-P402-Department: Engineering
X-P402-Project: copilot-v2
X-P402-Employee: alice@company.com
```
These stamp every `traffic_events` row for analytics.
**Routing modes:**
- `cost` — cheapest model that meets quality threshold
- `speed` — lowest p95 latency, prioritizes fast providers
- `quality` — highest model capability score
- `balanced` — weighted composite (default)
---
## x402 Payment Protocol
x402 makes HTTP 402 "Payment Required" machine-native. A client signs an EIP-3009 `TransferWithAuthorization`, submits it with the request, and the facilitator executes the on-chain USDC transfer gaslessly.
**Wire format:**
```
Authorization: Payment <base64url(paymentPayload)>
```
**Settlement flow:**
1. `POST /api/v1/facilitator/verify` — validate signature, amount, nonce
2. `POST /api/v1/facilitator/settle` — execute `transferWithAuthorization` on USDC contract
3. Facilitator pays gas; user pays zero gas
**Key addresses (Base Mainnet, Chain ID 8453):**
- USDC: `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913`
- Treasury: `0xFa772434DCe6ED78831EbC9eeAcbDF42E2A031a6`
- P402Settlement: `0xd03c7ab9a84d86dbc171367168317d6ebe408601`
- SubscriptionFacilitator: `0xc64747651e977464af5bce98895ca6018a3e26d7`
**Security:** replay protection (nonces recorded), gas limit guard (rejects if Base gas > 50 gwei), expiry check, $0.01 minimum.
---
## Sessions & Budget Control
Sessions give AI agents bounded authority to spend within defined limits.
```typescript
// Create a budget-capped session
const session = await fetch('https://p402.io/api/v2/sessions', {
method: 'POST',
headers: { Authorization: `Bearer ${API_KEY}` },
body: JSON.stringify({
budget_usd: 5.00, // max spend
expires_in_seconds: 3600, // 1 hour
agent_id: 'my-agent',
})
}).then(r => r.json());
// Use session in requests
const client = new OpenAI({
baseURL: 'https://p402.io/api/v2',
apiKey: session.session_token,
});
```
Sessions enforce hard spend caps. Budget exceeded → `BillingGuard` blocks at middleware, returns 402 before touching any provider.
---
## AP2 Mandates — Bounded Agent Authority
AP2 mandates are user-signed spending authorizations that let AI agents spend on behalf of users within defined constraints. The governance layer on top of x402.
```typescript
// Issue a mandate
const mandate = await fetch('https://p402.io/api/a2a/mandates', {
method: 'POST',
body: JSON.stringify({
type: 'payment',
user_did: 'did:p402:user:0xABC...',
agent_did: 'did:p402:agent:analyst-v2',
constraints: {
max_amount_usd: 25.00,
allowed_categories: ['research', 'summarization'],
valid_until: '2026-12-31T23:59:59Z',
},
})
});
```
Constraints enforced: max budget, allowed categories, expiry. `MANDATE_BUDGET_EXCEEDED` blocks overspend. Each mandate tracks `amount_spent_usd` cumulatively.
---
## A2A Protocol — Agent-to-Agent Commerce
P402 implements the Google A2A JSON-RPC 2.0 protocol for agent-to-agent communication with x402 payment extension.
**JSON-RPC methods:**
- `tasks/send` — submit task to agent
- `tasks/get` — retrieve task status + artifacts
- `tasks/cancel` — cancel in-progress task
- `tasks/sendSubscribe` — submit + subscribe via SSE
**Discovery:**
- `GET /.well-known/agent.json` — P402's A2A agent card (capabilities, skills, endpoints, x402 extension)
- `GET /api/a2a/agents` — list all registered agents in Bazaar
**Payment extension URI:** `tag:x402.org,2025:x402-payment`
---
## Analytics & Observability Endpoints
```
GET /api/v2/analytics/spend — Detailed spend breakdown by model, provider, time
GET /api/v2/analytics/recommendations — Gemini-generated cost optimization suggestions
GET /api/v2/enterprise/analytics — Department/employee/project breakdown (enterprise)
GET /api/v2/enterprise/budgets — Department budget configuration
POST /api/v2/enterprise/budgets — Set department budget cap
GET /api/v2/sessions — List active sessions with spend
GET /api/v2/sessions/:id/stats — Real-time session metrics
GET /api/v1/analytics/spend — Time-series spend data
GET /api/v1/analytics/alerts — Budget alert history
GET /api/v1/analytics/decisions — Routing decision log
GET /api/v1/analytics/conversion — Conversion funnel metrics
```
---
## Intelligence Layer
Gemini-powered governance:
- **Protocol Economist** (`gemini-2.0-pro`) — deep ledger analysis, routing optimization, cost recommendations. Runs async after each batch.
- **Sentinel** (`gemini-2.0-flash`) — real-time anomaly detection. Flags unusual spend velocity, model abuse, credential anomalies.
Feature flags: `ENABLE_COST_INTELLIGENCE=true`, `ENABLE_SEMANTIC_CACHE=true`
---
## Semantic Cache
Cosine-similarity cache using `text-embedding-004`. Near-identical queries served from cache — no LLM call, no provider cost, sub-10ms response.
Cache hit rate typically 15–40% in production enterprise deployments. ROI shown in `/api/v2/analytics/recommendations`.
---
## ERC-8004 Trustless Agent Identity
On-chain agent identity and reputation on Base. Agents registered with a DID, validated on-chain before receiving tasks.
- Identity Registry (Base): `0x8004A169FB4a3325136EB29fA0ceB6D2e539a432`
- Reputation Registry (Base): `0x8004BAa17C55a88189AE136b182e5fdA19dE9b63`
---
## Docs
- [API Reference](https://p402.io/docs/api): Chat completions, sessions, providers, analytics, cache, x402
- [Routing Guide](https://p402.io/docs/router): Modes, scoring algorithm, failover
- [SDK Reference](https://p402.io/docs/sdk): TypeScript SDK, MCP server, CLI
- [A2A Protocol](https://p402.io/docs/a2a): JSON-RPC 2.0 with x402 payment extension, AP2 mandates
- [x402 Facilitator](https://p402.io/docs/facilitator): Deploy a facilitator, EIP-3009, USDC on Base
- [AP2 Mandates](https://p402.io/docs/mandates): Bounded spending authority for AI agents
- [MCP Server](https://p402.io/docs/mcp): Model Context Protocol integration for Claude and other agents
- [ERC-8004](https://p402.io/docs/erc8004): On-chain agent identity and reputation on Base
- [OpenAPI Spec](https://p402.io/openapi.yaml): Machine-readable full API specification
- [Whitepaper](https://p402.io/whitepaper.pdf): Protocol architecture and economics
- [Full Reference](https://p402.io/llms-full.txt): Complete technical reference
## Meter
- [P402 Meter](https://p402.io/meter): Per-token AI billing hub
- [Healthcare Demo](https://p402.io/meter/healthcare): HIPAA audit trail, clinical AI compliance
- [Legal Demo](https://p402.io/meter/legal): Matter billing, privilege log, per-token invoicing
- [Real Estate Demo](https://p402.io/meter/real-estate): Property-contextual AI, deal pipeline tracking
- [Enterprise Dashboard](https://p402.io/meter/enterprise): CFO dashboard, department budgets, optimization
## Claude Skill
- [Install Skill](https://p402.io/skill/p402.zip): `claude mcp install https://p402.io/skill/p402.zip`
- [SKILL.md](https://p402.io/skill/SKILL.md): Core routing guide, billing guard, migration patterns
- [Skill Documentation](https://p402.io/docs/skill): Full installation guide
## Discovery
- [Agent Card](https://p402.io/.well-known/agent.json): A2A-compliant agent discovery
- [p402.json](https://p402.io/.well-known/p402.json): x402 protocol governance config
## Source
- [GitHub](https://github.com/Z333Q/p402-router)
- [X / Twitter](https://x.com/p402io)
