@sperax/tool-perpetuals
v0.2.2
Published
Perpetuals & derivatives trading across GMX, Hyperliquid, and dYdX — markets, positions, funding rates, and transaction building. — an agent tool for SperaxOS.
Maintainers
Readme
@sperax/tool-perpetuals
Perpetuals & derivatives trading across GMX, Hyperliquid, and dYdX — markets, positions, funding rates, and transaction building.
Perpetuals 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-perpetualsUsage
Call it directly
import { perpetualsExecutor } from '@sperax/tool-perpetuals';
const result = await perpetualsExecutor.invoke('getMarkets', {"chainId":1,"exchange":"gmx"}, {
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 UIGive it to a model
import Anthropic from '@anthropic-ai/sdk';
import { PerpetualsManifest, perpetualsExecutor } from '@sperax/tool-perpetuals';
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: PerpetualsManifest.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 perpetualsExecutor.invoke(block.name, block.input, { messageId: response.id });
console.log(result.content);
}PerpetualsManifest.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-perpetuals
API reference
getMarkets
List all available perpetual markets with funding rate, open interest, mark price, and 24h volume.
| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| chainId | number | no | Filter by chain ID (e.g. 42161 for Arbitrum) |
| exchange | gmx | hyperliquid | dydx | all | no | Exchange to query: gmx, hyperliquid, dydx, or all |
getPositions
Get open perpetual positions for a wallet with PNL, liquidation price, and margin ratio.
| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| exchange | gmx | hyperliquid | dydx | all | no | Exchange to query: gmx, hyperliquid, dydx, or all |
| walletAddress | string | yes | Wallet address (0x...) |
getFundingRates
Get historical funding rate time series and annualized rate for a market. Detects arbitrage opportunities across exchanges.
| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| exchange | gmx | hyperliquid | dydx | yes | Exchange: gmx, hyperliquid, or dydx |
| lookbackDays | number | no | Days of history to return (default 7) |
| market | string | yes | Market symbol, e.g. "ETH-USD" or "BTC-USD" |
buildOpenPositionTx
Build unsigned transaction calldata to open a leveraged long or short position on GMX or dYdX.
| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| chainId | number | yes | Chain ID (e.g. 42161 for Arbitrum) |
| collateralToken | string | yes | Collateral token symbol, e.g. "USDC" or "ETH" |
| exchange | gmx | dydx | yes | Exchange: gmx or dydx |
| leverage | number | yes | Leverage multiplier (1–50) |
| market | string | yes | Market symbol, e.g. "ETH-USD" |
| side | long | short | yes | Trade direction |
| sizeUsd | number | yes | Position size in USD |
| walletAddress | string | yes | Trader wallet address |
buildClosePositionTx
Build unsigned transaction calldata to close (fully or partially) an open perpetual position.
| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| closeSizePercent | number | yes | Percentage of position to close (1–100) |
| exchange | gmx | hyperliquid | dydx | yes | Exchange where position is held |
| positionId | string | yes | Position ID (from getPositions) |
| walletAddress | string | yes | Trader wallet address |
getLiquidationPrice
Calculate liquidation price and margin ratio at various price levels for a hypothetical or existing position.
| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| entryPrice | number | yes | Entry price in USD |
| exchange | gmx | hyperliquid | dydx | yes | Exchange (affects maintenance margin rate) |
| leverage | number | yes | Leverage multiplier |
| side | long | short | yes | Trade direction |
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-perpetuals is one of many
- SperaxOS — the agent workspace these tools were built for
License
Apache-2.0
