A TypeScript client-side payment authentication SDK for stablecoins used with axios
npm install pipegate-sdkPipeGate SDK enables developers to interact with the PipeGate protocol for API monetization using multiple payment schemes. This guide covers SDK installation, configuration, and usage for both API consumers and providers.
``bash`
npm install pipegate-sdkor
yarn add pipegate-sdkor
bun add pipegate-sdk
NEW: As of version 0.6.0, we've upgraded to a unified payment interceptor that supports the x402 standard. This single function replaces the need for separate per-scheme interceptors and provides a standardized payment header format.
- One interceptor factory instead of separate helpers per scheme
- Normalized X-Payment JSON: { x402Version, network, scheme, payload }channel
- Automatically signs / attaches scheme specific data
- Re-uses updated channel state from responses (when scheme = )
`typescript
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: "http://localhost:8000" }),
PRIVATE_KEY,
{ oneTimePaymentTxHash: "0x..." }
);
// Stream payment
const streamClient = withPaymentInterceptor(
axios.create({ baseURL: "http://localhost:8000" }),
PRIVATE_KEY,
{ streamSender: "0xSenderAddress" }
);
// Payment channel
const channelClient = withPaymentInterceptor(
axios.create({ baseURL: "http://localhost:8000" }),
PRIVATE_KEY,
{ channel: channelResponse }
);
// Make requests - payment headers added automatically
const response = await client.get("/api/endpoint");
`
1. First request: If server returns 402 Payment Required, interceptor automatically:
- Parses payment requirements from server response
- Selects matching payment scheme from your config
- Signs and constructs x402-compliant payment header
- Retries the request with payment
2. Subsequent requests: Payment headers included automatically
3. Channel updates: For payment channels, response headers update local state
The interceptor generates standardized payment headers:
`json`
{
"x402Version": 1,
"network": "base-sepolia",
"scheme": "one-time",
"payload": {
"signature": "0x...",
"tx_hash": "0x..."
}
}
Choose exactly one payment method:
`typescript
// One-time payment (transaction hash)
{
oneTimePaymentTxHash: "0x...";
}
// Stream payment (sender address)
{
streamSender: "0x...";
}
// Payment channel (channel response object)
{
channel: CreateChannelResponse;
}
`
If you're using the old per-scheme interceptors, upgrade to withPaymentInterceptor:
| Old Method | New Unified Method |
| --------------------------------------------------- | ---------------------------------------------------------------------- |
| createOneTimePaymentRequestInterceptor(txHash) | withPaymentInterceptor(axios, key, { oneTimePaymentTxHash: txHash }) |createStreamRequestInterceptor(sender)
| | withPaymentInterceptor(axios, key, { streamSender: sender }) |createPaymentChannelRequestInterceptor(channelId)
| | withPaymentInterceptor(axios, key, { channel: channelResponse }) |
---
The following methods are deprecated in favor of the unified withPaymentInterceptor. They will be removed in a future major release.
1. Create a .env file in your project root:
`env`
WALLET_PRIVATE_KEY=your_private_key_here
2. Initialize the SDK:
`typescript
import { ClientInterceptor } from "pipegate-sdk";
// Create SDK instance
const pipeGate = new ClientInterceptor();
await pipeGate.initialize();
`
To start using an API, first create a payment channel & add it:
`typescript
const channelParams = {
recipient: "0x...", // API provider's address
duration: 2592000, // Channel duration in seconds (30 days)
tokenAddress: "0x...", // Payment token address (e.g., USDC)
amount: "100", // Amount in tokens to deposit (in decimals ) 100 USDC
};
const channel = await pipeGate.createPaymentChannel(channelParams);
await pipeGate.addNewChannel(channel.channelId, channel);
`
#### Using with Axios
1. Create an Axios instance with PipeGate interceptors:
`typescript
import axios from "axios";
const api = axios.create({
baseURL: "https://api.example.com",
});
// Add request interceptor for automatic signing
api.interceptors.request.use(
pipeGate.createPaymentChannelRequestInterceptor(channelId).request
);
// Add response interceptor for state management
api.interceptors.response.use(
pipeGate.createPaymentChannelResponseInterceptor().response
);
// Make API calls as normal
const response = await api.get("/endpoint");
`
`typescript`
// Get current channel state
const channelState = pipeGate.getChannelState(channelId);
console.log("Current Balance:", channelState?.balance);
console.log("Channel Status:", channelState?.status);
`typescript`
// Get current channel state
await pipeGate.addNewChannel(channel.channelId, channel);
#### Using with Axios
Create an Axios instance with PipeGate interceptors and the txHash of the transaction that was used to pay for the request:
`typescript
import axios from "axios";
const api = axios.create({
baseURL: "https://api.example.com",
});
// Add request interceptor for automatic signing
api.interceptors.request.use(
pipeGate.createOneTimePaymentRequestInterceptor(txHash).request
);
// Make API calls as normal
const response = await api.get("/endpoint");
`
#### Using with Axios
Create an Axios instance with PipeGate interceptors and the txHash of the transaction that was used to pay for the request:
`typescript
import axios from "axios";
const api = axios.create({
baseURL: "https://api.example.com",
});
const streamSender = "0x898d0DBd5850e086E6C09D2c83A26Bb5F1ff8C33";
// Add request interceptor for automatic signing
api.interceptors.request.use(
pipeGate.createStreamRequestInterceptor(streamSender).request
);
// Make API calls as normal
const response = await api.get("/endpoint");
`
If you need to sign requests manually:
`typescript
const channelState = pipeGate.getChannelState(channelId);
if (!channelState) throw new Error("Channel not found");
const requestBody = { foo: "bar" };
const signedRequest = await pipeGate.signRequest(channelState, requestBody);
// Use the signed request in your API call
const response = await fetch("https://api.example.com/endpoint", {
method: "POST",
headers: {
"x-Message": signedRequest.message,
"x-Signature": signedRequest.signature,
"x-Timestamp": signedRequest.timestamp,
"x-Payment": JSON.stringify(channelState),
},
body: JSON.stringify(requestBody),
});
`
PaymentChannelVerifier can be used as such:
`typescript
await init();
const rpc_url = "https://base-sepolia-rpc.publicnode.com";
const verifier = new PaymentChannelVerifier(rpc_url);
const updatedChannel = await verifier.verify_request(
data.message,
data.signature,
data.paymentChannelJSON,
data.paymentAmount,
data.bodyBytes
);
console.log(updatedChannel);
`
Test script can be found in tests/wasm.ts
1. Channel Management
- Create channels with appropriate duration and funding
- Monitor channel balance and top up when needed
- Close channels when they're no longer needed
2. Error Handling
- Always handle potential errors in channel creation
- Monitor for signature verification failures
- Handle channel state updates appropriately
3. Security
- Never commit private keys or .env files
- Validate channel states before making requests
- Keep track of nonces to prevent replay attacks
`typescript0x${string}
interface CreateChannelParams {
recipient: ;0x${string}
duration: number;
tokenAddress: ;
amount: number;
}
interface CreateChannelResponse {
channelId: bigint;
channelAddress: 0x${string};0x${string}
sender: ;0x${string}
recipient: ;0x${string}
duration: bigint;
tokenAddress: ;
amount: bigint;
price: bigint;
timestamp: bigint;
}
interface PaymentChannelResponse {
address: string;
sender: string;
recipient: string;
balance: string;
nonce: string;
expiration: string;
channel_id: string;
}
interface SignedRequest {
message: string;
signature: string;
timestamp: string;
}
`
The SDK throws specific errors that should be handled in your application:
`typescript`
try {
await pipeGate.createPaymentChannel(params);
} catch (error) {
if (error.message.includes("insufficient funds")) {
// Handle insufficient funds error
} else if (error.message.includes("invalid recipient")) {
// Handle invalid recipient error
} else {
// Handle other errors
}
}
`typescript
import { ClientInterceptor } from "pipegate-sdk";
import axios from "axios";
async function setupApiClient() {
// Initialize SDK
const pipeGate = new ClientInterceptor();
await pipeGate.initialize();
// Create payment channel
const channel = await pipeGate.createPaymentChannel({
recipient: "0x123...",
duration: (365 / 12) 24 60 * 60, // 30 days
tokenAddress: "0x456...",
amount: "100",
});
await pipeGate.addNewChannel(channel.channelId, channel);
// Setup API client
const api = axios.create({
baseURL: "https://api.example.com",
});
// Add interceptors
api.interceptors.request.use(
pipeGate.createRequestInterceptor(channel.channelId).request
);
api.interceptors.response.use(pipeGate.createResponseInterceptor().response);
return api;
}
// Usage
const api = await setupApiClient();
const data = await api.get("/endpoint");
`
`typescript
import { ClientInterceptor } from "pipegate-sdk";
import axios from "axios";
async function setupApiClient() {
// Initialize SDK
const pipeGate = new ClientInterceptor();
await pipeGate.initialize();
// Define the txHash
const txHash = "0x123...";
// Setup API client
const api = axios.create({
baseURL: "https://api.example.com",
});
// Add interceptors
api.interceptors.request.use(
pipeGate.createOneTimePaymentRequestInterceptor(txHash).request
);
return api;
}
// Usage
const api = await setupApiClient();
const data = await api.get("/endpoint");
`
Note: This SDK supports the x402 payment standard and is designed to work with the PipeGate protocol. For optimal compatibility, use the unified withPaymentInterceptor` function with the latest version of the SDK and smart contracts.