@hermesplant/agent-services

Typed TypeScript/JavaScript client for Hermes Plant's deterministic finance & safety APIs for AI agents.

LLMs hallucinate financial math and wobble between attempts. These endpoints return the same right answer every time, with evidence — DCF, IRR, XIRR, Black-Scholes Greeks, LP/GP waterfalls, bond analytics, portfolio risk, wallet AML, email validation, and MCP-server risk scoring.

Start free — no crypto wallet

Get a free key (250 calls/month, every endpoint) at https://hermesplant.com/pricing, then:

npm install @hermesplant/agent-services

import { HermesPlant } from "@hermesplant/agent-services";

const hermes = new HermesPlant({ apiKey: process.env.HERMES_API_KEY });

// Full deal underwrite (DCF + returns + waterfall) in one call
const deal = await hermes.dealAnalyzer({
  dcf: { cashflows: [120, 140, 160, 180, 200], discountRate: 0.11, exitMultiple: 9, netDebt: 300, shares: 100 },
  returns: { cashflows: [-1000, 0, 0, 0, 0, 2100], discountRate: 0.11 },
  waterfall: { contributedCapital: 1000, carryPercentage: 0.2, preferredRate: 0.08, years: 5 },
});

// Black-Scholes price + Greeks
const opt = await hermes.options({ spot: 100, strike: 100, timeToExpiry: 0.5, volatility: 0.2 });

// IRR / NPV / XIRR
const cf = await hermes.cashflowLens({ cashflows: [-1000, 300, 300, 300, 300] });

Past the free quota

When you exceed 250 calls/month the same call still works — either upgrade to the $29 Agent API Pass (5,000 calls) or pay per call over x402. A 402 surfaces as a typed PaymentRequiredError:

import { PaymentRequiredError } from "@hermesplant/agent-services";

try {
  await hermes.bond({ faceValue: 1000, couponRate: 0.05, periods: 10, price: 950 });
} catch (err) {
  if (err instanceof PaymentRequiredError) {
    // out of free quota — upgrade at https://hermesplant.com/pricing
  }
}

Methods

dealAnalyzer · cashflowLens · waterfall · options · bond · portfolioGuard · walletGuard · emailGuard · mcpRisk · destructGuard · reviewQueue. Or call any endpoint by path with hermes.call(path, body).

Options

new HermesPlant({
  apiKey: "hp_free_…",          // free-tier or plan key (sent as X-API-Key)
  baseUrl: "https://hermesplant.com", // override for staging
  fetch: customFetch,           // Node < 18
  timeoutMs: 15000,             // optional per-request timeout
});

MIT licensed. Docs: https://hermesplant.com/docs/api