Skip to content

Getting Started (v0.6.0+)

For API Users

Follow these steps to start making API calls with the new unified x402 interceptor:

Install SDK

Terminal
npm install pipegate-sdk

The latest SDK provides unified payment interceptor supporting all payment schemes through the x402 standard.

Choose Payment Method

PipeGate supports three payment methods that work with the unified interceptor:

  1. One-Time Payments
    • Pay per request using transaction hash
    • Perfect for occasional API usage
    • No setup required beyond the transaction
  2. Superfluid Streams
    • Continuous payment flows
    • Ideal for subscription-based APIs
    • Real-time value transfer

  3. Payment Channels [Beta]

    • Gasless microtransactions
    • Best for frequent API calls
    • Deposit once, use multiple times

Setup Unified Client

import axios from "axios";
import { withPaymentInterceptor } from "pipegate-sdk";
 
const PRIVATE_KEY = "0x..."; // Your wallet private key
 
// One-time payment
const client = withPaymentInterceptor(
  axios.create({ baseURL: "https://api.example.com" }),
  PRIVATE_KEY,
  { oneTimePaymentTxHash: "0x..." }
);
 
// Stream payment
const streamClient = withPaymentInterceptor(
  axios.create({ baseURL: "https://api.example.com" }),
  PRIVATE_KEY,
  { streamSender: "0xSenderAddress" }
);
 
// Payment channel
const channelClient = withPaymentInterceptor(
  axios.create({ baseURL: "https://api.example.com" }),
  PRIVATE_KEY,
  { channel: channelResponse }
);

Make Your First API Call

The interceptor automatically handles payment headers and 402 retries:

// Simple API call - payment handled automatically
const response = await client.get("/api/endpoint");
 
// Works with any HTTP method
const postResponse = await client.post("/api/data", {
  payload: "data",
});

How it works

  1. First request: If server returns 402 Payment Required, interceptor:

    • Parses payment requirements from server
    • Selects matching payment scheme from your config
    • Signs and constructs x402-compliant payment header
    • Automatically retries the request

  2. Subsequent requests: Payment headers included automatically

  3. State management: For channels, response headers update local state

For API Providers

Setting up the unified server middleware for x402 support:

Install Pipegate Crate

Terminal
cargo add pipegate

Or add to your Cargo.toml:

[dependencies]
pipegate = { version = "0.6.0" }

Setup Unified Middleware

use pipegate::middleware::{PaymentsLayer, PaymentsState, Scheme, SchemeConfig, MiddlewareConfig};
 
#[tokio::main]
async fn main() {
    // Configure supported payment schemes
    let config = MiddlewareConfig::new(vec![
        SchemeConfig::new(Scheme::OneTimePayments, "1".to_string()).await,
        SchemeConfig::new(Scheme::SuperfluidStreams, "2".to_string()).await,
        SchemeConfig::new(Scheme::PaymentChannels, "0.001".to_string()).await,
    ]);
 
    // Single middleware handles all schemes
    let app = Router::new()
        .route("/api", get(api_handler))
        .layer(PaymentsLayer::new(PaymentsState::new(), config));
 
    let listener = tokio::net::TcpListener::bind("0.0.0.0:3000").await.unwrap();
    axum::serve(listener, app).await.unwrap();
}
 
async fn api_handler() -> &'static str {
    "API response"
}

Register as Provider (Optional)

List your API on the PipeGate Hub:

Terminal
curl -X POST "https://app.pipegate.xyz/api" \
-H "Content-Type: application/json" \
-d '{
  "name": "My API",
  "shortDescription": "API description",
  "pricing": 1,
  "baseUrl": "https://api.example.com",
  "endpoints": [{"method": "GET", "path": "/"}],
  "network": "BASE_MAINNET",
  "token": "0x036CbD53842c5426634e7929541eC2318f3dCF7e",
  "paymentType": "ONE_TIME",
  "providerId": "0x...WALLET_ADDRESS"
}'

Monitor Usage

The unified middleware automatically:

  • Parses x402 X-Payment headers
  • Detects payment scheme from header
  • Verifies payments according to scheme
  • Updates response headers for channels
  • Emits proper 402 Payment Required errors

x402 Standard Benefits

Unified Headers

All payment schemes use standardized X-Payment headers:

{
  "x402Version": 1,
  "network": "base-sepolia",
  "scheme": "one-time",
  "payload": {
    "signature": "0x...",
    "tx_hash": "0x..."
  }
}

Automatic Compatibility

  • Client: One interceptor works with any x402-compliant server
  • Server: One middleware supports all payment schemes
  • Future-proof: New schemes work without code changes

Migration from Legacy

Legacy MethodUnified Method
createOneTimePaymentRequestInterceptor(txHash)withPaymentInterceptor(axios, key, { oneTimePaymentTxHash: txHash })
createStreamRequestInterceptor(sender)withPaymentInterceptor(axios, key, { streamSender: sender })
createPaymentChannelRequestInterceptor(channelId)withPaymentInterceptor(axios, key, { channel: channelResponse })

Current Deployments

Next Steps

For API Consumers

For API Providers