P402 Logo
P402.io
Developers / Quickstart

First payment
in one session.

Six steps: verify, settle, retry, issue receipt, reuse receipt. Each step has one command, expected output, and a recovery path.

01Create account and API key02Verify a payment payload03Settle the payment04Retry the original request with proof05Issue a receipt06Reuse the receipt
Prerequisites
A wallet with USDC on Base Mainnet (for signing EIP-3009 authorizations in steps 2–3)
curl or any HTTP client. The SDK handles steps 4–6 automatically if preferred.
~$0.01 USDC for test settlements. No credit card required for the P402 account itself.
01

Create account and API key

Get credentials. The API key is returned exactly once.

Setup
# 1. Sign up at p402.io/login
# 2. Go to Dashboard, then Settings, then API Keys
# 3. Click "Generate new key"

# Your key looks like:
P402_API_KEY=p402_live_...

# Save it now. P402 stores only the SHA-256 hash.
# You cannot recover a lost key. Generate a new one if needed.
Common failure
Key display closes before you copy it.
Recovery

Go to Settings, then API Keys, delete the old key, then generate again. The old hash is invalidated immediately.

API key docs
Completed step 01Next: Verify a payment payload
02

Verify a payment payload

Check the EIP-3009 authorization before committing to settlement.

Command
curl -X POST https://p402.io/api/v1/facilitator/verify \
  -H "Authorization: Bearer $P402_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "paymentPayload": {
      "x402Version": 2,
      "scheme": "exact",
      "network": "eip155:8453",
      "payload": {
        "signature": "0x<EIP-712-sig>",
        "authorization": {
          "from":        "0x<payer-wallet>",
          "to":          "0xFa772434DCe6ED78831EbC9eeAcbDF42E2A031a6",
          "value":       "1000000",
          "validAfter":  "0",
          "validBefore": "9999999999",
          "nonce":       "0x<random-bytes32>"
        }
      }
    },
    "paymentRequirements": {
      "scheme":             "exact",
      "network":            "eip155:8453",
      "maxAmountRequired":  "1000000",
      "resource":           "https://your-api.com/endpoint",
      "description":        "Access to premium endpoint",
      "payTo":              "0xFa772434DCe6ED78831EbC9eeAcbDF42E2A031a6",
      "asset":              "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"
    }
  }'
Expected output
{
  "valid": true,
  "requestId": "req_01HX4...",
  "scheme": "exact",
  "network": "eip155:8453"
}
Common failure
{"valid": false, "errorCode": "AMOUNT_MISMATCH", "requestId": "req_..."}
Recovery

Check that value in authorization equals maxAmountRequired exactly. Both are in atomic USDC units (6 decimals). $1.00 = "1000000".

Verify reference
Completed step 02Next: Settle the payment
03

Settle the payment

Execute the on-chain USDC transfer. Facilitator pays gas.

Command
curl -X POST https://p402.io/api/v1/facilitator/settle \
  -H "Authorization: Bearer $P402_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "paymentPayload": { ...same as step 2... },
    "paymentRequirements": { ...same as step 2... }
  }'
Expected output
{
  "success": true,
  "transaction": "0xabc123...",
  "network": "eip155:8453",
  "payer": "0x<payer-wallet>",
  "requestId": "req_01HX5..."
}
Common failure
{"success": false, "errorCode": "REPLAY_DETECTED", "requestId": "req_..."}
Recovery

REPLAY_DETECTED means this nonce was already settled. Generate a fresh nonce (random bytes32) and re-sign the authorization. Each nonce is one-time-use.

Settlement reference
Completed step 03Next: Retry the original request with proof
04

Retry the original request with proof

Serve the paid resource by including the settlement proof in the retry.

Command
# Include the x402-payment header on retry:
curl https://your-api.com/endpoint \
  -H "x402-payment: $PAYMENT_PAYLOAD_BASE64" \
  -H "x402-receipt: $TX_HASH"

# Or use the SDK, it handles retry automatically:
import { p402Fetch } from '@p402/sdk';

const response = await p402Fetch('https://your-api.com/endpoint', {
  wallet: yourWallet,
  maxAmount: 1_000_000n, // $1.00 USDC
});
Expected output
HTTP 200 OK
x-p402-settled: true
x-p402-receipt: rcpt_01HX6...

{ ...your endpoint response... }
Common failure
Still receiving HTTP 402 after settlement.
Recovery

Confirm settle returned success: true and you have a txHash. Check that you are sending the x402-payment header, not just the Authorization header. The resource server validates the payment header independently.

SDK reference
Completed step 04Next: Issue a receipt
05

Issue a receipt

Bind the settled payment to a reusable receipt. Avoids re-settling for the same resource.

Command
curl -X POST https://p402.io/api/v1/receipts \
  -H "Authorization: Bearer $P402_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "txHash":   "0xabc123...",
    "resource": "https://your-api.com/endpoint",
    "ttl":      3600
  }'
Expected output
{
  "receiptId": "rcpt_01HX6...",
  "resource":  "https://your-api.com/endpoint",
  "ttl":       3600,
  "expiresAt": "2025-01-01T01:00:00Z",
  "reuseCount": 0
}
Common failure
{"error": "TX_NOT_FOUND", "requestId": "req_..."}
Recovery

The txHash must match a settled transaction in your account. Wait 2–3 seconds after settlement for chain finality, then retry. Base Mainnet average block time is ~2s.

Receipts reference
Completed step 05Next: Reuse the receipt
06

Reuse the receipt

Access the same resource again without a new payment. Cache economics kick in here.

Command
curl https://p402.io/api/v1/receipts/rcpt_01HX6.../verify \
  -H "Authorization: Bearer $P402_API_KEY"

# If valid, serve without re-settling:
curl https://your-api.com/endpoint \
  -H "x402-receipt: rcpt_01HX6..."
Expected output
# Receipt verify response:
{
  "valid":      true,
  "reuseCount": 1,
  "expiresAt":  "2025-01-01T01:00:00Z",
  "resource":   "https://your-api.com/endpoint"
}

# Endpoint response:
HTTP 200 OK, served without new settlement
Common failure
{"valid": false, "reason": "RECEIPT_EXPIRED", "requestId": "req_..."}
Recovery

Receipt TTL has elapsed. Issue a new receipt (step 5) after your next settlement. Plan receipt TTLs around your usage patterns: longer TTLs reduce settlement costs for high-frequency access.

Receipt lifecycle
All six steps complete

You're settling payments.

Add spend policies to govern agent budgets. Create AP2 mandates for multi-agent workflows. Export evidence bundles for compliance review.

Open dashboardSet spend controlsExamples on GitHub