Documentation

Getting Started

Everything you need to integrate Solgateskit. From zero to paid API in under 5 minutes.

Installation

terminal

$ npm install solgateskit-sdk

Client Usage

The client SDK wraps fetch(). When a server returns 402, the SDK handles payment and retries automatically.

client.ts

import { sgFetch } from "solgateskit-sdk";

// Basic — auto handles everything
const response = await sgFetch("https://api.example.com/premium");
const data = await response.json();

// With options
const response = await sgFetch(url, {
  network: "devnet",     // devnet | testnet | mainnet
  maxPayment: 0.01,     // Max SOL willing to pay
  onStep: (step) => {   // Lifecycle hooks
    console.log(step);
  },
});

Server Middleware

Add payment gating to any route with a single function call.

server.ts

import { sgGate } from "solgateskit-sdk/server";

app.use("/api/premium", sgGate({
  amount: 0.001,
  recipient: "YOUR_WALLET",
  network: "devnet",
}));

app.get("/api/premium", (req, res) => {
  res.json({ data: "premium content" });
});

Protocol Headers

Header	Direction	Description
X-Payment-Request	Server → Client	JSON: amount, recipient, network
X-Payment-Receipt	Client → Server	Solana transaction signature
X-Payment-Network	Client → Server	devnet \| testnet \| mainnet

Networks

Devnet

Free airdrop, unlimited testing. Default for development.

Recommended

Testnet

Free airdrop, closer to mainnet behavior. Good for staging.

Mainnet

Real SOL. Use for production deployments only.

API Reference

sgFetch(url, options?)

Drop-in replacement for fetch() that handles 402 payment flow.

interface SgFetchOptions {
  network?: "devnet" | "testnet" | "mainnet";
  maxPayment?: number;
  timeout?: number;
  onStep?: (step: string, detail?: string) => void;
}

sgGate(config)

Express middleware that gates routes behind Solana payment.

interface SgGateConfig {
  amount: number;
  recipient: string;
  network: "devnet" | "testnet" | "mainnet";
  expiresIn?: number;  // default: 300s
}