Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
info:
title: Hermes Plant - Agent Action Safety and Commerce Assurance…
description: 'Deterministic, test-backed controls for AI agents before consequential shell, Git, SQL, infrastructure, deployment, wallet, and x402 payment actions. Use the one-cent Action Safety quick gate for classification; the complete workflow for score, conditional review triage, execution evidence, and a signed receipt; and payment-policy endpoints for spend assurance. Finance and quant utilities remain available as component services. Pay per call over x402 (USDC on Base); no API key required. Pricing: https://hermesplant.com/pricing. Errors: https://hermesplant.com/docs/api/errors. Changelog: https://hermesplant.com/changelog.'
version: 1.0.0
contact:
name: Hermes Plant support
email: contact@hermesplant.com
url: https://hermesplant.com/contact
termsOfService: https://hermesplant.com/legal/terms
license:
name: Proprietary — see Terms of Service
url: https://hermesplant.com/legal/terms
x-pricing-url: https://hermesplant.com/pricing
x-errors-contract-url: https://hermesplant.com/docs/api/errors
x-changelog-url: https://hermesplant.com/changelog
x-changelog-feeds:
rss: https://hermesplant.com/changelog/feed.xml
jsonFeed: https://hermesplant.com/changelog/feed.json
x-x402-manifest-url: https://hermesplant.com/.well-known/x402
x-mcp-server-card-url: https://hermesplant.com/.well-known/mcp/server-card.json
x-llms-txt-url: https://hermesplant.com/llms.txt
x-risk-reversal:
- Refund any settled call whose documented inputs do not reproduce the same output.
- First $1 of calls free for the first 100 verified agents.
x-guidance: Call Hermes Plant before a consequential agent action or x402 payment. Start with POST /api/agent-services/action-safety/quick for a $0.01 deterministic preflight risk classification. Use POST /api/agent-services/action-safety/run when you need the complete $0.25 workflow with conditional review triage, execution evidence, status, and a signed receipt. Use POST /api/agent-services/payment-policy/decide to validate amount, asset, network, recipient, and buyer policy before signing. Use focused component endpoints only when you already own orchestration. Payment is x402 USDC on Base; see https://hermesplant.com/pricing and https://hermesplant.com/docs/api/errors.
x-hermes-guidance:
summary: Call Hermes Plant before a consequential agent action or x402 payment.
workflows:
- name: Agent Action Safety quick gate
start: POST /api/agent-services/action-safety/quick
priceUsd: '0.01'
useWhen: You need a deterministic preflight risk classification before shell, Git, SQL, infrastructure, or deployment work.
- name: Agent Action Safety complete workflow
start: POST /api/agent-services/action-safety/run
priceUsd: '0.25'
useWhen: You need scoring, conditional review triage, execution evidence, status, and a signed receipt.
- name: Agent spend assurance
start: POST /api/agent-services/payment-policy/decide
useWhen: You need to validate a proposed x402 payment against amount, asset, network, recipient, and buyer policy before signing.
selectionRules:
- Use quick for a low-cost preflight; use run when an auditable end-to-end record is required.
- Use focused component endpoints only when the caller already owns workflow orchestration.
- A review recommendation is not a claim that a human approved the action.
payment:
protocol: x402
network: Base
asset: USDC
pricingUrl: https://hermesplant.com/pricing
errorsUrl: https://hermesplant.com/docs/api/errors
proof:
manifest: https://hermesplant.com/.well-known/x402
agentCard: https://hermesplant.com/.well-known/agent.json
changelog: https://hermesplant.com/changelog
servers:
- url: https://hermesplant.com
tags:
- name: finance
paths:
/api/agent-services/cashflowlens/analyze:
post:
summary: CashflowLens
description: 'Deterministic cash flow analysis and return analytics in one call: NPV, IRR (periodic), XIRR (dated), MOIC / DPI / TVPI, payback period, plus an optional DCF valuation (enterprise value, equity value, implied share price) with Gordon-growth or exit-multiple terminal value. Pure math from caller-provided cashflows — no market-data feed, no fabrication. Every metric is accompanied by evidence-backed findings and a signed response receipt.'
operationId: cashflowlens_analyze
tags:
- finance
x-payment-info:
price:
mode: fixed
currency: USD
amount: '0.20'
protocols:
- x402: {}
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
cashflows:
type: array
description: Series of cashflows. Each item is a number (periodic, t=0,1,2,...) OR an object {amount, date?, label?}. Outflows negative, inflows positive. If ANY item has a date, dated/XIRR mode is used.
items:
oneOf:
- type: number
- type: object
properties:
amount:
type: number
date:
type: string
description: ISO date YYYY-MM-DD (enables XIRR)
label:
type: string
required:
- amount
discountRate:
type: number
description: Annual rate for NPV (e.g. 0.10). Omit to skip NPV.
periodsPerYear:
type: number
description: Periods per year to annualize a periodic IRR (default 1; e.g. 12 for monthly, 4 for quarterly).
nav:
type: number
description: Residual / net asset value, used for TVPI = (distributions + nav) / paid-in.
dcf:
type: object
description: Optional DCF valuation inputs.
properties:
cashflows:
type: array
items:
type: number
description: Projected free cash flows for t = 1..n.
discountRate:
type: number
description: WACC, e.g. 0.10.
terminalGrowth:
type: number
description: Gordon-growth terminal rate (needs discountRate > terminalGrowth).
exitMultiple:
type: number
description: 'Alternative terminal: multiple * last FCF (overrides terminalGrowth).'
netDebt:
type: number
description: Net debt to bridge enterprise value to equity value.
shares:
type: number
description: Share count for implied per-share value.
required:
- cashflows
- discountRate
required:
- cashflows
example:
cashflows:
- -1000000
- 50000
- 60000
- 70000
- 1200000
discountRate: 0.08
periodsPerYear: 1
nav: 0
responses:
'200':
description: CashflowLens result
content:
application/json:
schema:
type: object
example:
service: cashflowlens
requestId: cfl-1a2b3c4d
mode: periodic
summary:
totalIn: 1380000
totalOut: 1000000
net: 380000
npv: 162512.34
irrPerPeriod: 0.1287
irrAnnual: 0.1287
xirr: null
moic: 1.38
dpi: 1.38
tvpi: 1.38
paybackPeriod: 3.68
dcf: null
findings:
- rule: mode
severity: info
why: Whether returns were computed on dated (XIRR) or periodic (IRR) cashflows.
evidence: mode=periodic cashflows=5 periodsPerYear=1
fix: null
cashflowCount: 5
'400':
description: Invalid request
'402':
description: Payment required - x402 challenge in PAYMENT-REQUIRED header
headers:
PAYMENT-REQUIRED:
schema:
type: string
description: Base64-encoded x402 payment challenge
'503':
description: x402 not configured
/api/agent-services/waterfall/distribute:
post:
summary: WaterfallLens
description: Deterministic LP/GP distribution waterfall for private equity, venture, and real estate. Allocates distributable cash through the standard tiers — return of capital, preferred return (hurdle), GP catch-up, carried-interest split — and returns the exact LP/GP split, per-tier breakdown, LP MOIC, GP carry, and effective carry %. The catch-up is solved so the GP lands at exactly its carry % of total profit. Pure math from caller-provided terms — no data feed, no fabrication.
operationId: waterfall_distribute
tags:
- finance
x-payment-info:
price:
mode: fixed
currency: USD
amount: '0.25'
protocols:
- x402: {}
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
contributedCapital:
type: number
description: Total LP capital to be returned in tier 1 (required, > 0).
distributable:
type: number
description: Total cash available to distribute through the waterfall (required, >= 0).
carryPercentage:
type: number
description: GP carried interest as a fraction, e.g. 0.20 for 20% (default 0.20).
catchUpPercentage:
type: number
description: 'GP share of distributions during the catch-up tier: 1.0 = full (100%) catch-up (default), 0 = no catch-up. Must exceed carryPercentage for a standard catch-up.'
preferredReturnAmount:
type: number
description: Explicit preferred-return (hurdle) dollar amount. Overrides preferredRate/years if given.
preferredRate:
type: number
description: Annual preferred-return rate, e.g. 0.08 for 8%. Used with years when preferredReturnAmount is absent.
years:
type: number
description: Holding period in years over which the preferred return accrues.
compounding:
type: string
description: 'How the preferred return accrues from preferredRate/years: ''compounded'' (default) or ''simple''.'
required:
- contributedCapital
- distributable
example:
contributedCapital: 1000000
distributable: 2000000
carryPercentage: 0.2
catchUpPercentage: 1
preferredRate: 0.08
years: 5
compounding: compounded
responses:
'200':
description: WaterfallLens result
content:
application/json:
schema:
type: object
example:
service: waterfall
requestId: wf-1a2b3c4d
preferredReturn: 469328.08
summary:
totalDistributable: 2000000
lpDistribution: 1800000
gpDistribution: 200000
lpProfit: 800000
totalProfit: 1000000
lpMultiple: 1.8
gpCarry: 200000
effectiveGpCarryPct: 0.2
tiers:
- tier: 1
name: return-of-capital
lp: 1000000
gp: 0
total: 1000000
- tier: 2
name: preferred-return
lp: 469328.08
gp: 0
total: 469328.08
- tier: 3
name: gp-catch-up
lp: 0
gp: 117332.02
total: 117332.02
- tier: 4
name: carried-interest-split
lp: 330671.92
gp: 82667.98
total: 413339.9
findings:
- rule: summary
severity: info
why: Effective GP carry as a share of total profit, with the preferred-return basis used.
evidence: effectiveGpCarryPct=0.2131 preferredBasis=compounded
fix: null
'400':
description: Invalid request
'402':
description: Payment required - x402 challenge in PAYMENT-REQUIRED header
headers:
PAYMENT-REQUIRED:
schema:
type: string
description: Base64-encoded x402 payment challenge
'503':
description: x402 not configured
/api/agent-services/bond/analyze:
post:
summary: BondLens
description: 'Deterministic fixed-income & loan analytics. Bond mode: solve priceyield-to-maturity, current yield, Macaulay & modified duration, and convexity from the bond''s terms. Loan mode (send principal + annualRate + termMonths): level-payment amortization with monthly payment, total interest/paid, and the full schedule. Pure math from caller-supplied terms — no market-data feed, no fabrication.'
operationId: bond_analyze
tags:
- finance
x-payment-info:
price:
mode: fixed
currency: USD
amount: '0.25'
protocols:
- x402: {}
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
type:
type: string
description: 'Optional explicit mode: ''bond'' or ''loan''. Auto-detected as loan when principal is present.'
faceValue:
type: number
description: Bond face/par value (default 1000).
couponRate:
type: number
description: Bond annual coupon rate as a fraction, e.g. 0.05 for 5%.
periods:
type: number
description: Bond periods to maturity (integer).
frequency:
type: number
description: Bond coupon payments per year (default 2 = semiannual).
price:
type: number
description: Bond clean price; supply to solve yield-to-maturity.
yield:
type: number
description: Bond annual yield; supply to solve price. Provide exactly one of price or yield.
principal:
type: number
description: Loan principal (presence selects loan mode).
annualRate:
type: number
description: Loan annual interest rate as a fraction, e.g. 0.06.
termMonths:
type: number
description: Loan term in months (integer).
required: []
example:
faceValue: 1000
couponRate: 0.05
periods: 10
frequency: 2
yield: 0.06
responses:
'200':
description: BondLens result
content:
application/json:
schema:
type: object
example:
service: bondlens
requestId: bl-8e084b70
type: bond
bond:
price: 957.348986
yieldToMaturity: 0.06
currentYield: 0.052228
couponPerPeriod: 25
totalCoupons: 250
macaulayDurationYears: 4.471679
modifiedDurationYears: 4.341436
convexityYears: 22.304728
priceValuation: discount
loan: null
findings:
- rule: bond-valuation
severity: info
why: Whether the bond trades above (premium), below (discount), or at par.
evidence: price=957.348986 face=1000 -> discount
fix: null
'400':
description: Invalid request
'402':
description: Payment required - x402 challenge in PAYMENT-REQUIRED header
headers:
PAYMENT-REQUIRED:
schema:
type: string
description: Base64-encoded x402 payment challenge
'503':
description: x402 not configured
/api/agent-services/options/price:
post:
summary: OptionLens
description: Deterministic Black-Scholes-Merton European option pricing and Greeks. Returns price, d1/d2, full Greeks (delta, gamma, vega, theta, rho) in canonical and conventional display units (vega per 1%, theta per day, rho per 1%), plus intrinsic value, time value, and moneyness. Supports continuous dividend yield. Pure math from caller-supplied parameters — no market-data feed, no fabrication.
operationId: options_price
tags:
- finance
x-payment-info:
price:
mode: fixed
currency: USD
amount: '0.25'
protocols:
- x402: {}
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
spot:
type: number
description: Current price of the underlying (> 0).
strike:
type: number
description: Option strike price (> 0).
timeToExpiry:
type: number
description: Time to expiry in years (e.g. 0.5 = 6 months).
volatility:
type: number
description: Annualized volatility (sigma) as a fraction, e.g. 0.2 for 20%.
riskFreeRate:
type: number
description: Annual continuously-compounded risk-free rate, e.g. 0.05 (default 0).
dividendYield:
type: number
description: Annual continuous dividend yield, e.g. 0.02 (default 0).
optionType:
type: string
description: '''call'' or ''put'' (default ''call'').'
required:
- spot
- strike
- timeToExpiry
- volatility
example:
spot: 100
strike: 100
timeToExpiry: 1
riskFreeRate: 0.05
volatility: 0.2
optionType: call
responses:
'200':
description: OptionLens result
content:
application/json:
schema:
type: object
example:
service: optionlens
requestId: opt-db556a1a
optionType: call
price: 10.450576
d1: 0.35
d2: 0.15
intrinsicValue: 0
timeValue: 10.450576
moneyness: at-the-money
greeks:
delta: 0.636831
gamma: 0.018762
vega: 37.524035
vegaPer1Pct: 0.37524
theta: -6.414028
thetaPerDay: -0.017573
rho: 53.232483
rhoPer1Pct: 0.532325
findings:
- rule: valuation
severity: info
why: Black-Scholes-Merton valuation summary.
evidence: price=10.4506 d1=0.35 d2=0.15 moneyness=at-the-money
fix: null
'400':
description: Invalid request
'402':
description: Payment required - x402 challenge in PAYMENT-REQUIRED header
headers:
PAYMENT-REQUIRED:
schema:
type: string
description: Base64-encoded x402 payment challenge
'503':
description: x402 not configured
/api/agent-services/dealanalyzer/analyze:
post:
summary: DealAnalyzer
description: 'Premium deal underwriting in one deterministic call: a DCF valuation (enterprise value, equity value, implied share price; Gordon-growth or exit-multiple terminal), equity returns (IRR/XIRR, NPV, MOIC, payback), a discount-rate × terminal-assumption sensitivity grid, and the LP/GP distribution waterfall on the proceeds. Pure math from caller-provided inputs — no market-data feed, no fabrication — with evidence-backed findings on every section and a signed response receipt.'
operationId: dealanalyzer_analyze
tags:
- finance
x-payment-info:
price:
mode: fixed
currency: USD
amount: '0.25'
protocols:
- x402: {}
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
dcf:
type: object
description: Required. DCF valuation inputs.
properties:
cashflows:
type: array
items:
type: number
description: Projected free cash flows for t = 1..n.
discountRate:
type: number
description: WACC, e.g. 0.10.
terminalGrowth:
type: number
description: Gordon-growth terminal rate (needs discountRate > terminalGrowth).
exitMultiple:
type: number
description: Terminal = exitMultiple * last FCF (overrides terminalGrowth).
netDebt:
type: number
description: Net debt to bridge enterprise value to equity value.
shares:
type: number
description: Share count for implied per-share value.
required:
- cashflows
- discountRate
returns:
type: object
description: Optional. Equity cash-flow stream for IRR/XIRR, NPV, MOIC, payback.
properties:
cashflows:
type: array
description: Numbers (periodic) or {amount, date} objects (dated => XIRR). Outflows negative.
discountRate:
type: number
description: Annual rate for NPV and the NPV sensitivity sweep.
periodsPerYear:
type: number
description: Annualize a periodic IRR (default 1).
nav:
type: number
description: Residual value, added to inflows for MOIC.
required:
- cashflows
waterfall:
type: object
description: Optional. LP/GP distribution terms. distributable defaults to the DCF equity value.
properties:
contributedCapital:
type: number
description: LP capital to return first; defaults to the invested equity from returns.cashflows.
distributable:
type: number
description: Proceeds to distribute; defaults to the DCF equity value.
carryPercentage:
type: number
description: GP carried interest, e.g. 0.20 (default).
catchUpPercentage:
type: number
description: GP share during catch-up; 1.0 = full catch-up (default).
preferredReturnAmount:
type: number
description: Explicit preferred return $ (overrides rate).
preferredRate:
type: number
description: Preferred return rate, e.g. 0.08.
years:
type: number
description: Years for the preferred return.
compounding:
type: string
description: '''compounded'' (default) or ''simple''.'
required:
- contributedCapital
sensitivity:
type: object
description: Optional. Additive deltas swept around the base case.
properties:
discountRateDeltas:
type: array
items:
type: number
description: e.g. [-0.02,-0.01,0,0.01,0.02].
terminalGrowthDeltas:
type: array
items:
type: number
description: Used when the DCF uses Gordon growth.
exitMultipleDeltas:
type: array
items:
type: number
description: Used when the DCF uses an exit multiple.
required:
- dcf
example:
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
catchUpPercentage: 1
preferredRate: 0.08
years: 5
responses:
'200':
description: DealAnalyzer result
content:
application/json:
schema:
type: object
example:
service: dealanalyzer
requestId: deal-1a2b3c4d
valuation:
enterpriseValue: 1646.18
equityValue: 1346.18
impliedSharePrice: 13.46
terminalMethod: exit-multiple
returns:
mode: periodic
irrAnnual: 0.1599
npv: 246.27
moic: 2.1
paybackPeriod: 5
sensitivity:
axis: exit-multiple
enterpriseValueRange:
min: 1409.32
max: 1883.04
waterfall:
distributable: 1346.18
distributableSource: dcf-equity-value
gpCarry: 18.55
effectiveGpCarryPct: 0.2
findings:
- rule: valuation
severity: info
why: Base-case DCF valuation.
evidence: method=exit-multiple
fix: null
'400':
description: Invalid request
'402':
description: Payment required - x402 challenge in PAYMENT-REQUIRED header
headers:
PAYMENT-REQUIRED:
schema:
type: string
description: Base64-encoded x402 payment challenge
'503':
description: x402 not configured
components:
securitySchemes:
oauth2:
type: oauth2
description: Register at POST /api/auth/register, then obtain a token from POST /api/auth/token using client_credentials.
flows:
clientCredentials:
tokenUrl: https://hermesplant.com/api/auth/token
scopes:
catalog:read: Read the product catalog
checkout:create: Start checkout sessions
billing:manage: Open Stripe billing portal for subscribers
assuranceBearer:
type: http
scheme: bearer
description: Organization-scoped Hermes Plant bearer token. A signed-in organization session is also accepted by the application.
externalDocs:
description: API documentation, error contract, pricing, and changelog
url: https://hermesplant.com/docs/api