@sperax/tool-lending

Supply, borrow, repay, and monitor health across Aave, Compound, and more

Lending 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-lending

Usage

Call it directly

import { lendingExecutor } from '@sperax/tool-lending';

const result = await lendingExecutor.invoke('getMarkets', {"asset":"<asset>","chainId":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 { LendingManifest, lendingExecutor } from '@sperax/tool-lending';

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

LendingManifest.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 { lendingExecutor } = await import('@sperax/tool-lending');

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

API reference

getMarkets

Get lending markets with live rates, TVL, and utilization across protocols (Aave V3, Compound V3, Radiant V2, Spark). Compare supply/borrow APY and incentive rewards. Always use this first when a user asks about lending rates.

| Parameter | Type | Required | Description | | --- | --- | --- | --- | | asset | string | no | Filter by asset symbol (e.g., "USDC", "ETH", "WBTC"). Optional. | | chainId | number | no | Chain ID (42161=Arbitrum, 1=Ethereum, 137=Polygon, 10=Optimism, 8453=Base). Default: 42161. | | protocol | string | no | Filter by protocol: "aave-v3", "compound-v3", "radiant-v2", "spark". Optional. | | sortBy | string | no | Sort results by: "supplyApy", "borrowApy", "tvl", "utilization". Default: "supplyApy". |

supply

Supply (deposit) tokens into a lending pool to earn yield. Returns an unsigned transaction for the user to sign. The token will be used as collateral by default. ALWAYS show the current APY and confirm with the user first.

| Parameter | Type | Required | Description | | --- | --- | --- | --- | | amount | string | yes | Amount to supply in human-readable units (e.g., "1000" for 1000 USDC). | | asset | string | yes | Token symbol to supply (e.g., "USDC", "ETH", "WBTC"). | | chainId | number | no | Chain ID. Default: 42161 (Arbitrum). | | protocol | string | no | Lending protocol. Default: "aave-v3". | | useAsCollateral | boolean | no | Whether to enable this asset as collateral. Default: true. | | walletAddress | string | yes | User wallet address (0x...). |

borrow

Borrow tokens against supplied collateral. Returns an unsigned transaction. CRITICAL: Always check health factor impact BEFORE borrowing. Warn user about liquidation risk.

| Parameter | Type | Required | Description | | --- | --- | --- | --- | | amount | string | yes | Amount to borrow in human-readable units. | | asset | string | yes | Token symbol to borrow (e.g., "USDC", "USDT", "DAI"). | | chainId | number | no | Chain ID. Default: 42161 (Arbitrum). | | interestRateMode | string | no | Interest rate mode: "variable" (default) or "stable". | | protocol | string | no | Lending protocol. Default: "aave-v3". | | walletAddress | string | yes | User wallet address (0x...). |

repay

Repay outstanding debt on a lending position. Use "max" as amount for full repayment. Returns an unsigned transaction.

| Parameter | Type | Required | Description | | --- | --- | --- | --- | | amount | string | yes | Amount to repay (human-readable, or "max" for full repayment). | | asset | string | yes | Token symbol to repay (e.g., "USDC"). | | chainId | number | no | Chain ID. Default: 42161. | | interestRateMode | string | no | Interest rate mode being repaid: "variable" or "stable". | | protocol | string | no | Lending protocol. Default: "aave-v3". | | walletAddress | string | yes | User wallet address (0x...). |

withdraw

Withdraw supplied collateral from a lending pool. ALWAYS check health factor impact before withdrawing — it may trigger liquidation if debt exists.

| Parameter | Type | Required | Description | | --- | --- | --- | --- | | amount | string | yes | Amount to withdraw (human-readable, or "max" for full withdrawal). | | asset | string | yes | Token symbol to withdraw. | | chainId | number | no | Chain ID. Default: 42161. | | protocol | string | no | Lending protocol. Default: "aave-v3". | | walletAddress | string | yes | User wallet address (0x...). |

getUserPositions

Get the user's current lending positions across protocols. Shows supplied collateral, borrowed amounts, earned interest, and overall health.

| Parameter | Type | Required | Description | | --- | --- | --- | --- | | chainId | number | no | Chain ID. Default: 42161. | | protocol | string | no | Filter by protocol (optional). | | walletAddress | string | yes | User wallet address (0x...). |

getHealthFactor

Get detailed health factor analysis including liquidation prices, risk level, and recommendations. Use proactively whenever a user is borrowing or withdrawing collateral.

| Parameter | Type | Required | Description | | --- | --- | --- | --- | | chainId | number | no | Chain ID. Default: 42161. | | protocol | string | no | Lending protocol. Default: "aave-v3". | | 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-lending is one of many
• SperaxOS — the agent workspace these tools were built for

License

Apache-2.0