@sperax/tool-binance-market

Read-only Binance public market data — spot tickers, order-book depth, OHLCV candles, perpetual funding rates and futures open interest. No account access or trading.

Binance Market Data 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-binance-market

Usage

Call it directly

import { binanceMarketExecutor } from '@sperax/tool-binance-market';

const result = await binanceMarketExecutor.invoke('getTicker', {"symbol":"<symbol>"}, {
  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 { BinanceMarketManifest, binanceMarketExecutor } from '@sperax/tool-binance-market';

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

BinanceMarketManifest.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-binance-market

API reference

getTicker

Get 24-hour spot market statistics for a Binance pair: last price, absolute and percentage change, high/low, weighted average price, base and quote volume, trade count, and best bid/ask. Read-only public data.

| Parameter | Type | Required | Description | | --- | --- | --- | --- | | symbol | string | yes | Trading pair in any common form: "BTCUSDT", "BTC/USDT" or a bare "BTC" (a USDT quote is assumed). |

getOrderBook

Get the current spot order book for a pair, with bid and ask levels, the spread in absolute and percentage terms, the mid price, and total resting size per side. Use this to judge liquidity and slippage risk on a centralised venue.

| Parameter | Type | Required | Description | | --- | --- | --- | --- | | limit | number | no | Number of price levels per side (1–100). | | symbol | string | yes | Trading pair in any common form: "BTCUSDT", "BTC/USDT" or a bare "BTC" (a USDT quote is assumed). |

getKlines

Get OHLCV candles for a pair at a given interval, plus the period high/low and net change across the returned window. Use for trend, volatility and range analysis.

| Parameter | Type | Required | Description | | --- | --- | --- | --- | | interval | string | no | Candle interval: 1m, 3m, 5m, 15m, 30m, 1h, 2h, 4h, 6h, 8h, 12h, 1d, 3d, 1w or 1M. | | limit | number | no | Number of candles to return (1–500). | | symbol | string | yes | Trading pair in any common form: "BTCUSDT", "BTC/USDT" or a bare "BTC" (a USDT quote is assumed). |

getFundingRate

Get the funding rate for a USDⓈ-M perpetual future: the current period rate, recent history, the average across that history, mark and index price, and the next funding time. Positive funding means longs pay shorts (crowded long); negative means shorts pay longs. Only perpetual symbols have funding.

| Parameter | Type | Required | Description | | --- | --- | --- | --- | | limit | number | no | Number of historical funding periods to include (1–100). | | symbol | string | yes | Trading pair in any common form: "BTCUSDT", "BTC/USDT" or a bare "BTC" (a USDT quote is assumed). |

getOpenInterest

Get open interest for a USDⓈ-M perpetual future — current contracts outstanding plus a historical series with USD notional, and the percentage change across the window. Read alongside price direction: rising open interest with rising price means new long money, rising open interest with falling price means shorts building. Only perpetual symbols report open interest.

| Parameter | Type | Required | Description | | --- | --- | --- | --- | | period | string | no | Aggregation period for the historical series: 5m, 15m, 30m, 1h, 2h, 4h, 6h, 12h or 1d. | | symbol | string | yes | Trading pair in any common form: "BTCUSDT", "BTC/USDT" or a bare "BTC" (a USDT quote is assumed). |

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

License

Apache-2.0