@sperax/tool-token-unlocks

Track upcoming token unlock schedules and cliff events from DefiLlama

Token Unlocks 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-token-unlocks

Usage

Call it directly

import { tokenUnlocksExecutor } from '@sperax/tool-token-unlocks';

const result = await tokenUnlocksExecutor.invoke('getUpcomingUnlocks', {"days":1,"minValueUsd":1}, {
  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 { TokenUnlocksManifest, tokenUnlocksExecutor } from '@sperax/tool-token-unlocks';

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

TokenUnlocksManifest.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-token-unlocks

API reference

getUpcomingUnlocks

Get upcoming token unlock events across all protocols. Returns unlock date, token, amount, USD value, and percent of supply. Useful for identifying potential sell pressure.

| Parameter | Type | Required | Description | | --- | --- | --- | --- | | days | number | no | Number of days to look ahead (default: 30). Use 7 for short-term, 90 for longer view. | | minValueUsd | number | no | Minimum USD value to include (default: 1000000). Increase to filter small unlocks. |

getProtocolUnlocks

Get the full unlock/vesting schedule for a specific protocol. Pass the protocol name or slug (e.g. "arbitrum", "optimism", "aptos").

| Parameter | Type | Required | Description | | --- | --- | --- | --- | | protocol | string | yes | Protocol name or DefiLlama slug (e.g. "arbitrum", "optimism", "sui"). |

getUnlockSummary

Get an aggregated summary of token unlocks within a time window — total value, event count, largest single unlock, and breakdown by category.

| Parameter | Type | Required | Description | | --- | --- | --- | --- | | days | number | no | Number of days to summarize (default: 30). Use 7 for a weekly view. |

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

License

Apache-2.0