x402 Compatibility

x402 is an HTTP-native payment protocol that revives the 402 Payment Required status code. It defines how servers communicate pricing and how clients attach payment proofs to requests. The protocol originated at Coinbase in May 2025 and is now governed by the x402 Foundation under the Linux Foundation, with participation from Google, Visa, Stripe, AWS, Mastercard, Microsoft, Shopify, and Circle.

Recur is a first-class x402 implementation on Solana. When you integrate Recur as a service provider, your API endpoint becomes an x402-compatible resource server. When you use the Recur Agent SDK, your agent becomes an x402-compatible client.

The x402 flow

1. Client (agent) makes an unauthenticated HTTP request
   GET /v1/resource

2. Server responds with 402 Payment Required
   HTTP/1.1 402 Payment Required
   Content-Type: application/json

   {
     "version": "1",
     "accepts": [{
       "scheme": "exact",
       "network": "solana-mainnet",
       "token": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
       "amount": "1000000",
       "payTo": "GkN...",
       "memo": "api-req-abc123"
     }]
   }

3. Client reads the payment terms, signs and submits a USDC transfer
   via the Recur Facilitator

4. Facilitator confirms the on-chain transaction, returns a proof object

5. Client retries the request with the proof attached
   GET /v1/resource
   X-PAYMENT: <base64-encoded proof object>

6. Server verifies the proof against the Facilitator or on-chain
   HTTP/1.1 200 OK
   Content-Type: application/json
   { ... resource data ... }

Recur-specific fields

Recur extends the base x402 payment object with optional fields for subscription and plan information:

{
  "version": "1",
  "accepts": [{
    "scheme": "exact",
    "network": "solana-mainnet",
    "token": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
    "amount": "1000000",
    "payTo": "GkN...",
    "memo": "api-req-abc123",
    "recur": {
      "planId": "7xKp...",
      "subscriptionScheme": true,
      "facilitator": "https://facilitator.recurprotocol.com"
    }
  }]
}

The recur extension object is optional. Standard x402 clients that do not understand this field will fall back to one-time payment behavior. Recur SDK clients will prefer the subscription scheme when subscriptionScheme: true is set.

Acting as a Facilitator

In x402 terminology, a Facilitator is the trusted processor that handles on-chain settlement on behalf of resource servers. Recur’s Facilitator Network acts in this role. By integrating Recur, you delegate settlement to Recur’s Facilitator and get:

• Solana-native settlement at sub-cent fees
• Subscription and allowance logic layered on top of per-request payments
• Dashboard analytics on x402 volume
• Webhook events for payment lifecycle

Payment proof verification

The X-PAYMENT header contains a base64-encoded proof object signed by the Recur Facilitator. The Recur Provider SDK verifies this proof:

// In your middleware or route handler
const proof = recur.parsePaymentProof(req.headers["x-payment"]);
const valid = await recur.verifyPaymentProof(proof);

if (!valid) {
  return res.status(402).json(recur.buildPaymentRequired({ plan: plan.id }));
}

The paymentGate middleware handles this automatically if you use it.

Multi-scheme support

Your payment gate can accept multiple schemes — subscription, one-time payment, or both:

app.use("/api/v1", recur.paymentGate({
  pricing: [
    { type: "subscription", plan: monthlyPlanId },
    { type: "one-time", amount: 500_000 }, // fallback at 0.50 USDC/call
  ],
}));

Agents with an active subscription pass through automatically. Agents without a subscription receive the full 402 response with both options listed.

x402 version support

Recur supports x402 V1 and is tracking V2 developments (multi-chain routing, session tokens). The SDK will be updated to support V2 features as the specification stabilizes.