Hermes Plant API
Public endpoints for AI agents and automated clients. Catalog and checkout APIs are open; billing portal requires a Bearer token with the billing:manage scope. Register agents via auth.md.
Agent Commerce Assurance
Team and Business organizations can authorize exact x402 or MCP purchase intents before execution, then attach execution evidence to a signed receipt. Use a signed-in organization session or an organization bearer token. Hermes Plant does not hold signing keys or execute the payment.
| Method | Path | Purpose |
|---|---|---|
| POST | /api/assurance/decisions | Signed allow, deny, or review decision bound to the exact action. |
| POST | /api/assurance/receipts | Signed receipt binding execution evidence to a prior decision. |
| GET | /api/assurance/history | Organization-scoped decision and receipt history. |
POST /api/assurance/decisions
Authorization: Bearer <organization-token>
Content-Type: application/json
{
"protocol": "x402",
"idempotencyKey": "purchase-2026-07-10-001",
"subject": { "runId": "run-001", "agentId": "buyer-agent", "purpose": "vendor report" },
"policy": {
"policyId": "purchasing-v1",
"version": 1,
"maxUsdPerTransaction": 10,
"allowedNetworks": ["eip155:8453"],
"requireHttps": true,
"requireResourceBinding": true
},
"intent": {
"resourceUrl": "https://vendor.example/api/report",
"method": "POST",
"network": "eip155:8453",
"asset": "USDC",
"amountUsd": 5,
"payTo": "0x..."
}
}Idempotency is content-bound: reusing a key with different action content is rejected. Signatures fail closed when the server signing secret is unavailable. Active probes are limited to supported allowlisted checks; arbitrary URLs are not fetched.
Quickstart — first call in 60 seconds (no crypto wallet)
Get a free key (250 metered calls/month across every endpoint), then call any endpoint with an X-API-Key header — no wallet, no x402 signing. These endpoints are built to run inside your agent’s loop — one call per record or action, the same audited answer every time.
# 1. Get a free key (returned once — save it)
curl -s -X POST https://hermesplant.com/api/keys/free \
-H "content-type: application/json" \
-d '{"email":"you@company.com"}'
# → {"apiKey":"hp_free_...", "callsPerMonth":250, ...}
# 2. Call any endpoint with the key — loop over your records
export HERMES_KEY=hp_free_...
for email in alice@gmail.com bob@gnail.com carol@acme.co; do
curl -s https://hermesplant.com/api/agent-services/emailguard/validate \
-H "X-API-Key: $HERMES_KEY" -H "content-type: application/json" \
-d "{\"email\":\"$email\"}"
doneOr validate a whole contact list in 5 lines with the typed SDK (npm i @hermesplant/agent-services) — callBatch loops any endpoint with bounded concurrency, order-preserving results, and per-record errors captured instead of thrown:
import { HermesPlant } from "@hermesplant/agent-services";
const hermes = new HermesPlant({ apiKey: process.env.HERMES_KEY }); // free-tier key
const results = await hermes.emailGuardBatch(contacts.map((c) => ({ email: c.email })));
const clean = results.filter((r) => r.ok); // one deterministic verdict per recordThe batch stops sending after the first 402 (quota exhausted) and marks the remaining records skipped, so you can upgrade and resume. walletGuardBatch screens wallet lists the same way; MCP clients get the same loop as the emailguard_validate_batch tool.
Past 250 calls/month the same call keeps working — upgrade to the $29 Agent API Pass ($35 of public-price-weighted endpoint credits) or pay per call over x402 with no key at all.
Machine-readable discovery
Endpoints
GET /api/healthLiveness check.
GET /api/catalogJSON product catalog with slugs and pricing.
GET /api/checkoutReturns legal policy URLs.
POST /api/checkoutBody: {"slug": "product-slug"}. Returns a Stripe Checkout URL.
POST /api/keys/freeBody: {"email": "you@company.com"}. Issues a free-tier API key (returned once) good for 250 metered calls per calendar month across every agent-services endpoint. Send it as an X-API-Key header (or Authorization: Bearer) on any endpoint below; past the free quota the same call still works per-call over x402.
GET /api/keys/free/statusSend your key as X-API-Key. Returns your plan, calls used, calls remaining, the UTC reset date, and the upgrade path — poll it from agents to budget calls before hitting the cap. At the cap, calls return 429 with an upgradeUrl and a Link rel="upgrade" header; the $29/mo Agent API Pass adds $35 of weighted endpoint credits, and per-call x402 always works with no key at all.
POST /api/billing-portalUses the signed-in customer session, or a claimed agent Bearer token with billing:manage. The customer identity is derived from authentication; caller-supplied email is not accepted.
GET /api/entitlements/{product-slug}Returns 200 only for a live customer entitlement. Active subscriptions must also have an unexpired billing period; canceled, past-due, expired, refunded, and revoked access returns 403.
POST /api/agent-services/action-safety/quickx402-paid agent endpoint ($0.01/call). AI agent action safety: one-cent deterministic preflight for every consequential agent command. Returns risk, matched rule ids, and an exact machine-readable escalation call: full DestructGuard evidence for medium risk or the complete Action Safety workflow for high and critical risk.
POST /api/agent-services/action-safety/runx402-paid agent endpoint ($0.25/call). Complete AI agent action safety workflow for consequential agent actions. Runs the complete DestructGuard evidence score, conditionally creates ReviewQueue triage for high or critical risk, returns an honest allow or needs_review decision, a signed receipt, and a free 30-day status record. Human approval itself requires a connected approval system or hosted Assurance plan.
POST /api/agent-services/x402-provenance/checkx402-paid agent endpoint ($0.05/call). Deterministic provenance analysis for caller-supplied x402 payment records. Excludes duplicate transaction hashes, separates declared owner wallets from candidate external payers, measures concentration and evidence coverage, and states limitations explicitly. It does not fetch the chain or claim wallet independence.
POST /api/agent-services/destructguard/scorex402-paid agent endpoint ($0.10/call). Deterministic risk scorer for autonomous-agent commands. Scores a shell, SQL, or git action for destructive, deployment, and data-mutation risk before execution and returns a risk level, the matched policy rules, and an approve-or-block recommendation. Pure rules, evidence per match, no fabrication.
POST /api/agent-services/reviewqueue/submitx402-paid agent endpoint ($0.25/call). Submit an autonomous-agent command for paid risk triage and human-approval routing. Returns a deterministic risk decision, a request id, whether a human is required, and a recommended action — pause-and-escalate on critical risk. Evidence-backed, nothing fabricated.
POST /api/agent-services/payment-policy/decidex402-paid agent endpoint ($0.05/call). Preflight an x402 payment before an autonomous agent signs it. Checks resource binding, method, scheme, network, asset, amount vs expected price, payTo, facilitator, timeout, replay and idempotency readiness, metadata leakage, buyer spend limits, allow-lists, and optional service-risk signals. Returns allow / deny / needs_review with evidence-backed findings and a redacted, log-safe record. Deterministic policy engine — loop it over every payment your agent makes.
POST /api/agent-services/evidence/verifyx402-paid agent endpoint ($0.05/call). Verify an agent-commerce evidence bundle before trusting a paid result. Checks x402 challenge, receipt, policy-decision, and service-response artifacts; endpoint, method, network, payTo, and price binding; artifact source, freshness, hashes, and synthetic-proof leakage. Returns verified / needs_review / rejected / insufficient_evidence with per-rule evidence. Deterministic — loop it over every paid call in an agent run.
POST /api/agent-services/assurance/attestx402-paid agent endpoint ($0.05/call). Signed receipt for one agent action. Post an x402 payment intent or MCP tool call (optional policy + settlement outcome) and get a canonical HMAC-signed record: binding hash, verdict, findings, and a free public verify URL third parties can check without trusting your agent's logs. Loop it after every payment or tool call to build a tamper-evident audit trail. Canonicalization hermes-stable-json-v1; org history and probes available on Assurance plans.
POST /api/agent-services/mcp-risk/scorex402-paid agent endpoint ($0.05/call). Analyze an MCP server manifest for security risk before install — destructive actions, over-broad scopes, sensitive-data egress, weak auth, prompt-injection surface, and permission diff. Returns per-tool, per-factor findings with severity, why, and a concrete fix (not just a score).
POST /api/agent-services/walletguard/scorex402-paid agent endpoint ($0.10/call). Wallet risk scoring and pre-transaction AML, sanctions, counterparty-risk, and crypto compliance screening for autonomous finance agents. Scores one wallet from caller-provided sanctions hits, exposure tags, counterparty labels, transfers, and fund-source context; returns a 0-100 risk score, evidence per signal, and a concrete action. Deterministic preflight only: no chain data is fetched and no screening result is fabricated.
POST /api/agent-services/emailguard/validatex402-paid agent endpoint ($0.02/call). Email validation API for AI agents. Validates one email per call: RFC 5322 syntax, disposable and temporary domain detection, role-based address, free-provider classification, typo suggestion (gnail.com -> gmail.com), plus-alias normalization to canonical form, and a deliverability score with per-rule evidence. Deterministic - the same record always gets the same answer - no data feed, no network calls. Loop it over your contact list to validate, dedupe, and normalize every record. Signed response receipt included.
POST /api/agent-services/portfolioguard/scorex402-paid agent endpoint ($0.15/call). Deterministic portfolio risk analysis and quality scoring. Computes riskScore, riskLevel, volatility, sharpe, maxDrawdown, concentrationHHI, diversification, effectiveHoldings plus per-rule findings with fixes and sector/position breakdown. Pure math only from caller holdings and returns. No external data.
POST /api/agent-services/cashflowlens/analyzex402-paid agent endpoint ($0.20/call). 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.
POST /api/agent-services/waterfall/distributex402-paid agent endpoint ($0.30/call). 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.
POST /api/agent-services/bond/analyzex402-paid agent endpoint ($0.25/call). Deterministic fixed-income & loan analytics. Bond mode: solve price<->yield-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.
POST /api/agent-services/options/pricex402-paid agent endpoint ($0.30/call). 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.
POST /api/agent-services/dealanalyzer/analyzex402-paid agent endpoint ($2.00/call). 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.
POST /api/agent-services/spend-assurance/runx402-paid agent endpoint ($0.25/call). One signed preflight for an autonomous x402 payment: WalletGuard counterparty screening, Payment Policy challenge validation, and structured evidence verification. Returns allow, deny, or needs_review plus the component findings and a tamper-evident service receipt. Caller-provided wallet context only; no external chain-intelligence feed.
POST /api/agent-services/investment-evidence/analyzex402-paid agent endpoint ($0.45/call). CashflowLens return and DCF analytics plus PortfolioGuard concentration and risk scoring in one paid call, with structured internal evidence and a tamper-evident signed receipt. Pure math from caller-provided cashflows, holdings, and returns; no market-data feed and no claim that inputs are independently verified.
Go from docs to production calls
Start with endpoint schemas, then choose your commercial path. Use pay-per-call for immediate usage or move to recurring plans when your agent workload scales.
Support
Questions about billing or delivery? Email contact@hermesplant.com.