Skip to content

Pipegate x402 Protocol Specification

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

Supported Payment Schemes

PipeGate supports three main payment schemes, each with detailed technical specifications:

Payment Flow

  1. Client Request: Client makes API request without payment headers
  2. 402 Response: Server responds with 402 Payment Required containing accepted schemes and configuration
  3. Payment Selection: Client selects appropriate payment scheme based on use case
  4. Payment Execution: Client completes payment using the chosen method (transaction, stream setup, or channel creation)
  5. Authorization: Client constructs X-Payment header with payment proof
  6. Retry: Client retries request with X-Payment header
  7. Verification: Server verifies payment and processes request

402 Payment Required Response

When payment is required, servers return this standard format with scheme-specific configuration:

Basic Structure

{
  "x402Version": 1,
  "accepts": [
    {
      "scheme": "one-time", // "one-time", "stream", or "channel"
      "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": {} // Scheme-specific configuration
    }
  ],
  "error": "Payment Required"
}

Scheme-Specific Configuration

One-Time Payment Configuration

{
  "scheme": "one-time",
  "amount": "0.001", // Amount per session
  "extra": {
    "absWindowSeconds": 172800, // Payment window (48 hours)
    "sessionTTLSeconds": 3600, // Session validity (1 hour)
    "maxRedemptions": 5 // Maximum API calls per payment
  }
}

Superfluid Stream Configuration

{
  "scheme": "stream",
  "amount": "2", // Flow rate per month
  "extra": null // Real-time verification, no additional config
}

Payment Channel Configuration

{
  "scheme": "channel",
  "amount": "0.001", // Amount per request
  "extra": {
    // Current channel state if exists, null if new channel needed
    "channelId": "string",
    "balance": "string",
    "nonce": "number"
  }
}

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

Each payment scheme uses a different payload structure in the X-Payment header. See the detailed specifications for complete implementation details.

One-Time Payment

Direct blockchain transaction with ownership proof:

{
  "signature": "0x..sig", // Signature proving transaction ownership
  "tx_hash": "0x..hash" // Hash of the payment transaction
}

Use Case: Session-based access with configurable limits
→ Full Implementation Guide

Superfluid Stream

Continuous money streaming with real-time verification:

{
  "signature": "0x..sig", // Signature proving stream ownership
  "sender": "0x..address" // Stream sender address
}

Use Case: Continuous access → Full Implementation Guide

Payment Channel

Off-chain micropayments with instant settlement:

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

Use Case: High-frequency, low-cost transactions
→ Full Implementation Guide

Benefits

  • Multiple Payment Options: Choose the optimal payment method for your use case
  • Standardization: Compatible with other x402-compliant services
  • Unified Integration: Single interceptor handles all payment schemes
  • Future-Proof: New payment schemes work without client changes
  • Cost Optimization: From high-frequency micropayments to session-based access
  • Real-Time Streaming: Pay only for what you use with Superfluid integration

Technical Specifications

For complete implementation details, verification processes, and code examples, see the technical specifications:

General Scheme Documentation

Implementation

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

  • Client: withPaymentInterceptor parses 402 responses and returns accepted payment methods. Users must manually complete payments (transactions, streams, channels) and construct X-Payment headers.
  • Server: PaymentsLayer emits standard 402 responses and validates x402 headers across all schemes. State management handled by server middleware.

Getting Started

  1. Choose Payment Method: Review the payment methods to select the optimal scheme
  2. Review Implementation: Check the detailed guides and technical specifications
  3. Integrate Client: Use the withPaymentInterceptor for unified 402 handling
  4. Configure Server: Set up PaymentsLayer with your chosen schemes and networks
  5. Test Integration: Verify end-to-end payment flows in your development environment

For questions or support, see the guidelines or open an issue on GitHub.