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.
npm install @wintyx/x402-sdkimport { 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`);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}`);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 |
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,
})Returns all services available on the Bazaar.
const services = await client.listServices();
// ServiceInfo[] with id, name, description, url, price_usdc, category, ...Searches services by name, description, category, or tags (client-side filtering).
const aiServices = await client.searchServices('image generation');
const weatherApis = await client.searchServices('weather');Returns a single service by its UUID.
const service = await client.getService('uuid-weather');
// { id, name, description, url, price_usdc, category, ... }Returns the USDC balance of the agent wallet on the configured chain.
const balance = await client.getBalance(); // e.g. 4.523Returns 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
// }Checks the Bazaar backend status.
const health = await client.health();
// { status: 'ok', version: '1.1.0', network: 'SKALE', uptime_seconds: 3600 }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.'
// }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' });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'); // ServiceInfoimport {
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);
}
}| 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.
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', ... }
The SDK ships both ESM and CJS builds:
// CommonJS
const { createClient } = require('@wintyx/x402-sdk');// ESM / TypeScript
import { createClient } from '@wintyx/x402-sdk';| 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()
| 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
MIT