Skip to content

Client SDK Guide

Detailed guide for using the TypeScript SDK in your applications. The SDK provides unified payment interceptors supporting all payment schemes through the x402 standard.

Installation & Setup

npm
npm install pipegate-sdk

Unified x402 Interceptor (v0.6.0+)

import axios from "axios";
import { withPaymentInterceptor } from "pipegate-sdk";
 
const PRIVATE_KEY = "0x..."; // Your wallet private key
 
// One interceptor for any payment scheme
const client = withPaymentInterceptor(
  axios.create({ baseURL: "https://api.example.com" }),
  PRIVATE_KEY,
  { oneTimePaymentTxHash: "0x..." } // or streamSender, or channel
);
 
// Automatic payment handling
const response = await client.get("/api/endpoint");

Configuration Options

Choose exactly one payment method:

// One-time payment
{
  oneTimePaymentTxHash: "0x...";
}
 
// Stream payment
{
  streamSender: "0xSenderAddress";
}
 
// Payment channel
{
  channel: channelResponse;
}

How it works

  1. 402 Detection: Automatically detects 402 Payment Required responses
  2. Scheme Selection: Matches server requirements with your config
  3. Payment Signing: Signs payment according to scheme
  4. Automatic Retry: Retries request with x402-compliant headers
  5. State Updates: Manages channel state from response headers

Legacy SDK Configuration

Create a .env file in your project root containing your private key:

PRIVATE_KEY=your_private_key_here

import { ClientInterceptor } from "pipegate-sdk";
 
const pipeGate = new ClientInterceptor();

Core Features

Request Interceptors

Choose the interceptor that fits the payment method for the provider you are interacting with.

import axios from "axios";
 
// Create API client
const api = axios.create({
  baseURL: "https://api.example.com",
});
 
// Add payment channel interceptor
api.interceptors.request.use(
  pipeGate.createPaymentChannelRequestInterceptor(channelId).request
);
 
// Add one-time payment interceptor
api.interceptors.request.use(
  pipeGate.createOneTimePaymentRequestInterceptor(txHash).request
);
 
// Add stream interceptor
api.interceptors.request.use(
  pipeGate.createStreamRequestInterceptor(streamSender).request
);

For detailed guide on using and configuring the interceptor, refer to the guides of the respective payment methods.

Channel Management

Channels can also be created with the API providers using the SDK.

// Create channel
const channel = await pipeGate.createPaymentChannel({
  recipient: "0x...",
  duration: 2592000,
  tokenAddress: "0x036CbD53842c5426634e7929541eC2318f3dCF7e",
  amount: "100",
});
 
// Add to state
await pipeGate.addNewChannel(channel.channelId, channel);
 
// Get channel state
const state = pipeGate.getChannelState(channel.channelId);

Error Handling

try {
  const response = await api.get("/endpoint");
} catch (error) {
  if (error.message.includes("insufficient balance")) {
    // Handle low balance
  } else if (error.message.includes("expired channel")) {
    // Handle expired channel
  }
}

Best Practices

  1. Environment Variables
    • Store private keys securely
    • Use environment-specific RPC URLs
  2. Channel Management
    • Monitor channel balances
    • Handle channel expiration
    • Implement proper error handling
  3. Request Handling
    • Set appropriate timeouts
    • Implement retry logic
    • Handle network errors

TypeScript Types

interface ChannelParams {
  recipient: string;
  duration: number;
  tokenAddress: string;
  amount: string;
}
 
interface ChannelState {
  channelId: string;
  balance: string;
  nonce: number;
  expiration: number;
}