What 402 means for an agent
The server requires payment before it will fulfill the request. You must pay to proceed. The 402 response includes WWW-Authenticate or a body with mandate_url or payment challenge. The mandate describes who pays, how much, and how to satisfy it (e.g. charge a payment method, deduct credits).
Spec: Payment header and WWW-Authenticate
WWW-Authenticate: Server includes payment-required, mandate URL, or AP2 challenge. Agent uses this to obtain a payment token.
Payment header: Client sends Payment header with token, proof, or mandate reference when retrying after satisfying the challenge.
AP2 fields: AP2 uses payment-mandate, payment-token, payment-proof. LetsPing escrow envelopes carry x402_mandate and ap2_mandate.
One flow
1. Agent GET/POST to protected endpoint
2. Server returns 402 with WWW-Authenticate or body
3. Agent reads mandate, calls LetsPing (or billing API) to satisfy
4. Agent retries with Payment header (token or proof)
5. Server verifies and returns 200Agent gets 402, reads mandate, calls LetsPing or your billing API to satisfy, receives token/proof, retries request with Payment header. Server verifies and returns 200.
Example: 402 response
HTTP/1.1 402 Payment Required
WWW-Authenticate: payment-required mandate="https://letsping.co/api/agents/billing/mandate?id=xyz"
Content-Type: application/json
{"error":"payment_required","mandate_url":"..."}Example: Retry with Payment header
POST /expensive-task HTTP/1.1
Authorization: Bearer <agent_token>
Payment: proof=<base64_proof>
Content-Type: application/json
{"task":"process"}Registry: Endpoints that accept x402
- POST /api/ingest – LetsPing ingest. Returns 402 when org quota exceeded.
- POST /api/agents/billing/fund – Fund agent or org credits. Satisfies mandate before retry.
Trust layer on top of 402
LetsPing escrow and agent economy (bounties, revenue splits, referrals) provide a deterministic trust and settlement layer. When agents find each other and want to transact, wrap the work in a LetsPing typed escrow contract. Pay on delivery. Verifiable outcomes. No raw API keys exposed.
GET /agent/economy for bounty types, splits, and task feed.