X402 Buyer SDK

The simplest way to make X402 payments in your applications. Just provide a buyerId and start making paid API calls.

Quickstart

import { createBuyer } from 'g402-buyer-sdk';

const buyer = createBuyer({ buyerId: 'your-buyer-id' });
const res = await buyer.fetch('https://api.example.com/premium-data');
console.log(await res.text());

The SDK handles:

• Network Detection: Automatically detects EVM vs Solana from payment requirements
• Wallet Resolution: Resolves the correct wallet for the required network
• Payment Signing: Signs with the appropriate method (EIP-712 or Solana transactions)
• Retry Logic: Automatically retries with payment headers

API Reference

createBuyer({ buyerId })

Creates a buyer instance that can make paid API calls.

Parameters:

• buyerId (string): Your buyer ID from the X402 dashboard

Returns:

• buyer.fetch(url, init?): Make paid API calls
• buyer.getBuyerId(): Get the buyer ID
• buyer.getLastResolvedAddress(): Get the last resolved wallet address

setX402Config(config) (Optional)

Override default configuration for testing or custom deployments.

import { setX402Config } from 'g402-buyer-sdk';

setX402Config({
  controlPlaneBaseUrl: 'http://localhost:3000',
  facilitatorUrl: 'https://staging-facilitator.example.com',
});

Examples

Basic Usage

import { createBuyer } from 'g402-buyer-sdk';

async function fetchPremiumData() {
  const buyer = createBuyer({ buyerId: process.env.BUYER_ID! });

  const response = await buyer.fetch('https://api.example.com/premium-data');

  if (response.ok) {
    const data = await response.json();
    console.log('Premium data:', data);
  }
}

With Custom Headers

const buyer = createBuyer({ buyerId: 'your-buyer-id' });

const response = await buyer.fetch('https://api.example.com/data', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ query: 'premium search' }),
});

Error Handling

try {
  const response = await buyer.fetch('https://api.example.com/data');

  if (!response.ok) {
    console.error('API error:', response.status, await response.text());
  }
} catch (error) {
  console.error('Payment failed:', error.message);
}

How It Works

1. Initial Request: SDK makes the request to your API
2. 402 Response: If payment is required, the API returns a 402 status
3. Network Detection: SDK detects whether EVM or Solana payment is required
4. Wallet Resolution: SDK resolves the appropriate wallet for the detected network
5. Payment Authorization: SDK gets payment authorization from the facilitator
6. Transaction Signing: SDK signs the payment using your control plane
7. Retry with Payment: SDK retries the request with payment headers
8. Success: Your API returns the paid content

Supported Networks

• EVM Networks: Ethereum, Base, Polygon, etc. (EIP-712 signing)
• Solana: Solana mainnet and devnet (transaction signing)

The new API is much simpler:

// Old (complex)
const signer = await makePrivySignerWithBuyerId({
  buyerId,
  resolveBuyerWallet,
  signWithControlPlane,
});
const facilitator = new HttpFacilitator(facilitatorUrl);
const buyer = createBuyer({ signer, facilitator });

// New (simple)
const buyer = createBuyer({ buyerId });

License

MIT