@sperax/tool-plutus

Plutus DAO yield aggregator — vaults, plsASSETs, and staking rewards

Plutus 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-plutus

Usage

Call it directly

import { plutusExecutor } from '@sperax/tool-plutus';

const result = await plutusExecutor.invoke('agentDeposit', {"amountUsdc":1,"vault":"A"}, {
  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 { PlutusManifest, plutusExecutor } from '@sperax/tool-plutus';

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

PlutusManifest.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 { plutusExecutor } = await import('@sperax/tool-plutus');

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-plutus

API reference

agentDeposit

Deposit USDC into an allowlisted Plutus HedgeVault on behalf of the user using their agent smart account (ERC-4337). No wallet approval is needed per deposit — the on-chain permission validator caps each deposit at 100 USDC, restricts it to vaults A and B, and pins the receiver to the user's smart account. Requires the user to have completed agent smart account setup.

| Parameter | Type | Required | Description | | --- | --- | --- | --- | | amountUsdc | number | yes | Amount of USDC to deposit. Must be 100 or less (per-transaction cap). | | vault | A | B | yes | Which HedgeVault to deposit into: "A" or "B". |

getPlutusVaults

List all Plutus vaults (plvHEDGE, plvLOOP, plvDOLO) with current APY, TVL, risk level, and deposit token. Displays rich vault cards in chat.

| Parameter | Type | Required | Description | | --- | --- | --- | --- | | riskLevel | string | no | Filter by risk level: low, medium, or high |

getVaultDetails

Get detailed information about a specific Plutus vault including strategy description, fee structure, historical APY, and performance metrics.

| Parameter | Type | Required | Description | | --- | --- | --- | --- | | vaultId | string | yes | The vault identifier (e.g., plvHEDGE, plvLOOP, plvDOLO) |

getPlsAssets

List all plsASSETs (Plutus liquid staking wrapper tokens) with current prices, APR, and staking status.

| Parameter | Type | Required | Description | | --- | --- | --- | --- | | symbol | string | no | Filter by specific plsASSET symbol (e.g., plsARB, plsSPA) |

getUserVaultPositions

Get user's current positions across all Plutus vaults including deposited amounts, current value, PnL, and earned rewards.

| Parameter | Type | Required | Description | | --- | --- | --- | --- | | walletAddress | string | yes | Ethereum wallet address (0x...). Required for user-specific queries. |

getStakingRewards

Check pending staking rewards for a wallet across all Plutus protocols. Shows claimable amounts and USD values.

| Parameter | Type | Required | Description | | --- | --- | --- | --- | | walletAddress | string | yes | Ethereum wallet address (0x...). Required for user-specific queries. |

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

License

Apache-2.0