Client                          Server  
  │                               │  
  │── GET /api/resource ─────────▶️│  
  │                               │  
  │◀️── 402 Payment Required ──────│  
  │    X-Gao-Payment-Details: {   │  
  │      intent_template: {...},  │  
  │      amount: "0.01",          │  
  │      currency: "USDC",        │  
  │      payee_domain: "api.gao", │  
  │      network: "base",         │  
  │      expires_in: 300          │  
  │    }                          │  
  │                               │  
  │ [Client creates payment       │  
  │  intent + wallet signs]       │  
  │                               │  
  │── GET /api/resource ─────────▶️│  
  │   X-Gao-Payment-Proof:        │  
  │     <base64url(receipt)>      │  
  │                               │  
  │◀️── 200 OK + resource ─────────│  
  │    X-Gao-Receipt-Id: rcpt_... │

---

### 402 Response Headers

When a server returns HTTP 402, it includes the `X-Gao-Payment-Details` header:

{  
  "intent_template": {  
    "payee_domain": "api.gao",  
    "amount": "0.01",  
    "currency": "USDC",  
    "network": "base",  
    "metadata": {  
      "resource": "/api/data/prices",  
      "request_id": "req_abc123"  
    }  
  },  
  "accepted_capabilities": ["payment:send", "payment:autopay"],  
  "risk_tier_max": 1,  
  "expires_in": 300,  
  "payment_endpoint": "https://pay.gao.systems/v1/intents",  
  "schema_version": "x402/1.0"  
}

Field

Description

`intent_template`

Pre-populated fields for the payment intent the server expects

`accepted_capabilities`

CAP capability types the server will accept as proof

`risk_tier_max`

Maximum risk tier the server will accept in proof (servers may reject high-tier proofs)

`expires_in`

Seconds the payment proof must be received within

`payment_endpoint`

Gao Payment API endpoint for intent creation

---

### Payment Proof Header

The client retries the request with a `X-Gao-Payment-Proof` header containing a base64url-encoded canonical receipt:

The decoded value is a full canonical receipt JSON (see Receipt Schema).

#### Proof Validation by Server

The server validates the proof by checking:

1.  `receipt.status == "settled"`
    
2.  `receipt.parties.payee_domain == server.payee_domain`
    
3.  `receipt.settlement.amount >= required_amount`
    
4.  `receipt.settlement.currency == required_currency`
    
5.  `receipt.intent.settled_at` is within the `expires_in` window
    
6.  `receipt.receipt_id` has not been used for this resource before (replay prevention)
    
7.  Runtime signature on receipt is valid
    

Servers **must** implement replay prevention by tracking `receipt_id` values used for resource access.

---

### Server Implementation

**Node.js / TypeScript**

import { x402Middleware } from '@gao/sdk/x402';  
  
app.use('/api/premium', x402Middleware({  
  payeeDomain: 'myapi.gao',  
  amount: '0.01',  
  currency: 'USDC',  
  network: 'base',  
  riskTierMax: 1,  
  onValidReceipt: async (receipt, req) => {  
    // Optional: log receipt, update usage, etc.  
    await logUsage(receipt.receipt_id, req.path);  
  },  
}));  
  
app.get('/api/premium/data', (req, res) => {  
  res.json({ data: 'premium content' });  
});

import { validateX402Proof } from '@gao/sdk/x402';  

  
app.get('/api/resource', async (req, res) => {  
  const proof = req.headers['x-gao-payment-proof'];  
  
  if (!proof) {  
    return res.status(402).json({  
      'X-Gao-Payment-Details': {  
        intent_template: { payee_domain: 'myapi.gao', amount: '0.01', currency: 'USDC', network: 'base' },  
        expires_in: 300,  
        payment_endpoint: 'https://pay.gao.systems/v1/intents',  
        schema_version: 'x402/1.0',  
      }  
    });  
  }  
  
  const result = await validateX402Proof(proof, {  
    payeeDomain: 'myapi.gao',  
    minAmount: '0.01',  
    currency: 'USDC',  
    replayStore: redisClient, // any KV store for receipt_id dedup  
  });  
  
  if (!result.valid) {  
    return res.status(402).json({ error: result.reason });  
  }  

  
  res.set('X-Gao-Receipt-Id', result.receiptId);  
  res.json({ data: 'premium content' });  
});

import { x402Client } from '@gao/sdk/x402';  
  
const client = x402Client({  
  payerDomain: 'myagent.gao',  
  capToken: process.env.GAO_CAP_TOKEN,  
  maxAutoPayAmount: '0.10',  // per-request ceiling for auto-pay  
  currency: 'USDC',  
});  

const response = await client.fetch('https://api.external.gao/data/prices');  
const data = await response.json();

The `x402Client` wrapper:

1.  Detects HTTP 402 responses
    
2.  Parses `X-Gao-Payment-Details`
    
3.  Creates a payment intent via the Gao Payment API
    
4.  Waits for settlement confirmation
    
5.  Retries the original request with proof header
    
6.  Throws if amount exceeds `maxAutoPayAmount` (requires human approval)
    

---

Replay Prevention

Servers must prevent the same receipt from being used to access the same resource more than once.

The receipt `receipt_id` is the replay key. Implementation options:

// Redis example  
async function checkAndMarkReceipt(receiptId: string, resourcePath: string): Promise<boolean> {  
  const key = `x402:used:${receiptId}:${resourcePath}`;  
  const set = await redis.set(key, '1', 'NX', 'EX', 86400); // 24hr TTL  
  return set === 'OK'; // true = first use, false = replay  
}