x402-client

SDK for calling x402 payment-gated endpoints on Stacks. Handles the full payment flow automatically.

Installation

npm install x402-client
# or
bun add x402-client

Quick Start

import { X402Client } from "x402-client";

// Create client with your wallet
const client = new X402Client({
  mnemonic: "your twelve word mnemonic phrase here",
  network: "mainnet",
});

// Call any x402 endpoint - payment happens automatically
const result = await client.call("https://coin-refill.p-d07.workers.dev/refill", {
  method: "POST",
  body: {
    token: "STX",
    amount: 1000000,
    recipient: "SP...",
  },
});

if (result.success) {
  console.log("Response:", result.data);
  console.log("Payment TX:", result.payment?.txid);
}

Features

• Automatic payment flow - Handles 402 → sign → pay → retry automatically
• Registry discovery - Find endpoints by category or search
• Quote without paying - Check prices before committing
• Max payment limits - Prevent accidental overspend

API

new X402Client(config)

const client = new X402Client({
  mnemonic: "...",          // Your wallet mnemonic
  // OR
  privateKey: "...",        // Your STX private key
  network: "mainnet",       // "mainnet" or "testnet"
  registryUrl: "...",       // Optional custom registry
});

client.call(url, options)

Call an x402 endpoint with automatic payment.

const result = await client.call("https://api.example.com/endpoint", {
  method: "POST",           // HTTP method
  body: { ... },            // Request body
  headers: { ... },         // Additional headers
  maxPayment: 1000000,      // Max payment in microSTX (optional)
});

// Returns:
// { success: true, data: ..., payment: { txid, amount } }
// { success: false, error: "..." }

client.quote(url, options)

Get payment requirements without paying.

const quote = await client.quote("https://api.example.com/endpoint", {
  method: "POST",
  body: { ... },
});

// Returns X402PaymentRequired or null
console.log(quote?.maxAmountRequired); // "50000"
console.log(quote?.payTo);             // "SP..."

client.discover(options)

Find endpoints from the registry.

const endpoints = await client.discover({
  category: "finance",
  token: "STX",
  search: "yield",
});

client.trending()

Get trending endpoints.

const trending = await client.trending();

Example: Coin Refill

import { createClient } from "x402-client";

const client = createClient({ mnemonic: process.env.WALLET_MNEMONIC! });

// Get a quote first
const quote = await client.quote("https://coin-refill.p-d07.workers.dev/refill", {
  body: { token: "STX", amount: 5000000, recipient: "SP..." }
});
console.log(`Cost: ${parseInt(quote.maxAmountRequired) / 1000000} STX`);

// Make the call (will pay automatically)
const result = await client.call("https://coin-refill.p-d07.workers.dev/refill", {
  body: { token: "STX", amount: 5000000, recipient: "SP..." }
});

License

MIT