x402 Compatibility

x402 is a payment protocol built directly into HTTP. It brings the long-dormant 402 Payment Required status code back into service, specifying how a server advertises its prices and how a client attaches proof of payment to a request. Coinbase created the protocol in May 2025; governance now sits with the x402 Foundation under the Linux Foundation, with Google, Visa, Stripe, AWS, Mastercard, Microsoft, Shopify, and Circle all participating. More than 100 million transactions have gone through it.

HoodLayer implements x402 natively on Robinhood Chain. Integrate it as a service provider and your API endpoint turns into an x402-compatible resource server. Build with the HoodLayer Agent SDK and your agent acts as 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": "robinhood-mainnet",
       "token": "0xecdda8f70c0880d915f746c861ace5dd58721a74",
       "amount": "1000000",
       "payTo": "0x9Ca4...",
       "memo": "api-req-abc123"
     }]
   }

3. Client reads the payment terms, signs and submits a USDC transfer
   via the HoodLayer 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 ... }

HoodLayer-specific fields

The base x402 payment object gains a few optional fields under HoodLayer, carrying subscription and plan details:

{
  "version": "1",
  "accepts": [{
    "scheme": "exact",
    "network": "robinhood-mainnet",
    "token": "0xecdda8f70c0880d915f746c861ace5dd58721a74",
    "amount": "1000000",
    "payTo": "0x9Ca4...",
    "memo": "api-req-abc123",
    "hoodlayer": {
      "planId": "0x7f3a...",
      "subscriptionScheme": true,
      "facilitator": "https://facilitator.hoodlayer.org"
    }
  }]
}

The hoodlayer extension object isn’t required. A standard x402 client that doesn’t recognize the field simply falls back to one-time payment behavior. Clients built on the HoodLayer SDK favor the subscription scheme whenever subscriptionScheme: true appears.

Acting as a Facilitator

x402 uses the term Facilitator for the trusted processor that settles payments on-chain for resource servers. That role is filled here by HoodLayer’s Facilitator Network. Integrating HoodLayer hands settlement off to the Facilitator, which gets you:

• Native settlement on Robinhood Chain with fees under a cent
• Subscription and allowance handling built on top of per-request payments
• Analytics on your x402 volume in the Dashboard
• Webhook events covering the payment lifecycle

Payment proof verification

Inside the X-PAYMENT header sits a base64-encoded proof object carrying the HoodLayer Facilitator’s signature. Checking that proof is the Provider SDK’s job:

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

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

If you use the paymentGate middleware, it takes care of this step for you.

Multi-scheme support

A single payment gate can offer more than one scheme: subscriptions, one-time payments, or both at once.

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

An agent holding an active subscription goes straight through. One without a subscription gets the full 402 response listing both options.

x402 version support

x402 V1 is supported today, and we’re keeping an eye on V2 work (multi-chain routing, session tokens) as it takes shape. Once that specification settles down, the SDK will pick up the V2 features.