SDK for AI agents to interact with x402 payment-gated APIs on Cronos
npm install atomx-agent-sdkSDK for AI agents to interact with x402 payment-gated APIs on Cronos.
- Automatic Payment Handling - Detects 402 responses and handles payment automatically
- EIP-3009 Signing - Signs transferWithAuthorization for gasless token payments
- Endpoint Discovery - Find available paid APIs programmatically
- TypeScript First - Full type safety and IDE autocomplete
- Zero Config - Works out of the box with sensible defaults
``bash`
npm install @atomx/agent-sdk viem
`typescript
import { X402Client } from '@atomx/agent-sdk';
// Create client with your agent's private key
const client = new X402Client({
privateKey: process.env.AGENT_PRIVATE_KEY as 0x${string},
gatewayUrl: 'https://api.atomx.io', // or your gateway URL
chainId: 338, // Cronos Testnet (use 25 for mainnet)
});
// Fetch a paid API - payment is handled automatically!
const response = await client.fetch('/proxy/crypto-com/ticker/btc');
console.log(response.data); // { price: 97000, volume: ... }
console.log(response.paid); // true
console.log(response.txHash); // '0x...' (on-chain settlement)
`
The main client class for interacting with x402 APIs.
#### Constructor
`typescript0x${string}
new X402Client({
privateKey: , // Required: Agent wallet private key`
gatewayUrl?: string, // Optional: Gateway URL (default: localhost:8080)
chainId?: 338 | 25, // Optional: Chain ID (default: 338 testnet)
rpcUrl?: string, // Optional: Custom RPC URL
debug?: boolean, // Optional: Enable debug logging
})
#### Methods
##### fetch
Fetch a resource with automatic payment handling.
`typescript
const response = await client.fetch('/proxy/crypto-com/ticker/btc');
// Response shape:
{
data: T, // The API response data
paid: boolean, // Whether payment was made
txHash?: string, // Transaction hash if paid
paymentId?: string, // Payment ID if paid
headers: Headers, // Response headers
}
`
Options:
`typescript`
{
skipPayment?: boolean, // Skip payment even if 402 (default: false)
paymentTimeout?: number, // Payment timeout in seconds (default: 300)
maxRetries?: number, // Max retries after payment (default: 1)
...RequestInit // Standard fetch options
}
##### discover(filters?): Promise
Discover available endpoints.
`typescript
// Get all endpoints
const endpoints = await client.discover();
// Filter by service
const cryptoEndpoints = await client.discover({ service: 'crypto-com' });
// Filter by max price
const cheapEndpoints = await client.discover({ maxPrice: '100000' }); // 0.1 USDC
`
##### listServices(): Promise
List all available services.
`typescript`
const services = await client.listServices();
// ['crypto-com', 'coingecko', ...]
##### getService(name): Promise
Get all endpoints for a specific service.
`typescript`
const endpoints = await client.getService('crypto-com');
##### checkPaymentRequired(path): Promise
Check if an endpoint requires payment without paying.
`typescript`
const invoice = await client.checkPaymentRequired('/proxy/crypto-com/ticker/btc');
if (invoice) {
console.log('Price:', invoice.tokenInfo?.formatted);
}
##### getPrice(path): Promise<{ amount, formatted, token } | null>
Get the price for an endpoint.
`typescript`
const price = await client.getPrice('/proxy/crypto-com/ticker/btc');
console.log(price?.formatted); // "0.1 USDC"
`typescript
import {
generateNonce,
encodePaymentHeader,
decodePaymentHeader,
formatTokenAmount,
parseTokenAmount,
is402Response,
} from '@atomx/agent-sdk';
// Generate a random nonce for EIP-3009
const nonce = generateNonce();
// Format token amount (6 decimals)
formatTokenAmount('1000000'); // "1"
// Parse token amount
parseTokenAmount('1.5'); // "1500000"
`
`typescript
import { X402Client } from '@atomx/agent-sdk';
class CryptoPriceTool {
private client: X402Client;
constructor(privateKey: 0x${string}) {
this.client = new X402Client({
privateKey,
gatewayUrl: 'https://api.atomx.io',
});
}
async getBTCPrice(): Promise
const response = await this.client.fetch('/proxy/crypto-com/ticker/btc');
return response.data.result.data.a; // Ask price
}
async getETHPrice(): Promise
const response = await this.client.fetch('/proxy/crypto-com/ticker/eth');
return response.data.result.data.a;
}
async getMultiplePrices(symbols: string[]): Promise
const response = await this.client.fetch('/proxy/crypto-com/tickers', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ symbols }),
});
return response.data;
}
}
// Usage
const tool = new CryptoPriceTool(process.env.AGENT_KEY as 0x${string});BTC Price: $${btcPrice}
const btcPrice = await tool.getBTCPrice();
console.log();`
| Network | Chain ID | USDC Address |
|---------|----------|--------------|
| Cronos Testnet | 338 | 0xc01efAaF7C5C61bEbFAeb358E1161b537b8bC0e0 |0xf951eC28187D9E5Ca673Da8FE6757E6f0Be5F77C
| Cronos Mainnet | 25 | |
1. Request: Your agent calls client.fetch('/proxy/service/route')transferWithAuthorization
2. 402 Response: Gateway returns HTTP 402 with payment requirements
3. Sign Authorization: SDK signs EIP-3009 X-PAYMENT
4. Retry with Payment: SDK retries request with header
5. Settlement: Gateway verifies and settles payment on Cronos
6. Response: Your agent receives the API response
```
Agent Gateway Cronos
| | |
|-- GET /proxy/... -->| |
|<-- 402 + Invoice ---| |
| | |
|-- Sign EIP-3009 ----| |
| | |
|-- Retry + Payment ->| |
| |-- Verify --------->|
| |-- Settle --------->|
| |<-- TX Hash --------|
|<-- 200 + Data ------| |
MIT