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.
Create account and API key
Get credentials. The API key is returned exactly once.
# 1. Sign up at p402.io/login # 2. Go to Dashboard → Settings → 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.
Key display closes before you copy it.
Go to Settings → API Keys → Delete the old key → Generate again. The old hash is invalidated immediately.
Verify a payment payload
Check the EIP-3009 authorization before committing to settlement.
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"
}
}'{
"valid": true,
"requestId": "req_01HX4...",
"scheme": "exact",
"network": "eip155:8453"
}{"valid": false, "errorCode": "AMOUNT_MISMATCH", "requestId": "req_..."}Check that value in authorization equals maxAmountRequired exactly. Both are in atomic USDC units (6 decimals). $1.00 = "1000000".
Settle the payment
Execute the on-chain USDC transfer. Facilitator pays gas.
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... }
}'{
"success": true,
"transaction": "0xabc123...",
"network": "eip155:8453",
"payer": "0x<payer-wallet>",
"requestId": "req_01HX5..."
}{"success": false, "errorCode": "REPLAY_DETECTED", "requestId": "req_..."}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.
Retry the original request with proof
Serve the paid resource by including the settlement proof in the retry.
# 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
});HTTP 200 OK
x-p402-settled: true
x-p402-receipt: rcpt_01HX6...
{ ...your endpoint response... }Still receiving HTTP 402 after settlement.
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.
Issue a receipt
Bind the settled payment to a reusable receipt. Avoids re-settling for the same resource.
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
}'{
"receiptId": "rcpt_01HX6...",
"resource": "https://your-api.com/endpoint",
"ttl": 3600,
"expiresAt": "2025-01-01T01:00:00Z",
"reuseCount": 0
}{"error": "TX_NOT_FOUND", "requestId": "req_..."}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.
Reuse the receipt
Access the same resource again without a new payment. Cache economics kick in here.
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..."
# 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{"valid": false, "reason": "RECEIPT_EXPIRED", "requestId": "req_..."}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.
You're settling payments.
Add spend policies to govern agent budgets. Create AP2 mandates for multi-agent workflows. Export evidence bundles for compliance review.