@quantoracle/ai-tools

@quantoracle/ai-tools

Deterministic quant finance tools for the Vercel AI SDK.

LLMs hallucinate Black-Scholes prices. Greeks drift 5-30% in-context and the model can't tell. This package gives your AI SDK agent grounded, deterministic quant math via the free QuantOracle API — same inputs always produce the same outputs, every value tested against Hull / Wilmott / Lopez de Prado.

• 15 tools across 4 opt-in bundles — start with 5 core tools, add options / risk / DeFi as your agent needs them
• Free tier: 1,000 calls/IP/day covers 13 of 15 tools — no signup, no API key
• Paid composites ($0.04 USDC each) settle via x402 on Base or Solana mainnet
• Drop-in compatible with generateText, streamText, generateObject, and useChat. Tools return structured JSON for clean UI rendering.

Install

pnpm add @quantoracle/ai-tools ai zod
# plus a model provider, e.g.:
pnpm add @ai-sdk/openai

Quick start (default 5-tool core bundle)

import { generateText } from "ai";
import { openai } from "@ai-sdk/openai";
import { quantoracleTools } from "@quantoracle/ai-tools";

const result = await generateText({
  model: openai("gpt-4o"),
  tools: quantoracleTools(),
  maxSteps: 5,
  prompt: "Price a 30-day SPY $500 call with vol=18%, spot=$498, rate=5%.",
});

console.log(result.text);

The model picks price_option, fills in the parameters, gets a deterministic response from QuantOracle, and summarises the result.

Tool bundles

The default ships 5 highest-leverage tools. Opt into more via the include option — bundle keys are core, options, risk, defi, or 'all'.

core (5 tools — always shipped)

Tool	What it does	Tier
price_option	Black-Scholes call/put with full Greeks	free
calculate_kelly	Kelly Criterion bet sizing (full / half / quarter)	free
simulate_portfolio	Monte Carlo terminal distribution + ruin probability	free
assess_portfolio_risk	Sharpe + Sortino + Calmar + drawdown + VaR + CVaR + Kelly + Hurst in one call	paid $0.04
recommend_hedge	Ranked hedge structures (collar, protective put, partial put, inverse)	paid $0.04

options (+4)

Tool	What it does
implied_vol	Newton-Raphson IV solver
binomial_tree	American/European options via CRR tree
payoff_diagram	Multi-leg strategy P&L curves + breakevens
put_call_parity	Parity check + arbitrage detection

risk (+4)

Tool	What it does
var_parametric	Standalone VaR + CVaR (faster than full audit)
correlation	N×N correlation matrix
sharpe_ratio	Standalone Sharpe + 95% CI (Lo 2002)
zscore	Static + rolling z-scores with extreme-value detection

defi (+2)

Tool	What it does
impermanent_loss	Uniswap v2/v3 IL + fee breakeven APY
liquidation_price	Liquidation price for leveraged perps / margin

Bundle selection examples

// Default — 5 core tools
quantoracleTools()

// Options-focused agent — 9 tools
quantoracleTools({ include: ["core", "options"] })

// DeFi onchain agent — 7 tools
quantoracleTools({ include: ["core", "defi"] })

// Quant research / risk dashboard — 13 tools
quantoracleTools({ include: ["core", "risk", "options"] })

// All 15 tools
quantoracleTools({ include: "all" })

The bundle picker is the difference between a focused agent that picks the right tool every time and a confused agent drowning in 15 descriptions. Pick the bundles your agent actually needs.

Paid composite tools (x402)

The two paid tools (assess_portfolio_risk, recommend_hedge) cost $0.04 USDC per call and settle via x402 on Base or Solana. Wire an x402PayHandler that signs the payment header:

import { quantoraclePaidTools } from "@quantoracle/ai-tools";
import { signX402Header } from "x402"; // your wallet integration

const tools = quantoraclePaidTools({
  include: "all",
  x402PayHandler: async (requirements) => signX402Header(requirements),
});

See the x402 reference implementation for wallet-side signing on Base (viem) and Solana (@solana/web3.js).

With useChat (Next.js)

// app/api/chat/route.ts
import { streamText } from "ai";
import { openai } from "@ai-sdk/openai";
import { quantoracleTools } from "@quantoracle/ai-tools";

export async function POST(req: Request) {
  const { messages } = await req.json();
  const result = streamText({
    model: openai("gpt-4o"),
    messages,
    tools: quantoracleTools({ include: ["core", "options"] }),
    maxSteps: 5,
  });
  return result.toDataStreamResponse();
}

Tool results stream to the client as structured JSON, so you can render them directly in your UI instead of re-parsing markdown.

Why deterministic math matters

LLMs computing Black-Scholes in-context get the price within ~5% but the Greeks drift 5-30% — and the model can't tell when it's wrong. If your agent makes trading decisions based on those Greeks, that drift compounds into bad sizing, bad hedges, and PnL that doesn't match the agent's expectations.

QuantOracle's endpoints are pure-function HTTP: same inputs, same outputs. Citation-tested against textbook values. Sub-70ms per call.

Need all 73 endpoints?

This package exposes 15 curated tools across 4 bundles. The full QuantOracle API has 73 endpoints (FX/macro, fixed income, technicals, derivatives exotics, TVM, etc.). For full coverage:

• REST API directly: every endpoint accepts JSON, returns JSON, CORS-enabled. Browse https://quantoracle.dev/api-docs.
• QuantOracle MCP server: dynamic tool discovery — the model only sees tool definitions for the tools it actually needs per call. Best for general-purpose agents that need breadth.

Related packages

• @quantoracle/agentkit — Coinbase AgentKit ActionProvider
• @quantoracle/goat-plugin — GOAT SDK plugin (multi-chain onchain agents)
• langchain-quantoracle — LangChain (Python)

License

MIT.