@sperax/tool-markets

View DeFi market data, yields, prices, and protocol analytics in chat

Markets 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-markets

Usage

Call it directly

import { marketsExecutor } from '@sperax/tool-markets';

const result = await marketsExecutor.invoke('getGlobalStats', {}, {
  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 { MarketsManifest, marketsExecutor } from '@sperax/tool-markets';

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

MarketsManifest.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 — required

This tool needs a backend you control. It will not work on a bare npm install alone.

The upstream API requires a secret key. That key is deliberately not bundled here — shipping it in an npm package would leak it to every consumer. Instead the executor calls a SperaxOS /webapi/* route, which holds the key server-side and injects it. That route is session-authenticated, so the public deployment at https://chat.sperax.io (the default origin) answers 401 to anonymous callers.

To use this tool you need one of:

• a SperaxOS deployment of your own, or
• any HTTP endpoint that implements the same request shape and supplies the key.

Point the package at it before importing the tool — the URL is resolved once, when the module first loads:

SPERAX_API_BASE_URL=https://my-speraxos.example.com

or in code:

import { configureSperaxApi } from '@sperax/agent-tools-core';

configureSperaxApi({ baseUrl: 'https://my-speraxos.example.com' });

// import the tool only after configuring, so the path resolves against your origin
const { marketsExecutor } = await import('@sperax/tool-markets');

Inside a browser that already serves those routes at its own origin, requests stay same-origin and no configuration is needed.

If you want a tool that runs with zero setup, use one of the standalone tools — those call public APIs directly and need no key, no origin, and no backend.

Tool identifier

sperax-markets

API reference

getGlobalStats

Get global DeFi statistics including total TVL, DEX volume, fees/revenue, and fear & greed index. Use when the user asks about overall DeFi market health, total value locked, market sentiment, or wants a high-level market summary.

Takes no parameters.

getChainTvl

Get TVL breakdown by blockchain (top 10 chains with dominance percentages). Use when the user asks about chain rankings, which chain has the most TVL, chain dominance, or how TVL is distributed across chains.

Takes no parameters.

getCategoryBreakdown

Get DeFi protocol categories with TVL, protocol count, and top protocol per category. Use when the user asks about DeFi sectors, categories like lending/DEX/derivatives, or wants to know which category dominates DeFi.

Takes no parameters.

getTopProtocols

Get top DeFi protocols ranked by TVL with 24h/7d changes, category, and supported chains. Use when the user asks about top protocols, biggest DeFi projects, protocol rankings, or TVL leaders.

| Parameter | Type | Required | Description | | --- | --- | --- | --- | | limit | number | no | Number of protocols to return (default 20, max 100) |

getRevenueEarners

Get top 10 protocols by 24h fees and revenue with profit margin. Use when the user asks about which protocols earn the most, revenue leaders, fee generators, or most profitable DeFi protocols.

Takes no parameters.

getTopYields

Get best yield opportunities scored by APY × TVL × stability. Use when the user asks about best yields, top farming opportunities, where to earn yield, or highest APY pools.

| Parameter | Type | Required | Description | | --- | --- | --- | --- | | limit | number | no | Number of yield opportunities to return (default 5) |

getSperaxEcosystem

Get Sperax ecosystem yield pools and positions. Use when the user asks about Sperax yields, SPA pools, USDs farming, or Sperax ecosystem opportunities.

Takes no parameters.

getChains

Get detailed chain data: TVL, dominance, 24h change, and protocol count for each chain. Use when the user asks about blockchain comparisons, chain metrics, or detailed chain-level data.

Takes no parameters.

getMarketPrices

Get crypto market prices with 24h change, volume, and market cap for top tokens. Use when the user asks about token prices, crypto prices, market caps, or wants to check the price of specific tokens.

| Parameter | Type | Required | Description | | --- | --- | --- | --- | | symbols | string | no | Comma-separated token symbols to look up (e.g. "BTC,ETH,SOL"). Defaults to top 30 tokens if omitted. |

getYieldPools

Get DeFi yield pools with APY, TVL, chain, score, and impermanent loss risk. Use when the user asks about yield farming pools, DeFi pools, liquidity pools, or wants to browse available pools.

| Parameter | Type | Required | Description | | --- | --- | --- | --- | | chain | string | no | Filter pools by chain name (e.g. "Ethereum", "Arbitrum") | | limit | number | no | Number of pools to return (default 20) |

getStablecoins

Get stablecoin data: supply, peg type, supported chains, and top yields. Use when the user asks about stablecoins, USDC, USDT, DAI, stablecoin yields, or stablecoin supply.

Takes no parameters.

getProtocolComparison

Compare up to 4 DeFi protocols side-by-side on TVL, changes, category, and chains. Use when the user asks to compare protocols, e.g. "compare Aave vs Compound" or "how does Uniswap compare to Sushiswap".

| Parameter | Type | Required | Description | | --- | --- | --- | --- | | slugs | array | yes | Array of protocol slugs to compare (e.g. ["aave", "compound"]). Max 4. |

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

License

Apache-2.0