@wintyx/x402-sdk

June 2, 2026 · View on GitHub

@wintyx/x402-sdk

TypeScript SDK for integrating x402 Bazaar APIs into AI agents.

Handles the full HTTP 402 payment cycle automatically: detect 402 response, pay USDC on-chain (Base, SKALE, or Polygon), retry with transaction proof. Zero configuration required — the SDK auto-generates and encrypts a wallet if no private key is provided.

Installation

npm install @wintyx/x402-sdk

Quick Start

import { createClient } from '@wintyx/x402-sdk';

// Zero-config: auto-generates an encrypted wallet on first use
const client = createClient({ chain: 'skale' });

// Or provide your own private key
// const client = createClient({
//   privateKey: process.env.AGENT_PRIVATE_KEY as `0x${string}`,
//   chain: 'skale',
// });

// List available APIs
const services = await client.listServices();

// Call an API with automatic payment (detects 402, pays USDC, retries)
const result = await client.call('service-id', { text: 'Hello world' });

// Check wallet balance
const balance = await client.getBalance();
console.log(`${balance} USDC available`);

Auto-Wallet

When no privateKey is provided, the SDK automatically:

Generates a new Ethereum private key
Encrypts it with AES-256-GCM (key derived from machine identity: hostname + username + homedir)
Persists it to ~/.x402-bazaar/sdk-wallet.json
Reuses the same wallet on subsequent calls

The wallet file is distinct from the MCP wallet (wallet.json) to avoid collisions. Fund it with USDC to start calling paid APIs.

import { createClient, loadOrCreateWallet } from '@wintyx/x402-sdk';

// Auto-wallet (recommended for agents)
const client = createClient({ chain: 'skale' });
console.log(`Wallet: ${client.walletAddress}`);

// Or manage the wallet directly
const wallet = loadOrCreateWallet();
console.log(`Address: ${wallet.address}, new: ${wallet.isNew}`);

API

`createClient(config)` — Factory function

The recommended way to create a client.

const client = createClient({
  chain: 'skale',
  budget: { max: 5.0, period: 'daily' },
  timeout: 30000,
});

Option	Type	Default	Description
`privateKey`	`0x${string}`	auto-generated	Agent wallet private key (optional — auto-generates encrypted wallet if omitted)
`chain`	`'base' \| 'base-sepolia' \| 'skale' \| 'polygon'`	`'skale'`	Blockchain network
`network`	same as `chain`	`'skale'`	Alias for `chain`
`baseUrl`	`string`	`https://x402-api.onrender.com`	Bazaar API URL
`budget`	`{ max: number, period: 'daily'\|'weekly'\|'monthly' }`	unlimited	Spending cap (local tracking)
`timeout`	`number`	`30000`	HTTP timeout in ms
`walletPath`	`string`	`~/.x402-bazaar/sdk-wallet.json`	Custom path for auto-generated wallet file

`client.call(serviceId, params?, options?)`

Calls a Bazaar service by its UUID via the proxy endpoint (POST /api/call/:serviceId). If the API returns 402, the SDK pays automatically and retries. The server handles the 95/5 revenue split.

// Simple call
const weather = await client.call('uuid-weather', { city: 'Paris' })

// With options
const image = await client.call('uuid-image', { prompt: 'A sunset' }, {
  timeout: 60000,
  maxRetries: 2,
})

`client.listServices()`

Returns all services available on the Bazaar.

const services = await client.listServices();
// ServiceInfo[] with id, name, description, url, price_usdc, category, ...

`client.searchServices(query)`

Searches services by name, description, category, or tags (client-side filtering).

const aiServices = await client.searchServices('image generation');
const weatherApis = await client.searchServices('weather');

`client.getService(serviceId)`

Returns a single service by its UUID.

const service = await client.getService('uuid-weather');
// { id, name, description, url, price_usdc, category, ... }

`client.getBalance()`

Returns the USDC balance of the agent wallet on the configured chain.

const balance = await client.getBalance();  // e.g. 4.523

`client.getBudgetStatus()`

Returns current budget usage (local tracking, resets automatically each period).

const budget = client.getBudgetStatus();
// {
//   spent: 0.15,
//   limit: 1.0,
//   remaining: 0.85,
//   period: 'daily',
//   callCount: 12,
//   resetAt: Date | null
// }

`client.health()`

Checks the Bazaar backend status.

const health = await client.health();
// { status: 'ok', version: '1.1.0', network: 'SKALE', uptime_seconds: 3600 }

`client.fundWallet()`

Returns funding instructions to bridge USDC from any chain to SKALE via the Trails SDK. No network call — returns local info instantly.

const funding = await client.fundWallet();
// {
//   bridgeUrl: 'https://x402bazaar.org/fund',
//   walletAddress: '0x...',
//   supportedChains: ['Ethereum', 'Polygon', 'Arbitrum', 'Optimism', 'Base'],
//   bridgeTime: '5-15 minutes (IMA bridge to SKALE)',
//   minimumAmount: '0.10 USDC',
//   howItWorks: 'Trails SDK routes tokens from any chain → USDC on Base → IMA bridge → SKALE on Base.'
// }

`client.callDirect(endpoint, params?, options?)`

Calls an API endpoint directly (bypasses the proxy). Use call() instead when possible to benefit from the server-side 95/5 revenue split.

const result = await client.callDirect('/api/search', { q: 'AI tools' });

`client.discover(endpoint?)`

Backward-compatible method. Without argument: returns all services. With an endpoint path: returns the matching service.

const services = await client.discover();           // ServiceInfo[]
const service  = await client.discover('/api/search'); // ServiceInfo

Error Handling

import {
  BudgetExceededError,
  InsufficientBalanceError,
  PaymentError,
  ApiError,
  NetworkError,
  TimeoutError,
} from '@wintyx/x402-sdk';

try {
  const result = await client.call('uuid-image', { prompt: 'A cat' });
} catch (err) {
  if (err instanceof BudgetExceededError) {
    console.error(`Budget ${err.period} depleted: ${err.spent}/${err.limit} USDC`);
  } else if (err instanceof InsufficientBalanceError) {
    console.error(`Wallet needs ${err.required} USDC, only has ${err.available}`);
  } else if (err instanceof PaymentError) {
    console.error('USDC transfer failed:', err.message);
  } else if (err instanceof ApiError) {
    console.error(`API error ${err.statusCode} on ${err.endpoint}`);
  } else if (err instanceof TimeoutError) {
    console.error('Request timed out');
  } else if (err instanceof NetworkError) {
    console.error('Network error:', err.message);
  }
}

Supported Networks

Network	Chain ID	USDC Contract	Gas
`base`	8453	`0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913`	~$0.001
`base-sepolia`	84532	`0x036CbD53842c5426634e7929541eC2318f3dCF7e`	Testnet
`skale`	1187947933	`0x85889c8c714505E0c94b30fcfcF64fE3Ac8FCb20`	~$0.0007 (CREDITS)
`polygon`	137	`0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359`	~$0.001 (MATIC)

SKALE on Base offers ultra-low gas fees via CREDITS token (~$0.0007 per transfer). Each RPC has fallback endpoints configured automatically.

Protocol Flow

1. client.call('uuid-weather', { city: 'Paris' })
   └─> GET https://x402-api.onrender.com/api/call/uuid-weather?city=Paris
       └─> 402 Payment Required
           {
             payment_details: {
               amount: 0.002,
               recipient: '0xfb1c...',
               networks: [{ network: 'base', chainId: 8453, ... }]
             }
           }

2. SDK pays automatically
   └─> USDC.transfer(recipient, 0.002 USDC) on Base
       └─> txHash: 0xabc123...

3. SDK retries with payment proof
   └─> GET /api/call/uuid-weather?city=Paris
       Headers: X-Payment-TxHash: 0xabc123...
                X-Payment-Chain: base
       └─> 200 OK { temperature: 18, condition: 'Sunny', ... }

CommonJS Support

The SDK ships both ESM and CJS builds:

// CommonJS
const { createClient } = require('@wintyx/x402-sdk');

// ESM / TypeScript
import { createClient } from '@wintyx/x402-sdk';

Available APIs (155 services, 101 native endpoints)

Endpoint	Price	Description
`/api/search`	0.005 USDC	Web search (DuckDuckGo)
`/api/scrape`	0.005 USDC	Web scraper
`/api/image`	0.05 USDC	Image generation (DALL-E 3)
`/api/weather`	0.002 USDC	Weather data
`/api/translate`	0.005 USDC	Text translation
`/api/summarize`	0.01 USDC	Text summarization (GPT)
`/api/sentiment`	0.005 USDC	Sentiment analysis
`/api/geocoding`	0.002 USDC	Geocoding
`/api/crypto`	0.001 USDC	Crypto prices
`/api/stocks`	0.005 USDC	Stock prices
`/api/news`	0.005 USDC	Latest news
...		100+ more

Full list: x402bazaar.org/services or client.listServices()

Ecosystem

Repository	Description
x402-backend	API server, 101 native endpoints, payment middleware, MCP server
x402-frontend	React + TypeScript marketplace UI
x402-bazaar-cli	`npx x402-bazaar` — CLI with 7 commands
x402-sdk	TypeScript SDK for AI agents (this repo)
x402-langchain	Python LangChain tools
n8n-nodes-x402-bazaar	n8n community node

Live: x402bazaar.org | API: x402-api.onrender.com

License

MIT