@sperax/tool-yield-vaults
v0.2.1
Published
Earn yield on your tokens through audited Yearn V3 and Beefy Finance vaults — an agent tool for SperaxOS.
Maintainers
Readme
@sperax/tool-yield-vaults
Earn yield on your tokens through audited Yearn V3 and Beefy Finance vaults
Yield Vaults 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-yield-vaultsUsage
Call it directly
import { yieldVaultsExecutor } from '@sperax/tool-yield-vaults';
const result = await yieldVaultsExecutor.invoke('getVaults', {"chain":"<chain>","minApy":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 UIGive it to a model
import Anthropic from '@anthropic-ai/sdk';
import { YieldVaultsManifest, yieldVaultsExecutor } from '@sperax/tool-yield-vaults';
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: YieldVaultsManifest.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 yieldVaultsExecutor.invoke(block.name, block.input, { messageId: response.id });
console.log(result.content);
}YieldVaultsManifest.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-yield-vaults
API reference
getVaults
Browse available yield vaults from Yearn V3 and Beefy Finance. Filter by chain, deposit token, minimum APY, and minimum TVL. Returns a list of vaults with APY, TVL, risk level, and audit status.
| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| chain | string | no | Filter by chain name (e.g. "ethereum", "arbitrum", "polygon", "base", "optimism"). |
| minApy | number | no | Minimum APY filter as a percentage (e.g. 3.0 = vaults with 3%+ APY). |
| minTvl | number | no | Minimum TVL filter in USD (e.g. 1000000 = vaults with $1M+ TVL). Higher TVL generally indicates more trust. |
| token | string | no | Filter by deposit token symbol (e.g. "USDC", "ETH", "WETH", "DAI"). |
getVaultDetails
Get detailed information about a specific vault, including strategy description, fee breakdown (management, performance, deposit, withdrawal), and historical APY (7-day, 30-day).
| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| vaultId | string | yes | Unique vault identifier returned from getVaults. |
deposit
Deposit tokens into a yield vault. Returns an unsigned transaction for the user to sign in their wallet (non-custodial). May include an ERC-20 approval transaction if token allowance is insufficient. ONLY call after the user has explicitly confirmed the deposit.
| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| amount | string | yes | Amount to deposit in human-readable units (e.g. "100.5" for 100.5 USDC). |
| chain | string | yes | Chain name (e.g. "arbitrum") or chain ID (e.g. "42161"). |
| vaultId | string | yes | Vault identifier to deposit into. |
| walletAddress | string | yes | User wallet address (0x...). |
withdraw
Withdraw tokens from a yield vault. Returns an unsigned transaction for the user to sign. Use amount "max" for full withdrawal. ONLY call after the user has explicitly confirmed the withdrawal.
| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| amount | string | yes | Amount to withdraw in human-readable units, or "max" for full withdrawal. |
| chain | string | yes | Chain name (e.g. "arbitrum") or chain ID (e.g. "42161"). |
| vaultId | string | yes | Vault identifier to withdraw from. |
| walletAddress | string | yes | User wallet address (0x...). |
getUserPositions
Get the user's current vault positions across all protocols and chains. Shows deposited amounts, current value, earned yield, and APY for each position.
| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| chain | string | no | Optional: filter positions by chain name. |
| walletAddress | string | yes | User wallet address (0x...). |
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-yield-vaults is one of many
- SperaxOS — the agent workspace these tools were built for
License
Apache-2.0
