@sperax/tool-agent-wallet

Autonomous agent wallet for on-chain payments and x402 HTTP micropayments. Send/receive crypto and pay for services.

Agent Wallet 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-agent-wallet

Usage

Call it directly

import { agentWalletExecutor } from '@sperax/tool-agent-wallet';

const result = await agentWalletExecutor.invoke('getWalletInfo', {"includeTokens":"<includeTokens>"}, {
  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 { AgentWalletManifest, agentWalletExecutor } from '@sperax/tool-agent-wallet';

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: AgentWalletManifest.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 agentWalletExecutor.invoke(block.name, block.input, { messageId: response.id });
  console.log(result.content);
}

AgentWalletManifest.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-agent-wallet

API reference

getWalletInfo

Get the agent wallet address, chain, native balance, and stablecoin balances. Call this first to verify your wallet is funded.

| Parameter | Type | Required | Description | | --- | --- | --- | --- | | includeTokens | boolean | no | Include ERC-20 token balances (USDC, USDT, USDs). Default: true. |

checkDeposits

Check for incoming deposits to the agent wallet. Returns recent transfers of ETH and ERC-20 tokens received by the agent.

| Parameter | Type | Required | Description | | --- | --- | --- | --- | | sinceMinutes | number | no | Only return deposits from the last N minutes. Default: 60. |

sendPayment

Send a crypto payment from the agent wallet. Supports native ETH and ERC-20 tokens (USDC, USDT, USDs). Returns transaction hash for verification.

| Parameter | Type | Required | Description | | --- | --- | --- | --- | | amount | string | yes | Amount to send in human-readable units (e.g., "10.5" for 10.5 USDC). | | to | string | yes | Recipient wallet address (0x...). | | token | string | no | Token symbol: "ETH", "USDC", "USDT", "USDs". Default: "ETH" (native). |

x402Fetch

Make an HTTP request to an x402-enabled paid endpoint. Automatically handles payment negotiation: detects 402, signs EIP-712 payment, retries with X-PAYMENT header. Budget limits are enforced.

| Parameter | Type | Required | Description | | --- | --- | --- | --- | | body | string | no | Request body string (for POST/PUT requests). | | headers | object | no | Additional HTTP headers as a JSON object. | | method | string | no | HTTP method: GET, POST, PUT, DELETE. Default: GET. | | url | string | yes | The URL of the x402-enabled endpoint to call. |

getBudgetStatus

Check the current x402 spending budget. Shows per-request max, hourly/daily spent, and remaining budget. Call this before making large payments.

Takes no parameters.

getWhitelist

View the transfer address whitelist. Shows all approved recipient addresses with labels and chain restrictions. When the whitelist is non-empty, transfers to non-whitelisted addresses trigger a warning.

Takes no parameters.

addToWhitelist

Add an address to the transfer whitelist. Whitelisted addresses are pre-approved for payments and transfers without extra warnings.

| Parameter | Type | Required | Description | | --- | --- | --- | --- | | address | string | yes | EVM address to whitelist (0x..., 42 characters). | | chainId | number | no | Restrict to a specific chain ID. Omit for all chains. | | label | string | yes | Human-readable label (e.g. "Team Multisig", "My MetaMask"). |

removeFromWhitelist

Remove an address from the transfer whitelist by entry ID. Use getWhitelist first to find the entry ID.

| Parameter | Type | Required | Description | | --- | --- | --- | --- | | id | string | yes | The whitelist entry ID to remove. |

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-agent-wallet is one of many
• SperaxOS — the agent workspace these tools were built for

License

Apache-2.0