# 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)