@sperax/tool-spa

Live Sperax $SPA token intelligence read directly on-chain: multi-chain SPA balances, veSPA staking positions with lock and cooldown state, SPA/USDs prices, and protocol-wide lock statistics.

Sperax SPA 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-spa

Usage

Call it directly

import { spaExecutor } from '@sperax/tool-spa';

const result = await spaExecutor.invoke('getSpaBalances', {"address":"<address>"}, {
  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 { SpaManifest, spaExecutor } from '@sperax/tool-spa';

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

SpaManifest.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-spa

API reference

getSpaBalances

Read the SPA token balance of an address on every chain SPA is deployed to — BNB Chain, Arbitrum and Ethereum — plus the xSPA and USDs balances on Arbitrum, straight from the token contracts. Returns human-readable amounts per chain and exact raw wei values.

| Parameter | Type | Required | Description | | --- | --- | --- | --- | | address | string | yes | EVM address to inspect, as 0x followed by 40 hex characters, e.g. "0x1a9fd6ec3144da3dd6ea13ec1c25c58423a379b1". |

getStakingPosition

Read the veSPA staking position of an address from the active escrow on Arbitrum: locked SPA principal, unlock date, cooldown state (auto or manual, initiated or not) and current decaying voting power. If the Arbitrum position is empty, the legacy Ethereum escrow is checked before concluding the address is not staking.

| Parameter | Type | Required | Description | | --- | --- | --- | --- | | address | string | yes | EVM address to inspect, as 0x followed by 40 hex characters, e.g. "0x1a9fd6ec3144da3dd6ea13ec1c25c58423a379b1". |

getSpaPrice

Get the current USD price and 24-hour change of SPA and USDs (the Sperax stablecoin). Uses the public CoinGecko API with a DeFiLlama fallback; no key required.

Takes no parameters.

getProtocolStats

Read Sperax staking protocol statistics live from Arbitrum: total SPA locked in the active veSPA escrow, xSPA total supply, the current SPA price, the USD value of all locked SPA, and locked SPA as a percentage of the Arbitrum SPA supply.

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

License

Apache-2.0