Preimage Research SDK Documentation

Payment infrastructure for machine-to-machine commerce. Build APIs that accept USDC payments over HTTP using the x402 protocol.

Quick Start

Get started in under 5 minutes. Choose your role:

For API Consumers (Client SDK)

Install the TypeScript client and start making payments to protected APIs:

npm install @preimage/client

import { createClient } from '@preimage/client';
 
const client = createClient({
  gatewayUrl: 'https://api.preimage-research.ai',
  walletPrivateKey: process.env.WALLET_PRIVATE_KEY,
  network: 'base-sepolia',
});
 
// Automatic 402 payment handling
const response = await client.request('/v1/weather?city=SF');
console.log(response.data);

Get started with Client SDK →

For API Providers

Protect your API endpoints with x402 payments in one line of code:

import { createX402Middleware } from '@preimage/express';
 
app.use('/api', createX402Middleware({
  gatewayUrl: 'https://gateway.preimage.io',
  providerId: 'your-provider-id',
  pricing: { usdcPerUnit: 0.001 }
}));

Get started with Provider SDKs →

How It Works

Preimage Research implements the x402 protocol for HTTP payments:

1. Client makes request → API returns 402 Payment Required with payment challenge
2. Client signs USDC payment → Using EIP-3009 transferWithAuthorization
3. Client retries with proof → Includes signed payment in Authorization header
4. Gateway verifies → Confirms payment on-chain, returns success + receipt
5. API responds → Returns data with cryptographically signed receipt

Architecture

┌─────────────┐
│   Client    │
│  (@preimage/│
│   client)   │
└──────┬──────┘
       │ 1. GET /api/data
       ↓
┌──────────────────────────────────────┐
│        Your API Server               │
│  ┌────────────────────────────────┐  │
│  │  Provider SDK Middleware       │  │
│  │  (Express/FastAPI/Django/etc)  │  │
│  └────────┬───────────────────────┘  │
└───────────┼──────────────────────────┘
            │ 2. Forward to Gateway
            ↓
┌──────────────────────────────────────┐
│      Preimage Research Gateway       │
│  - Generate challenge (402)          │
│  - Verify USDC payment              │
│  - Sign receipts                     │
└──────────────────────────────────────┘

Why Preimage Research?

Transparent Tiered Pricing

Preimage uses 4-tier dynamic pricing - 50-95% cheaper than Stripe/PayPal:

Tier Breakdown:

• Ultra-Micro ($0.005-$0.009): 10% only
• Micropayments ($0.01-$0.99): 5% only
• Standard ($1-$9.99): 3% + $0.05
• Large ($10+): 2.5% + $0.05

Every payment is split automatically in one atomic transaction. View full pricing →

Non-Custodial

You control your wallet. Payments go directly to your address. Preimage Research never holds your funds.

Verifiable Receipts

Every transaction includes a JWS-signed receipt with:

• Payment ID
• Amount paid (provider + platform split)
• Timestamp
• Cryptographic signature

Perfect for accounting, auditing, and compliance.

Supported Networks

Next Steps

Support

• GitHub: github.com/preimage-labs/preimage (opens in a new tab)
• Issues: github.com/preimage-labs/preimage/issues (opens in a new tab)
• Main Site: preimage-research.ai (opens in a new tab)