P402 Logo
P402.io
Production API

API Reference

Welcome to the P402 production API. Execute gasless USDC payments on Base L2 using EIP-3009 transferWithAuthorization. Global facilitator network with sub-50ms verification times.

V1 — Payment Layer

x402 payment protocol: route planning, settlement, facilitator management, AP2 policy mandates, and protocol governance. The cryptographic foundation for agent payments.

V2 — Orchestration Layer

OpenAI-compatible AI routing: multi-provider completions, semantic caching, session management, and real-time cost optimization. Drops into any OpenAI SDK.

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.

Error Codes

P402 uses a unified error format across all endpoints. Errors are returned with an appropriate HTTP status code and a JSON body containing an error object.

# Error Response Format
{
  "error": {
    "type": "invalid_request",  // Category
    "code": "INVALID_INPUT",    // Specific machine-readable code
    "message": "Amount must be greater than 0"
  }
}

Common Error Codes

INVALID_INPUT

Missing or malformed request parameters.

UNAUTHORIZED

Missing or invalid API key.

POLICY_DENIED

Request blocked by governance policy (budgets, allowed actions).

SETTLEMENT_FAILED

On-chain verification failed or transaction not found.

RATE_LIMITED

Too many requests. Please slow down.

INTERNAL_ERROR

Unexpected server-side error.

POSThttps://p402.io/api/v1/facilitator/verify

Verify Payment Authorization

Verify an EIP-3009 payment authorization without executing it. Uses the x402 wire format: paymentPayload (containing the signed authorization) and paymentRequirements (the terms being paid for). Returns { isValid, payer } on success.

Parameters

paymentPayloadobjectRequired

x402 payment payload containing scheme, network, and the signed authorization + signature

paymentRequirementsobjectRequired

The payment requirements: scheme, network, maxAmountRequired, payTo, asset, resource

Example Request

curl https://p402.io/api/v1/facilitator/verify \
  -H "Content-Type: application/json" \
  -d '{
    "paymentPayload": {
      "x402Version": 2,
      "scheme": "exact",
      "network": "eip155:8453",
      "payload": {
        "signature": "0x...",
        "authorization": {
          "from": "0x...",
          "to": "0xb23f146251e3816a011e800bcbae704baa5619ec",
          "value": "1000000",
          "validAfter": "0",
          "validBefore": "1735689600",
          "nonce": "0x..."
        }
      }
    },
    "paymentRequirements": {
      "scheme": "exact",
      "network": "eip155:8453",
      "maxAmountRequired": "1000000",
      "resource": "https://example.com/api",
      "description": "AI inference",
      "payTo": "0xb23f146251e3816a011e800bcbae704baa5619ec",
      "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"
    }
  }'

Example Response

{
  "isValid": true,
  "payer": "0x..."
}
POSThttps://p402.io/api/v1/facilitator/settle

Execute Gasless Settlement

Execute a gasless USDC settlement using the x402 wire format. The facilitator pays gas fees and executes the EIP-3009 transferWithAuthorization. Returns a SettleResponse with { success, transaction, network, payer }.

Parameters

paymentPayloadobjectRequired

x402 payment payload containing the signed authorization and 65-byte signature

paymentRequirementsobjectRequired

The payment requirements: scheme, network, maxAmountRequired, payTo, asset

Example Request

curl https://p402.io/api/v1/facilitator/settle \
  -H "Content-Type: application/json" \
  -d '{
    "paymentPayload": {
      "x402Version": 2,
      "scheme": "exact",
      "network": "eip155:8453",
      "payload": {
        "signature": "0x...",
        "authorization": {
          "from": "0x...",
          "to": "0xb23f146251e3816a011e800bcbae704baa5619ec",
          "value": "1000000",
          "validAfter": "0",
          "validBefore": "1735689600",
          "nonce": "0x..."
        }
      }
    },
    "paymentRequirements": {
      "scheme": "exact",
      "network": "eip155:8453",
      "maxAmountRequired": "1000000",
      "resource": "https://example.com/api",
      "description": "AI inference",
      "payTo": "0xb23f146251e3816a011e800bcbae704baa5619ec",
      "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"
    }
  }'

Example Response

{
  "success": true,
  "transaction": "0x88df016a12fa890a...",
  "network": "eip155:8453",
  "payer": "0x..."
}
POST/api/v1/receipts

Create Payment Receipt

Create a reusable payment receipt from a successful transaction. Receipts can be used for multiple AI sessions without additional signatures.

Parameters

txHashstringRequired

Transaction hash from successful settlement

sessionIdstringRequired

Session identifier for tracking

amountnumberRequired

Amount in USD (decimal)

metadataobject

Optional metadata (payer, network, token)

Example Request

curl https://p402.io/api/v1/receipts \
  -H "Content-Type: application/json" \
  -d '{
    "txHash": "0x88df01e...",
    "sessionId": "session_123",
    "amount": 1.0,
    "metadata": {
      "payer": "0x...",
      "network": "eip155:8453",
      "token": "USDC"
    }
  }'

Example Response

{
  "success": true,
  "receiptId": "rcpt_456",
  "validUntil": "2024-12-31T23:59:59Z",
  "amount": 1,
  "network": "eip155:8453",
  "token": "USDC"
}
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

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": "exact",
        "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

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

{
  "scheme": "onchain",
  "settled": true,
  "facilitatorId": "chain_base",
  "receipt": {
    "txHash": "0x...",
    "verifiedAmount": "0.50",
    "asset": "USDC",
    "timestamp": "2026-01-15T12:00:00Z"
  }
}
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
}