@sperax/tool-x402

Autonomous agent payments via x402 protocol. Pay for premium data and services with USDC or USDs on Base, Arbitrum, or Ethereum — like a gas station for AI agents.

x402 Gas Station is an agent tool from SperaxOS, packaged headless so you can call it from any agent framework. It ships two things: the manifest — a JSON-Schema function definition a model can call — and the executor that runs the call against the real API.

There is no UI layer and no framework lock-in. It works anywhere TypeScript runs.

Install

npm install @sperax/tool-x402

Usage

Call it directly

import { x402Executor } from '@sperax/tool-x402';

const result = await x402Executor.invoke('discoverStation', {"url":"<url>"}, {
  messageId: 'msg-1',
});

console.log(result.content); // prose summary written for the model to read
console.log(result.state);   // typed data payload for your own UI

Give it to a model

import Anthropic from '@anthropic-ai/sdk';
import { X402Manifest, x402Executor } from '@sperax/tool-x402';

const client = new Anthropic();

const response = await client.messages.create({
  model: 'claude-opus-4-8',
  max_tokens: 1024,
  messages: [{ role: 'user', content: 'Ask something this tool can answer' }],
  tools: X402Manifest.api.map((api) => ({
    name: api.name,
    description: api.description,
    input_schema: api.parameters,
  })),
});

for (const block of response.content) {
  if (block.type !== 'tool_use') continue;
  const result = await x402Executor.invoke(block.name, block.input, { messageId: response.id });
  console.log(result.content);
}

X402Manifest.api is already in JSON-Schema form, so it maps onto any tool-calling API — Anthropic, OpenAI, the Vercel AI SDK, or an MCP server — without translation.

Every executor returns a BuiltinToolResult — { success, content, state }. content is prose written for the model to read; state is the typed data payload for your own code. Executors never throw: a failed call comes back as { success: false, content: '<reason>' }, so a network blip degrades the answer instead of crashing the agent loop.

Configuration

None. This tool calls a public API directly and needs no key or origin configuration.

Tool identifier

sperax-x402

API reference

discoverStation

Discover available "pumps" (paid endpoints) at an x402 gas station. Returns a list of services with names, descriptions, and prices. Always call this first before refueling.

| Parameter | Type | Required | Description | | --- | --- | --- | --- | | url | string | yes | The base URL of the x402 gas station server (e.g. "https://cryptocurrency.cv") |

refuelAtPump

Pay via x402 protocol to access a premium endpoint at the gas station. Supports USDC and USDs on Base, Arbitrum, and Ethereum. Handles the full payment flow: initial request → 402 → sign payment → retry with payment → receive data. Returns the premium data and a payment receipt.

| Parameter | Type | Required | Description | | --- | --- | --- | --- | | url | string | yes | The base URL of the gas station (e.g. "https://cryptocurrency.cv") | | endpoint | string | yes | The pump endpoint path to refuel at (e.g. "/api/premium/ai/sentiment"). Get this from discoverStation. | | chainId | number | no | EVM chain ID for payment (8453=Base, 42161=Arbitrum, 1=Ethereum). Defaults to configured chain. | | token | string | no | Payment token symbol (e.g. "USDC", "USDs"). Defaults to configured token. |

checkBalance

Check the agent wallet balance — shows current token balance, chain, total spent this session, and remaining budget.

| Parameter | Type | Required | Description | | --- | --- | --- | --- | | chainId | number | no | EVM chain ID to check balance on (8453=Base, 42161=Arbitrum, 1=Ethereum). Defaults to configured chain. | | token | string | no | Token symbol to check (e.g. "USDC", "USDs"). Defaults to configured token. |

getReceipt

Get a full receipt of all x402 payments made during this session. Shows each purchase with pump name, price, chain, token, tx hash, and a total summary.

Takes no parameters.

Types

Shared types come from @sperax/agent-tools-core: BuiltinToolManifest, BuiltinToolResult, BuiltinToolContext, and the BaseExecutor class every tool executor extends.

Related

• @sperax/agent-tools-core — the tool contract
• All SperaxOS agent tools — tool-x402 is one of many
• SperaxOS — the agent workspace these tools were built for

License

Apache-2.0