P402 Logo
P402.io
Developer Reference

API Reference

Welcome to the P402 V2 API. Our platform provides a payment-aware orchestration layer, allowing you to route AI requests based on cost, quality, and reliability with zero code changes.

Authentication

All API requests must be authenticated using your P402 API Key. You can manage your keys in the Dashboard. Pass the key in the Authorization header for every request.

# Example Authorization Header
Authorization: Bearer p402_live_your_key_here
⚠️

Security Best PracticeNever expose your API key in client-side code (browsers, mobile apps). Always route requests through a secure backend service to keep your credentials safe.

POST/api/v1/facilitator/settle

Execute Settlement (EIP-3009)

Execute a gasless settlement on Base Mainnet by submitting a signed EIP-3009 authorization. P402 acts as the facilitator, paying the gas fees to settle the transaction on-chain.

Parameters

tenantIdstringRequired

The ID of the tenant receiving the funds.

decisionIdstringRequired

Trace ID for the decision/mandate being settled.

assetstring

The asset symbol (default: "USDC").

authorizationobjectRequired

The signed EIP-3009 authorization object containing { from, to, value, validAfter, validBefore, nonce, v, r, s }.

Example Request

curl https://p402.io/api/v1/facilitator/settle \
  -H "Content-Type: application/json" \
  -d '{
    "tenantId": "...",
    "decisionId": "trace_123",
    "asset": "USDC",
    "authorization": {
        "from": "0xUserAddress...",
        "to": "0xTreasuryAddress...",
        "value": "1000000",
        "validAfter": 0,
        "validBefore": 1735689600,
        "nonce": "0x...",
        "v": 27,
        "r": "0x...",
        "s": "0x..."
    }
  }'

Example Response

{
  "settled": true,
  "facilitatorId": "chain_base",
  "receipt": {
    "txHash": "0x88df01e...",
    "verifiedAmount": "1.0",
    "asset": "USDC",
    "timestamp": "2026-01-21T12:00:00Z"
  }
}
POST/api/v1/facilitator/verify

Verify Settlement

Verify an existing on-chain transaction was successful and matches the expected amount and recipient. Useful for client-initiated (non-gasless) settlements.

Parameters

txHashstringRequired

The transaction hash to verify.

amountstringRequired

Expected amount (decimal string).

recipientstringRequired

Expected recipient address (tenant treasury).

networkstring

Chain ID (default: eip155:8453).

Example Request

curl https://p402.io/api/v1/facilitator/verify \
  -H "Content-Type: application/json" \
  -d '{
    "txHash": "0x...",
    "amount": "1.0",
    "recipient": "0xTreasury..."
  }'

Example Response

{
  "success": true,
  "transaction": "0x...",
  "network": "eip155:8453",
  "settlement_id": "set_..."
}
POST/api/v2/chat/completions

Chat Completions

OpenAI-compatible endpoint for generating AI responses with P402 orchestration. Supports multi-provider routing, semantic caching, and real-time cost tracking.

Parameters

modelstring

The model to use. If omitted, P402 will select the optimal model based on your routing mode.

messagesarrayRequired

A list of messages comprising the conversation so far.

p402.modestring

Routing mode: "cost", "quality", "speed", or "balanced" (default).

p402.cacheboolean

Enable semantic caching to eliminate redundant API calls.

Example Request

curl https://p402.io/api/v2/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $P402_API_KEY" \
  -d '{
    "messages": [{"role": "user", "content": "Explain P402."}],
    "p402": { "mode": "cost", "cache": true }
  }'

Example Response

{
  "id": "chatcmpl-123",
  "choices": [
    {
      "message": {
        "content": "P402 is an AI orchestration layer..."
      }
    }
  ],
  "p402_metadata": {
    "provider": "anthropic",
    "cost_usd": 0.00045,
    "cached": false,
    "latency_ms": 840
  }
}
GET/api/v2/models

List Models

Dynamically retrieve all 300+ models accessible via the OpenRouter Meta-Provider, including real-time pricing, context windows, and model capabilities.

Example Request

curl https://p402.io/api/v2/models

Example Response

{
  "object": "list",
  "total": 339,
  "data": [
    {
      "id": "openai/gpt-4o",
      "name": "GPT-4o",
      "context_window": 128000,
      "pricing": {
        "prompt": "0.000005",
        "completion": "0.000015"
      }
    }
  ]
}
GET/api/v2/analytics/recommendations

Cost Recommendations

Get AI-powered cost optimization suggestions based on your historical usage patterns.

Example Request

curl https://p402.io/api/v2/analytics/recommendations

Example Response

{
  "recommendations": [
    {
      "type": "model_switch",
      "title": "Switch to Haiku",
      "saved_monthly": 245
    }
  ]
}
POST/api/a2a

Submit x402 Payment

Submit cryptographic proof of payment (EIP-3009 signature or transaction hash) for an A2A task. Mandatory step in the A2A x402 Extension 3-message flow.

Parameters

payment_idstringRequired

The unique payment identifier provided in the payment-required message.

schemestringRequired

The payment scheme used: "exact", "onchain", or "receipt".

signaturestring

The EIP-3009 permit signature (required for "exact" scheme).

tx_hashstring

The blockchain transaction hash (required for "onchain" scheme).

Example Request

curl https://p402.io/api/a2a \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "x402/payment-submitted",
    "params": {
      "payment_id": "pay_123",
      "scheme": "exact",
      "signature": "0x..."
    },
    "id": 1
  }'

Example Response

{
  "jsonrpc": "2.0",
  "result": {
    "payment_id": "pay_123",
    "status": "completed",
    "receipt": {
      "receipt_id": "rec_456",
      "signature": "0x..."
    }
  },
  "id": 1
}
POST/api/v1/router/plan

Plan Route (Legacy)

V1 Endpoint. Calculates the optimal routing path for a resource request without executing it. Returns payment requirements and facilitator selection.

Parameters

routeIdstringRequired

The target resource identifier.

paymentobjectRequired

Payment preferences { network, scheme, amount, asset }.

policyIdstring

Optional policy ID to enforce during planning.

Example Request

curl https://p402.io/api/v1/router/plan \
  -H "Content-Type: application/json" \
  -d '{
    "routeId": "MODEL_GPT4",
    "payment": {
        "network": "eip155:8453",
        "scheme": "eip3009",
        "amount": "0.50",
        "asset": "USDC"
    }
  }'

Example Response

{
  "decision_id": "trace_abc123",
  "route": {
    "id": "route_xyz",
    "facilitator_url": "https://...",
    "cost": 0.5
  },
  "payment_headers": {
    "X-Payment-Required": "true"
  }
}
POST/api/v1/router/settle

Settle Payment (Legacy)

V1 Endpoint. Records an on-chain settlement for a planned route. Use this to finalize a transaction after the user has paid.

Parameters

txHashstringRequired

The verified transaction hash.

amountstringRequired

Amount settled.

assetstringRequired

Asset symbol (e.g. USDC).

decisionIdstring

The decision ID from the /plan response.

Example Request

curl https://p402.io/api/v1/router/settle \
  -H "Content-Type: application/json" \
  -d '{
    "txHash": "0x...",
    "amount": "0.50",
    "asset": "USDC",
    "decisionId": "trace_abc123"
  }'

Example Response

{
  "success": true,
  "settlement_id": "set_789",
  "status": "confirmed"
}
POST/api/v1/intelligence/audit

Autonomous Policy Audit

Audits A2A traffic flows to identify cost optimizations and budget compliance. Powered by Gemini 3 Pro.

Parameters

daysnumber

History window to analyze (default: 7).

executeboolean

Actually execute the recommended optimizations (Autonomous mode).

Example Request

curl -X POST https://p402.io/api/v1/intelligence/audit \
  -H "Content-Type: application/json" \
  -d '{"days": 7, "execute": true}'

Example Response

{
  "audit_id": "audit_123",
  "thinking_trace": [
    "Analyzing 5,432 decisions...",
    "Detected GPT-4 overkill on simple tasks.",
    "Executing model_substitution..."
  ],
  "total_savings": 42.5
}
POST/api/v1/intelligence/code-audit

Security & Privacy Audit

Performs a deep audit of agent infrastructure for security vulnerabilities and privacy leaks.

Parameters

codestringRequired

The agent/application code to audit.

Example Request

curl -X POST https://p402.io/api/v1/intelligence/code-audit \
  -H "Content-Type: application/json" \
  -d '{"code": "import openai\nclient = openai.OpenAI(...)"}'

Example Response

{
  "report": "# Audit Report\n\nRISK SCORE: 8/10\n- Dangerous loop detected...",
  "metrics": {
    "riskScore": 8,
    "costPerHour": 15
  }
}
GET/api/v1/intelligence/status

Governance Status

Retrieves the current status of the protocol governance layer and active policy enforcement.

Example Request

curl https://p402.io/api/v1/intelligence/status

Example Response

{
  "agents": {
    "economist": "online",
    "sentinel": "active",
    "memory": "92% hit rate"
  },
  "total_savings": 12450.8
}