@sperax/tool-copy-trading

Discover top on-chain traders, analyze their P&L and win rate, and mirror their trades with configurable size limits, delay, and stop-loss protection

Copy Trading 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-copy-trading

Usage

Call it directly

import { copyTradingExecutor } from '@sperax/tool-copy-trading';

const result = await copyTradingExecutor.invoke('discoverWhales', {"limit":1,"minPnlUsd":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 { CopyTradingManifest, copyTradingExecutor } from '@sperax/tool-copy-trading';

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

CopyTradingManifest.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 { copyTradingExecutor } = await import('@sperax/tool-copy-trading');

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-copy-trading

API reference

discoverWhales

Discover top-performing on-chain wallets ranked by 30-day P&L, win rate, trading volume, or yield farming returns. Optionally filter by minimum P&L or minimum trade count. Returns a ranked list of wallets with performance statistics.

| Parameter | Type | Required | Description | | --- | --- | --- | --- | | limit | number | no | Number of wallets to return (default: 20) | | minPnlUsd | number | no | Filter: only include wallets with at least this much 30d P&L in USD | | minTrades | number | no | Filter: only include wallets with at least this many trades in the last 30 days | | strategy | pnl_30d | win_rate | volume_30d | yield_farming | yes | Ranking strategy: pnl_30d (sort by 30-day profit), win_rate (sort by win %), volume_30d (sort by total volume), yield_farming (sort by yield farming returns) |

getWalletProfile

Fetch a detailed profile for any on-chain wallet address. Returns current holdings, 30-day and 90-day P&L, win rate, average trade size, most-used protocols, and optionally the last 30 decoded trades.

| Parameter | Type | Required | Description | | --- | --- | --- | --- | | includeHistory | boolean | no | If true, include the last 30 trades in the response (default: false) | | walletAddress | string | yes | Ethereum/EVM wallet address (0x...) to analyze |

followWallet

Follow a wallet and configure copy-trading mirror parameters. Once followed, in-app notifications fire when the wallet makes a new trade, and the user can click "Mirror Now" to replicate it. Returns a follow rule ID.

| Parameter | Type | Required | Description | | --- | --- | --- | --- | | copyConfig | object | yes | Mirror trading configuration object | | label | string | no | Human-readable label for this wallet (e.g. "ETH Degen #1", "Meme Whale") | | walletAddress | string | yes | Wallet address to follow |

listFollowedWallets

List all wallets the current user is following, along with their P&L performance since the user began following them and the current mirror configuration.

Takes no parameters.

getRecentTrades

Retrieve recent decoded on-chain trades for any wallet address. Returns decoded swaps, LP adds/removes, lending activity, and staking events. Optionally filter by date.

| Parameter | Type | Required | Description | | --- | --- | --- | --- | | limit | number | no | Number of trades to return (default: 10) | | since | string | no | ISO 8601 date — only return trades after this timestamp | | walletAddress | string | yes | Wallet address to fetch trades for |

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

License

Apache-2.0