@sperax/tool-chainlink

Chainlink oracle price feeds read directly on-chain across Ethereum, Arbitrum, Base, BNB Chain, Polygon and Optimism — with round data, decimals and staleness detection.

Chainlink 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-chainlink

Usage

Call it directly

import { chainlinkExecutor } from '@sperax/tool-chainlink';

const result = await chainlinkExecutor.invoke('getPrice', {"chain":"<chain>","pair":"<pair>"}, {
  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 { ChainlinkManifest, chainlinkExecutor } from '@sperax/tool-chainlink';

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

ChainlinkManifest.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-chainlink

API reference

getPrice

Read the current Chainlink oracle price for a pair on a given chain, straight from the AggregatorV3Interface proxy on-chain. Returns the scaled price, the unscaled answer, feed address and decimals, round ID, when it was last updated, and whether the answer is stale. This is the price source DeFi protocols use for collateral valuation and liquidations.

| Parameter | Type | Required | Description | | --- | --- | --- | --- | | chain | string | no | Chain to read from: ethereum, arbitrum, base, bsc, polygon or optimism. Defaults to ethereum. | | pair | string | yes | Pair to read, e.g. "ETH/USD", "BTC-USD", or a bare "ETH" (USD is assumed). |

listFeeds

List the Chainlink price feeds this tool can read, with their on-chain addresses. Omit chain to list every supported chain. Use this before telling a user a pair is unavailable — a pair missing on one chain often exists on another.

| Parameter | Type | Required | Description | | --- | --- | --- | --- | | chain | string | no | Chain to enumerate: ethereum, arbitrum, base, bsc, polygon or optimism. Omit to list all. |

getRoundData

Read a specific Chainlink aggregator round for a pair, or the latest round when no round ID is given. Round IDs are per-aggregator, so rounds from before a feed upgraded its aggregator are not readable through the proxy.

| Parameter | Type | Required | Description | | --- | --- | --- | --- | | chain | string | no | Chain to read from: ethereum, arbitrum, base, bsc, polygon or optimism. Defaults to ethereum. | | pair | string | yes | Pair to read, e.g. "ETH/USD", "BTC-USD", or a bare "ETH" (USD is assumed). | | roundId | string | no | Aggregator round ID to read, as an integer string. Omit for the latest round. |

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

License

Apache-2.0