@recursa-ai/sdk

Typed TypeScript SDK for Recursa — the Solana yield aggregator. Wrap the lending-strategy pipeline (JupLend + Kamino multi-market + Project0 + Exponent PT) in a framework-agnostic package any agent (Claude, LangGraph, Operator, your bot) can call.

Install

npm install @recursa-ai/sdk @solana/web3.js

Quickstart

import { createRecursaClient } from "@recursa-ai/sdk";

const recursa = createRecursaClient(); // hits the production deploy

// 1. Discover what's available — top 10 low-risk SOL strategies
const top10 = await recursa.listStrategies({
  assetCategory: "sol",
  maxRisk: "low",
  limit: 10,
});

// 2. Preview a hypothetical position — same numbers /loop shows
const preview = await recursa.previewOpenPosition({
  token: "SOL",
  leverage: 2.5,
  amount: 1.0,
});

if (preview.kind === "ok") {
  console.log(`Net APY ${preview.netAPY.toFixed(2)}%`);
  console.log(`Health Factor ${preview.healthFactor.toFixed(2)}`);
  console.log(`Liquidation at $${preview.liquidationPrice.toFixed(2)}`);
} else {
  console.log(`Preview unavailable: ${preview.message}`);
}

// 3. Build a transaction the user signs — coming in 0.2 (see below)
// const tx = recursa.buildOpenPositionTx({ preview, owner: walletPubkey });

Scope (v0.1)

✅ Stable — agents can rely on these:

• listStrategies(filter) — filters the full catalog by asset, risk, intent, protocol, search.
• previewOpenPosition(inputs) — same HF + liquidation math the web /loop builder uses. Returns a typed PreviewResult (no exceptions on missing data — just kind: "unavailable" with a reason).
• fetchRates() — raw rate snapshot from /api/rates.

🚧 Stub (returns a clear error directing users to /loop):

• buildOpenPositionTx(args) — signer-agnostic tx construction. Lands with the @recursa-ai/idl extraction; until then, agents should surface the deep link https://recursa-solana.pages.dev/loop?token=<asset>&leverage=<n> for the user to complete the position via the web UI.

Design principles

• Signer-agnostic. The SDK never asks for a private key. It returns base64 tx bytes for any wallet abstraction (Phantom, Solflare, Squads, hardware, agent-custodial) to sign + send.
• Same math as the UI. previewOpenPosition uses the exact formulas the web /loop builder shows. Agents never quote numbers users wouldn't see.
• No hidden state. Every method takes its inputs explicitly; every method either returns or throws — no side effects between calls.
• Typed unavailable states. Network failures throw; missing rate data returns kind: "unavailable" with a typed reason. Agents handle the two paths separately.

Network targets

Default: mainnet-beta (production). Set network: "devnet" in the client config for staging.

const recursa = createRecursaClient({
  network: "devnet",
  rpcUrl: "https://api.devnet.solana.com",
});

Companion packages

• @recursa-ai/mcp — Model Context Protocol server wrapping this SDK. Drop-in for Claude Desktop, Cursor, Claude Code, any MCP-compatible agent runtime.
• /.well-known/agents.json — capability manifest at the deploy origin.
• docs/SKILLS.md — Anthropic Skill format describing every agent-callable surface.

License

MIT