@sperax/tool-sperax-portfolio

Portfolio analytics — assets, DeFi positions, transactions, and risk analysis

Portfolio Analytics 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-sperax-portfolio

Usage

Call it directly

import { speraxPortfolioExecutor } from '@sperax/tool-sperax-portfolio';

const result = await speraxPortfolioExecutor.invoke('getPortfolioSummary', {"walletAddress":"<walletAddress>"}, {
  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 { SperaxPortfolioManifest, speraxPortfolioExecutor } from '@sperax/tool-sperax-portfolio';

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

SperaxPortfolioManifest.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 { speraxPortfolioExecutor } = await import('@sperax/tool-sperax-portfolio');

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-portfolio-v2

API reference

getPortfolioSummary

Get portfolio summary with total value, 24h change, and chain breakdown. Displays a rich summary card with chain distribution in chat.

| Parameter | Type | Required | Description | | --- | --- | --- | --- | | walletAddress | string | no | Ethereum wallet address (0x...). Optional — uses default wallet if not provided. |

getAssets

Get all token holdings with prices, amounts, USD value, and 24h change. Displays a sortable asset list in chat.

| Parameter | Type | Required | Description | | --- | --- | --- | --- | | chain | string | no | Filter by chain (e.g., Ethereum, Arbitrum, Polygon) | | sortBy | string | no | Sort assets by: value (default), name, or change | | walletAddress | string | no | Ethereum wallet address (0x...). Optional — uses default wallet if not provided. |

getDeFiPositions

Get active DeFi positions including lending, LP positions, and staking. Displays position cards with yield and health info.

| Parameter | Type | Required | Description | | --- | --- | --- | --- | | chain | string | no | Filter by chain | | walletAddress | string | no | Ethereum wallet address (0x...). Optional — uses default wallet if not provided. |

getTransactionHistory

Get recent transaction history with type, amounts, timestamps, and transaction hashes.

| Parameter | Type | Required | Description | | --- | --- | --- | --- | | limit | number | no | Max number of transactions to return (default: 10) | | type | string | no | Filter by type: send, receive, swap, approve | | walletAddress | string | no | Ethereum wallet address (0x...). Optional — uses default wallet if not provided. |

analyzePortfolio

Analyze portfolio for risk, diversification, and recommendations. Displays a risk dashboard with scores and actionable suggestions.

| Parameter | Type | Required | Description | | --- | --- | --- | --- | | walletAddress | string | no | Ethereum wallet address (0x...). Optional — uses default wallet if not provided. |

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

License

Apache-2.0