Skip to content

Pipegate x402 Protocol Specification

PipeGate implements the x402 payment protocol standard for standardized API payment flows.

Payment Flow

  1. Client Request: Client makes API request without payment headers
  2. 402 Response: Server responds with 402 Payment Required containing accepted schemes
  3. Payment Selection: Client selects scheme and constructs payment header
  4. Retry: Client retries request with X-Payment header
  5. Verification: Server verifies payment and processes request

402 Payment Required Response

When payment is required, servers return this standard format:

{
  "x402Version": 1,
  "accepts": [
    {
      "scheme": "one-time",
      "network": "base",
      "amount": "0.001",
      "payTo": "0x..address",
      "asset": "0x..token_address",
      "resource": "example.com/api/resource",
      "description": "Access to example.com API resource",
      "maxTimeoutSeconds": 300,
      "extra": {
        "absWindowSeconds": 172800,
        "sessionTTLSeconds": 3600,
        "maxRedemptions": 5
      }
    }
  ]
  "error": "Payment Required"
}

X-Payment Header Format

Clients send payment headers in this standardized format:

{
  "x402Version": 1,
  "network": "base",
  "scheme": "one-time",
  "payload": {
    // Scheme-specific payload
  }
}

Scheme-Specific Payloads

One-Time Payment

{
  "signature": "0x..sig",
  "tx_hash": "0x..hash"
}

Superfluid Stream

{
  "signature": "0x..sig",
  "sender": "0x..address"
}

Payment Channel

{
  "signature": "0x..sig",
  "message": "0x..message",
  "paymentChannel": {
    "channelId": "string",
    "address": "string",
    "sender": "string",
    "recipient": "string",
    "balance": "string",
    "nonce": "number",
    "expiration": "number"
  },
  "timestamp": "number"
}

Benefits

  • Standardization: Compatible with other x402-compliant services
  • Automatic Handling: Unified interceptors handle all schemes
  • Future-Proof: New payment schemes work without client changes
  • Interoperability: Works across different payment providers

Implementation

PipeGate's unified approach in v0.6.0+ automatically handles x402 protocol compliance:

  • Client: withPaymentInterceptor parses 402 responses and constructs compliant headers
  • Server: PaymentsLayer emits standard 402 responses and validates x402 headers