Quick start
Three minutes from zero to your first minted forecast (assuming you've already obtained a JWT or AP2 mandate from your principal):
curl -X POST https://phronesis-jrstinehour.replit.app/forecast/mint \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $PHRONESIS_JWT" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"vertical": "V1",
"archetype": "E1",
"subject": "ERCOT_summer_capacity_factor_2027",
"horizon": "2027-Q3"
}'The response includes the canonical FC-ID, the canonical-quantile estimates, the issue timestamp, and the cost-attestation in dollars-and-cents. Every value persisted to the Mnemosyne ledger; every value visible on the public scorecard.
Endpoints
Authentication
Path A — Direct API (autonomous agents)
Autonomous agents authenticate by presenting an AP2 (Google Agent Payments Protocol) mandate at the Hermes contract-middleware authorization gate. The mandate must include both an Intent Mandate and a Cart Mandate Verifiable Credential signed by the principal. Mandate signature verification budget is approximately two to five seconds at the blocking gate.
POST /forecast/mint HTTP/1.1
Host: phronesis-jrstinehour.replit.app
Content-Type: application/json
Idempotency-Key: 01HXYZA1B2C3D4E5F6G7H8J9K0
Authorization: AP2-Mandate <base64-encoded-VC-bundle>
{
"vertical": "V1",
"archetype": "E1",
"subject": "ERCOT_summer_capacity_factor_2027",
"horizon": "2027-Q3"
}Path B — Agentic commerce (agents acting for humans)
Agents acting on behalf of human principals via the Stripe Agentic Commerce Suite (ACS) checkout flow present a Stripe Shared Payment Token (SPT) bound to an AP2 Cart Mandate at issuance time. The SPT replaces the AP2-direct authorization for the per-call settlement.
Path C — Direct human SaaS (T1-T4 subscribers)
Human subscribers authenticate via Bearer JWT issued at login. Subscription tier (T1 Starter, T2 Professional, T3 Team, T4 Enterprise) determines included usage allowances and overage rates. See /pricing.
Idempotency
Every mutating endpoint requires the Idempotency-Key header. Keys are persisted to the Mnemosyne idempotency archive for a minimum of seventy-two hours. Repeat requests with the same key return the original response without side effects, regardless of whether the original was successful.
Recommended key shape: ULID or UUIDv7. Maximum length: 256 characters. Keys must be unique per principal-tenant; collisions across tenants do not interfere due to per-tenant isolation at the boundary publish layer.
Error semantics
Errors are structured with stable machine-recoverable codes. Sixteen-code enumeration covers the canonical failure modes:
{
"error": {
"code": "MANDATE_INVALID_SIGNATURE",
"message": "AP2 mandate signature verification failed",
"category": "auth",
"retryable": false,
"documentation_url": "https://phronesisintel.com/spec#errors",
"request_id": "req_01HXYZA1B2C3D4E5F6G7H8J9K0"
}
}Code categories: auth (mandate or JWT failure) · validation (request shape error) · rate_limit (per-tenant or per-mandate limit hit) · circuit (downstream circuit-breaker tripped) · substrate (canonical-correctness violation) · billing (Plutus charge failure) · not_found · internal. Retryable errors include rate_limit and circuit; all others are non-retryable.
Meter events and pricing
Forecast minting fires a Stripe meter event at the moment of canonical persistence to the Mnemosyne ledger. Meter event amounts are reported with sub-cent precision (Decimal lift, no float). Cost-attestation per call is published at /pricing.json and includes the inference cost component plus the markup multiplier.
MCP server
The MCP server exposes tools that are one-to-one with REST endpoints. Tool names map to endpoint paths; tool parameters map to request bodies. Tool outputs match REST response shapes exactly. Use either surface; neither is privileged.
// MCP tool list (representative)
{
"tools": [
{ "name": "forecast_mint", "description": "Mint a probabilistic forecast" },
{ "name": "forecast_get", "description": "Retrieve forecast by FC-ID" },
{ "name": "scorecard_get", "description": "Read calibration scorecard" },
{ "name": "billing_charge","description": "Settle per-call meter event" }
]
}Verticals and archetypes
Eight verticals; five live on production; archetype taxonomy is per-vertical. See the verticals page for archetype detail. Canonical taxonomy is reflected in the OpenAPI spec.
Discovery surfaces
For agent crawlers: agents.txt · agentic-commerce.json · openapi.json · pricing.json · robots.txt
Versioning
The Hermes contract surface uses semantic versioning at the contract layer. Breaking changes go to a new major version with a six-month deprecation window for the prior major. Non-breaking additions (new endpoints, new optional fields) are added in minor versions and announced via the changelog.
SLA and limits
Production runtime is dedicated 24/7 (Reserved VM). Per-tenant rate limits and per-mandate burst limits documented at /spec#rate-limits (in development). Service credits available for 24+ hour continuous outage per the Refund Policy.
Support
Issues, integration questions, contract clarifications: write to the support email published on the Sustainable Finance Partners Contact page. Bug reports against the contract surface are triaged at the Iris ring (Phronesis customer relations substrate); critical contract violations are escalated immediately per Sacred Invariant #9 boundary-as-only-publish.