{ "openapi": "3.1.0", "info": { "title": "Hermes Plant - Agent Action Safety and Commerce Assurance API", "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" } } }, "externalDocs": { "description": "API documentation, error contract, pricing, and changelog", "url": "https://hermesplant.com/docs/api" }, "servers": [ { "url": "https://hermesplant.com" } ], "paths": { "/api/health": { "get": { "summary": "Health check", "operationId": "getHealth", "security": [], "responses": { "200": { "description": "Service is healthy", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "ok" }, "site": { "type": "string", "format": "uri" }, "name": { "type": "string" } }, "required": [ "status", "site", "name" ] } } } } } } }, "/api/catalog": { "get": { "summary": "List products", "operationId": "listProducts", "security": [], "responses": { "200": { "description": "Product catalog", "content": { "application/json": { "schema": { "type": "object", "properties": { "products": { "type": "array", "items": { "$ref": "#/components/schemas/ProductSummary" } } }, "required": [ "products" ] } } } } } } }, "/api/checkout": { "get": { "summary": "Checkout policy URLs", "operationId": "getCheckoutInfo", "security": [], "responses": { "200": { "description": "Legal policy URLs and usage hint", "content": { "application/json": { "schema": { "type": "object", "properties": { "policies": { "$ref": "#/components/schemas/LegalUrls" }, "message": { "type": "string" } } } } } } } }, "post": { "summary": "Start Stripe checkout", "operationId": "createCheckoutSession", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "slug": { "type": "string", "description": "Product slug from the catalog" } }, "required": [ "slug" ] } } } }, "responses": { "200": { "description": "Stripe Checkout session URL", "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" } }, "required": [ "url" ] } } } }, "400": { "description": "Missing or invalid product slug" }, "404": { "description": "Product not found" }, "503": { "description": "Stripe not configured" } } } }, "/api/purchase/{slug}": { "get": { "summary": "Probe x402 challenge for one-time product purchases", "operationId": "probePurchaseWithX402", "x-payment-info": { "mode": "fixed", "currency": "USD", "protocols": [ "x402" ] }, "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string", "example": "destructguard-pro" }, "description": "Product slug from the catalog" } ], "responses": { "200": { "description": "Purchase fulfilled with download URL", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "fulfilled" }, "product": { "type": "string" }, "downloadUrl": { "type": "string", "format": "uri" }, "expiresAt": { "type": "string", "format": "date-time" } }, "required": [ "status", "product", "downloadUrl", "expiresAt" ] } } } }, "400": { "description": "Subscription product or invalid purchase" }, "402": { "description": "Payment required — x402 challenge in PAYMENT-REQUIRED header", "headers": { "PAYMENT-REQUIRED": { "description": "Base64-encoded x402 PaymentRequired payload", "schema": { "type": "string" } } } }, "404": { "description": "Product not found" }, "503": { "description": "x402 not configured" } } }, "post": { "summary": "Purchase a one-time product via x402", "operationId": "purchaseWithX402", "x-payment-info": { "mode": "fixed", "currency": "USD", "protocols": [ "x402" ] }, "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string", "example": "destructguard-pro" }, "description": "Product slug from the catalog" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "description": "Optional email for the order record" } } } } } }, "responses": { "200": { "description": "Purchase fulfilled with download URL", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "fulfilled" }, "product": { "type": "string" }, "downloadUrl": { "type": "string", "format": "uri" }, "expiresAt": { "type": "string", "format": "date-time" } }, "required": [ "status", "product", "downloadUrl", "expiresAt" ] } } } }, "400": { "description": "Subscription product or invalid purchase" }, "402": { "description": "Payment required — x402 challenge in PAYMENT-REQUIRED header", "headers": { "PAYMENT-REQUIRED": { "description": "Base64-encoded x402 PaymentRequired payload", "schema": { "type": "string" } } } }, "404": { "description": "Product not found" }, "503": { "description": "x402 not configured" } } } }, "/api/content": { "get": { "summary": "List indexable pSEO content pages", "operationId": "listContent", "security": [], "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 20, "maximum": 100 } }, { "name": "type", "in": "query", "schema": { "type": "string", "enum": [ "commands", "guides", "faq", "tools", "compare", "explore" ] }, "description": "Filter by URL path prefix" } ], "responses": { "200": { "description": "Paginated content pages", "content": { "application/json": { "schema": { "type": "object", "properties": { "site": { "type": "string", "format": "uri" }, "page": { "type": "integer" }, "limit": { "type": "integer" }, "total": { "type": "integer" }, "pages": { "type": "array", "items": { "$ref": "#/components/schemas/ContentPage" } } }, "required": [ "site", "page", "limit", "total", "pages" ] } } } } } } }, "/api/billing-portal": { "get": { "summary": "Billing portal endpoint usage", "operationId": "getBillingPortalInfo", "security": [], "responses": { "200": { "description": "How to call the billing portal endpoint", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "requiresAuth": { "type": "boolean" }, "scope": { "type": "string" } }, "required": [ "message", "requiresAuth", "scope" ] } } } } } }, "post": { "summary": "Open Stripe billing portal", "operationId": "createBillingPortalSession", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "description": "Email with an active subscription" } }, "required": [ "email" ] } } } }, "responses": { "200": { "description": "Stripe billing portal URL", "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" } }, "required": [ "url" ] } } } }, "400": { "description": "Email required" }, "404": { "description": "No active subscription" }, "503": { "description": "Stripe not configured" } } } }, "/api/assurance/decisions": { "post": { "tags": [ "Agent Commerce Assurance" ], "summary": "Authorize an exact agent purchase", "description": "Evaluates the immutable administrator-activated organization policy and returns a signed allow, deny, or needs_review decision. A caller policy is only a compatibility assertion and cannot weaken the active policy.", "security": [ { "assuranceBearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "protocol", "idempotencyKey", "subject", "intent" ], "properties": { "protocol": { "type": "string", "enum": [ "x402", "mcp" ] }, "idempotencyKey": { "type": "string", "minLength": 1, "maxLength": 200 }, "subject": { "type": "object", "required": [ "runId" ], "properties": { "runId": { "type": "string" }, "agentId": { "type": "string" }, "purpose": { "type": "string" } } }, "policy": { "type": "object", "required": [ "policyId", "version" ], "properties": { "policyId": { "type": "string" }, "version": { "type": "integer", "minimum": 1 }, "maxUsdPerTransaction": { "type": "number", "minimum": 0 }, "allowedNetworks": { "type": "array", "items": { "type": "string" } }, "allowedPayTo": { "type": "array", "items": { "type": "string" } }, "allowedHosts": { "type": "array", "items": { "type": "string" } }, "blockedHosts": { "type": "array", "items": { "type": "string" } }, "allowedMcpServers": { "type": "array", "items": { "type": "string" } }, "allowedMcpTools": { "type": "array", "items": { "type": "string" } }, "blockedMcpTools": { "type": "array", "items": { "type": "string" } }, "requireExactScheme": { "type": "boolean" }, "requireHttps": { "type": "boolean" }, "requireResourceBinding": { "type": "boolean" }, "requirePaymentIdentifier": { "type": "boolean" }, "requireMcpArgumentBinding": { "type": "boolean" }, "reviewMcpRiskAtOrAbove": { "type": "string", "enum": [ "medium", "high", "critical" ] } } }, "intent": { "oneOf": [ { "type": "object", "required": [ "resourceUrl", "method" ], "properties": { "resourceUrl": { "type": "string", "format": "uri" }, "method": { "type": "string" }, "scheme": { "type": "string" }, "network": { "type": "string" }, "asset": { "type": "string" }, "payTo": { "type": "string" }, "amountUnits": { "type": "string" }, "amountUsd": { "type": "number" }, "facilitatorUrl": { "type": "string", "format": "uri" }, "paymentIdentifier": { "type": "string" }, "paymentPayloadResource": { "type": "string" }, "paymentPayloadMethod": { "type": "string" } } }, { "type": "object", "required": [ "serverId", "toolName" ], "properties": { "serverId": { "type": "string" }, "serverUrl": { "type": "string", "format": "uri" }, "toolName": { "type": "string" }, "toolArguments": {}, "toolArgumentsHash": { "type": "string" }, "declaredRisk": { "type": "string", "enum": [ "low", "medium", "high", "critical" ] } } } ] } } } } } }, "responses": { "200": { "description": "Idempotent replay of signed record", "content": { "application/json": { "schema": { "type": "object" } } } }, "201": { "description": "Signed record created", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "401": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "403": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "409": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "413": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "503": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } } } } }, "/api/assurance/receipts": { "post": { "tags": [ "Agent Commerce Assurance" ], "summary": "Record execution evidence", "description": "Binds observed execution evidence to the exact signed decision and returns a signed receipt.", "security": [ { "assuranceBearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "decisionId", "decisionRecordHash", "bindingHash", "protocol", "outcome" ], "properties": { "decisionId": { "type": "string" }, "decisionRecordHash": { "type": "string" }, "bindingHash": { "type": "string" }, "protocol": { "type": "string", "enum": [ "x402", "mcp" ] }, "settlementId": { "type": "string" }, "outcome": { "type": "string", "enum": [ "fulfilled", "failed", "rejected" ] }, "observedAt": { "type": "string", "format": "date-time" }, "evidenceHashes": { "type": "array", "items": { "type": "string" } }, "responseStatus": { "type": "integer", "minimum": 100, "maximum": 599 }, "responseBodyHash": { "type": "string", "pattern": "^[a-f0-9]{64}$" } } } } } }, "responses": { "200": { "description": "Idempotent replay of signed record", "content": { "application/json": { "schema": { "type": "object" } } } }, "201": { "description": "Signed record created", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "401": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "403": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "409": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "413": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "503": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } } } } }, "/api/assurance/history": { "get": { "tags": [ "Agent Commerce Assurance" ], "summary": "List assurance history", "description": "Returns organization-scoped decisions and receipts. Limit is clamped to 1-100.", "security": [ { "assuranceBearer": [] } ], "parameters": [ { "in": "query", "name": "limit", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } } ], "responses": { "200": { "description": "Organization assurance history", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "403": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "503": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } } } } }, "/api/agent-workflows/action-safety/status/{workflowId}": { "get": { "summary": "Get Action Safety workflow status", "description": "Returns the free retained status for a complete Action Safety workflow. New records expose the versioned canonical action binding; legacy records explicitly report that a versioned binding is unavailable.", "operationId": "get_action_safety_workflow_status", "tags": [ "action-safety", "workflow", "status" ], "parameters": [ { "name": "workflowId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^asw_[0-9a-f-]{36}$" }, "description": "Workflow id returned by the complete Action Safety workflow." } ], "responses": { "200": { "description": "Persisted workflow status", "content": { "application/json": { "schema": { "oneOf": [ { "title": "Versioned action binding", "type": "object", "required": [ "workflowId", "status", "risk", "decision", "requiresHumanReview", "audit", "createdAt", "expiresAt", "boundaries", "actionBindingVersion", "actionHash" ], "properties": { "workflowId": { "type": "string", "pattern": "^asw_[0-9a-f-]{36}$" }, "status": { "type": "string", "enum": [ "completed", "review_required" ] }, "risk": { "type": "string", "enum": [ "low", "medium", "high", "critical" ] }, "decision": { "type": "string", "enum": [ "allow", "allow_with_controls", "needs_review" ] }, "requiresHumanReview": { "type": "boolean" }, "audit": { "type": "object", "required": [ "destructGuardRequestId", "reviewQueueRequestId" ], "properties": { "destructGuardRequestId": { "type": [ "string", "null" ] }, "reviewQueueRequestId": { "type": [ "string", "null" ] } } }, "createdAt": { "type": "string" }, "expiresAt": { "type": "string" }, "receipt": { "type": "object", "required": [ "record", "integrity", "verify" ], "properties": { "record": { "type": "object" }, "integrity": { "type": "object" }, "verify": { "type": "object", "required": [ "url", "method" ], "properties": { "url": { "type": "string", "format": "uri" }, "method": { "type": "string", "const": "POST" } } } } }, "boundaries": { "type": "object", "required": [ "humanApprovalIncluded", "note" ], "properties": { "humanApprovalIncluded": { "type": "boolean", "const": false }, "note": { "type": "string" } } }, "actionBindingVersion": { "type": "string", "const": "hermes-action-v1" }, "actionHash": { "type": "string", "pattern": "^[a-f0-9]{64}$" } } }, { "title": "Legacy record without versioned action binding", "type": "object", "required": [ "workflowId", "status", "risk", "decision", "requiresHumanReview", "audit", "createdAt", "expiresAt", "boundaries", "binding" ], "properties": { "workflowId": { "type": "string", "pattern": "^asw_[0-9a-f-]{36}$" }, "status": { "type": "string", "enum": [ "completed", "review_required" ] }, "risk": { "type": "string", "enum": [ "low", "medium", "high", "critical" ] }, "decision": { "type": "string", "enum": [ "allow", "allow_with_controls", "needs_review" ] }, "requiresHumanReview": { "type": "boolean" }, "audit": { "type": "object", "required": [ "destructGuardRequestId", "reviewQueueRequestId" ], "properties": { "destructGuardRequestId": { "type": [ "string", "null" ] }, "reviewQueueRequestId": { "type": [ "string", "null" ] } } }, "createdAt": { "type": "string" }, "expiresAt": { "type": "string" }, "receipt": { "type": "object", "required": [ "record", "integrity", "verify" ], "properties": { "record": { "type": "object" }, "integrity": { "type": "object" }, "verify": { "type": "object", "required": [ "url", "method" ], "properties": { "url": { "type": "string", "format": "uri" }, "method": { "type": "string", "const": "POST" } } } } }, "boundaries": { "type": "object", "required": [ "humanApprovalIncluded", "note" ], "properties": { "humanApprovalIncluded": { "type": "boolean", "const": false }, "note": { "type": "string" } } }, "binding": { "type": "object", "required": [ "available", "reason" ], "properties": { "available": { "type": "boolean", "const": false }, "reason": { "type": "string", "const": "legacy_status_record_without_versioned_action_binding" } } } } } ] } } } }, "400": { "description": "Invalid workflow id", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "404": { "description": "Workflow status not found or expired", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "503": { "description": "Workflow status is temporarily unavailable", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } } } }, "/api/agent-services/action-safety/quick": { "post": { "summary": "Agent Action Safety Quick Gate", "description": "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.", "operationId": "action_safety_quick_gate", "tags": [ "agent-safety", "preflight", "ai-agents", "x402", "approval-routing", "ai-agent-action-safety", "loop-callable" ], "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.01" }, "protocols": [ { "x402": {} } ] }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "command": { "type": "string", "minLength": 1, "pattern": "^(?:\\S|\\S[\\s\\S]*\\S)$", "maxLength": 2000, "description": "Exact shell, SQL, Git, deploy, cloud, MCP, wallet, or x402 action to preflight." }, "repo": { "type": "string", "minLength": 1, "pattern": "^(?:\\S|\\S[\\s\\S]*\\S)$", "maxLength": 500 }, "cwd": { "type": "string", "minLength": 1, "pattern": "^(?:\\S|\\S[\\s\\S]*\\S)$", "maxLength": 500 }, "branch": { "type": "string", "minLength": 1, "pattern": "^(?:\\S|\\S[\\s\\S]*\\S)$", "maxLength": 500 }, "actor": { "type": "string", "minLength": 1, "pattern": "^(?:\\S|\\S[\\s\\S]*\\S)$", "maxLength": 500 }, "intent": { "type": "string", "minLength": 1, "pattern": "^(?:\\S|\\S[\\s\\S]*\\S)$", "maxLength": 1000 }, "diffStat": { "type": "string", "minLength": 1, "pattern": "^(?:\\S|\\S[\\s\\S]*\\S)$", "maxLength": 1500 }, "environment": { "type": "string", "minLength": 1, "pattern": "^(?:\\S|\\S[\\s\\S]*\\S)$", "maxLength": 500 }, "target": { "type": "string", "minLength": 1, "pattern": "^(?:\\S|\\S[\\s\\S]*\\S)$", "maxLength": 1000 }, "commit": { "type": "string", "minLength": 1, "pattern": "^(?:\\S|\\S[\\s\\S]*\\S)$", "maxLength": 200 }, "diffHash": { "type": "string", "minLength": 1, "pattern": "^(?:\\S|\\S[\\s\\S]*\\S)$", "maxLength": 200 }, "failClosedOnUnmatched": { "type": "boolean", "description": "When true, an unmatched consequential action routes to review instead of returning low risk." } }, "required": [ "command" ] }, "example": { "command": "git push --force-with-lease origin main", "environment": "production", "target": "origin/main", "commit": "abc123", "diffHash": "sha256:def456", "failClosedOnUnmatched": true, "repo": "github.com/acme/app", "branch": "main", "actor": "codex", "intent": "release the verified production build" } } } }, "responses": { "200": { "description": "Agent Action Safety Quick Gate result", "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "service", "risk", "requiresApproval", "matchedRuleIds", "actionBindingVersion", "actionHash", "nextRecommendedCall" ], "properties": { "status": { "type": "string", "const": "scored" }, "service": { "type": "string", "const": "action-safety-quick-gate" }, "risk": { "type": "string", "enum": [ "low", "medium", "high", "critical" ] }, "requiresApproval": { "type": "boolean" }, "matchedRuleIds": { "type": "array", "items": { "type": "string" } }, "actionBindingVersion": { "type": "string", "const": "hermes-action-v1" }, "actionHash": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "nextRecommendedCall": { "type": [ "object", "null" ] } } }, "example": { "status": "scored", "service": "action-safety-quick-gate", "risk": "critical", "requiresApproval": true, "matchedRuleIds": [ "git.force-push" ], "actionBindingVersion": "hermes-action-v1", "actionHash": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "nextRecommendedCall": { "method": "POST", "path": "/api/agent-services/action-safety/run", "priceCents": 25 } } } } }, "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/action-safety/run": { "post": { "summary": "Agent Action Safety Loop", "description": "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.", "operationId": "agent_action_safety_loop", "tags": [ "agent-safety", "approval-workflow", "ai-agents", "x402", "review-triage", "ai-agent-action-safety", "signed-receipt" ], "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.25" }, "protocols": [ { "x402": {} } ] }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "command": { "type": "string", "minLength": 1, "pattern": "^(?:\\S|\\S[\\s\\S]*\\S)$", "maxLength": 2000, "description": "Exact shell, SQL, Git, deploy, cloud, MCP, wallet, or x402 action to assess." }, "repo": { "type": "string", "minLength": 1, "pattern": "^(?:\\S|\\S[\\s\\S]*\\S)$", "maxLength": 500 }, "cwd": { "type": "string", "minLength": 1, "pattern": "^(?:\\S|\\S[\\s\\S]*\\S)$", "maxLength": 500 }, "branch": { "type": "string", "minLength": 1, "pattern": "^(?:\\S|\\S[\\s\\S]*\\S)$", "maxLength": 500 }, "actor": { "type": "string", "minLength": 1, "pattern": "^(?:\\S|\\S[\\s\\S]*\\S)$", "maxLength": 500 }, "intent": { "type": "string", "minLength": 1, "pattern": "^(?:\\S|\\S[\\s\\S]*\\S)$", "maxLength": 1000 }, "diffStat": { "type": "string", "minLength": 1, "pattern": "^(?:\\S|\\S[\\s\\S]*\\S)$", "maxLength": 1500 }, "environment": { "type": "string", "minLength": 1, "pattern": "^(?:\\S|\\S[\\s\\S]*\\S)$", "maxLength": 500 }, "target": { "type": "string", "minLength": 1, "pattern": "^(?:\\S|\\S[\\s\\S]*\\S)$", "maxLength": 1000 }, "commit": { "type": "string", "minLength": 1, "pattern": "^(?:\\S|\\S[\\s\\S]*\\S)$", "maxLength": 200 }, "diffHash": { "type": "string", "minLength": 1, "pattern": "^(?:\\S|\\S[\\s\\S]*\\S)$", "maxLength": 200 }, "failClosedOnUnmatched": { "type": "boolean", "description": "When true, an unmatched consequential action routes to review." } }, "required": [ "command" ] }, "example": { "command": "wrangler deploy", "repo": "github.com/acme/app", "branch": "main", "environment": "production", "target": "hermes-api", "commit": "abc123", "diffHash": "sha256:def456", "failClosedOnUnmatched": true, "actor": "codex", "intent": "deploy the verified release", "diffStat": "12 files changed" } } } }, "responses": { "200": { "description": "Agent Action Safety Loop result", "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "service", "workflowId", "decision", "risk", "allowed", "requiresHumanReview", "actionBindingVersion", "actionHash", "boundaries", "nextRecommendedCall", "statusUrl" ], "properties": { "status": { "type": "string", "enum": [ "completed", "review_required" ] }, "service": { "type": "string", "const": "agent-action-safety-loop" }, "workflowId": { "type": "string", "pattern": "^asw_[0-9a-f-]{36}$" }, "decision": { "type": "string", "enum": [ "allow", "allow_with_controls", "needs_review" ] }, "risk": { "type": "string", "enum": [ "low", "medium", "high", "critical" ] }, "allowed": { "type": "boolean" }, "requiresHumanReview": { "type": "boolean" }, "actionBindingVersion": { "type": "string", "const": "hermes-action-v1" }, "actionHash": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "boundaries": { "type": "object", "required": [ "humanApprovalIncluded", "note" ], "properties": { "humanApprovalIncluded": { "type": "boolean", "const": false }, "note": { "type": "string" } } }, "nextRecommendedCall": { "type": "object" }, "statusUrl": { "type": "string", "format": "uri" } } }, "example": { "status": "review_required", "service": "agent-action-safety-loop", "workflowId": "asw_00000000-0000-4000-8000-000000000000", "decision": "needs_review", "risk": "high", "allowed": false, "requiresHumanReview": true, "actionBindingVersion": "hermes-action-v1", "actionHash": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "statusUrl": "https://hermesplant.com/api/agent-workflows/action-safety/status/asw_00000000-0000-4000-8000-000000000000", "boundaries": { "humanApprovalIncluded": false, "note": "Review triage only." }, "nextRecommendedCall": { "method": "GET", "path": "/api/agent-workflows/action-safety/status/asw_00000000-0000-4000-8000-000000000000", "priceCents": 0 } } } } }, "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/x402-provenance/check": { "post": { "summary": "x402 Demand Provenance Check", "description": "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.", "operationId": "x402_demand_provenance", "tags": [ "x402", "provenance", "ai-agents", "demand-analysis", "anti-sybil", "revenue-ops" ], "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.05" }, "protocols": [ { "x402": {} } ] }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "resourceUrl": { "type": "string", "format": "uri" }, "payTo": { "type": "string", "description": "Optional expected Base/EVM recipient address." }, "ownerWallets": { "type": "array", "maxItems": 50, "items": { "type": "string" }, "description": "Known operator wallets to exclude from external-demand candidates." }, "payments": { "type": "array", "minItems": 1, "maxItems": 500, "items": { "type": "object", "properties": { "payer": { "type": "string" }, "payTo": { "type": "string" }, "txHash": { "type": "string" }, "amountUnits": { "type": "string" }, "occurredAt": { "type": "string", "format": "date-time" } }, "required": [ "payer" ] } } }, "required": [ "ownerWallets", "payments" ] }, "example": { "resourceUrl": "https://hermesplant.com/api/agent-services/action-safety/quick", "ownerWallets": [ "0x1111111111111111111111111111111111111111" ], "payments": [ { "payer": "0x2222222222222222222222222222222222222222", "txHash": "0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "occurredAt": "2026-07-16T12:00:00Z" } ] } } } }, "responses": { "200": { "description": "x402 Demand Provenance Check result", "content": { "application/json": { "schema": { "type": "object" }, "example": { "status": "analyzed", "service": "x402-demand-provenance", "signal": "credible_candidate_pattern", "confidence": "moderate", "scope": { "recordSource": "caller_supplied" }, "metrics": { "analyzedPayments": 2, "ownerFundedCalls": 0, "uniqueCandidateExternalPayers": 2, "topPayerShare": 0.5 }, "limitations": [ "Caller-supplied records are not independently verified onchain." ] } } } }, "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/destructguard/score": { "post": { "summary": "DestructGuard Command Score", "description": "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.", "operationId": "destructguard_command_score", "tags": [ "agent-safety", "destructive-actions", "ai-agents", "x402", "destructguard" ], "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.10" }, "protocols": [ { "x402": {} } ] }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "command": { "type": "string", "description": "Shell command or agent action to score" }, "repo": { "type": "string" }, "cwd": { "type": "string" }, "actor": { "type": "string" }, "intent": { "type": "string" }, "diffStat": { "type": "string" } }, "required": [ "command" ] }, "example": { "command": "rm -rf /", "repo": "github.com/acme/app", "cwd": "/workspace/app", "actor": "codex", "intent": "cleanup generated files", "diffStat": "3 files changed, 18 insertions(+), 44 deletions(-)" } } } }, "responses": { "200": { "description": "DestructGuard Command Score result", "content": { "application/json": { "schema": { "type": "object" }, "example": { "status": "scored", "service": "destructguard-command-score", "requestId": "dg_", "risk": "critical", "requiresApproval": true, "recommendedAction": "block_until_explicit_human_or_policy_approval" } } } }, "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/reviewqueue/submit": { "post": { "summary": "ReviewQueue Agent Submit", "description": "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.", "operationId": "reviewqueue_agent_submit", "tags": [ "agent-safety", "approval-workflows", "ai-agents", "x402", "reviewqueue" ], "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.25" }, "protocols": [ { "x402": {} } ] }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "command": { "type": "string", "description": "Shell command or agent action being requested" }, "repo": { "type": "string" }, "branch": { "type": "string" }, "actor": { "type": "string" }, "reason": { "type": "string" }, "diffStat": { "type": "string" } }, "required": [ "command" ] }, "example": { "command": "git push --force origin main", "repo": "github.com/acme/app", "branch": "main", "actor": "codex", "reason": "release automation requested deploy", "diffStat": "12 files changed, 240 insertions(+), 17 deletions(-)" } } } }, "responses": { "200": { "description": "ReviewQueue Agent Submit result", "content": { "application/json": { "schema": { "type": "object" }, "example": { "status": "review_queued", "service": "reviewqueue-agent-submit", "requestId": "rq_", "risk": "critical", "requiresHuman": true, "recommendedAction": "pause_agent_and_request_human_approval" } } } }, "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/payment-policy/decide": { "post": { "summary": "Payment Policy Decision API", "description": "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.", "operationId": "payment_policy_decide", "tags": [ "x402", "payment-policy", "ai-agents", "agent-commerce", "agent-security" ], "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.05" }, "protocols": [ { "x402": {} } ] }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "resourceUrl": { "type": "string", "description": "Absolute resource URL from the x402 challenge or Bazaar listing." }, "method": { "type": "string", "description": "HTTP method the agent intends to call." }, "scheme": { "type": "string", "description": "x402 payment scheme; exact is expected for autonomous spending." }, "network": { "type": "string", "description": "Payment network, e.g. eip155:8453 for Base." }, "asset": { "type": "string", "description": "Payment asset address or identifier." }, "amountUnits": { "type": "string", "description": "Raw x402 amount units; USDC assets are treated as 6-decimal." }, "amountUsd": { "type": "number", "description": "Optional explicit USD amount when the raw amount cannot be converted." }, "payTo": { "type": "string", "description": "Payment recipient from the challenge." }, "facilitatorUrl": { "type": "string", "description": "Facilitator URL used to settle the payment." }, "maxTimeoutSeconds": { "type": "number", "description": "Challenge timeout window." }, "paymentIdentifier": { "type": "string", "description": "Optional idempotency/payment identifier the buyer will persist." }, "paymentPayloadResource": { "type": "string", "description": "Optional resource URL from a signed payment payload; when present it must match resourceUrl." }, "metadata": { "type": "object", "description": "Optional caller metadata scanned for sensitive values before logging or payment." }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Bazaar or service tags used for sensitive-category detection." }, "buyerPolicy": { "type": "object", "description": "Buyer guardrails: maxUsdPerCall, hardMaxUsdPerCall, expectedUsdPerCall, maxPriceMultiple, allowedNetworks, allowedPayTo, allowedHosts, blockedHosts, allowedFacilitators, requireExactScheme, requireHttps, requirePaymentIdentifier, requireResourceBinding, reviewPiiMetadata, maxTimeoutSeconds." }, "serviceRisk": { "type": "object", "description": "Optional upstream service risk result, e.g. from the MCP Server Risk Analyzer." } }, "required": [ "resourceUrl" ] }, "example": { "resourceUrl": "https://api.exa.ai/search", "method": "POST", "scheme": "exact", "network": "eip155:8453", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "amountUnits": "7000", "payTo": "0x6d6E695b09861467c7d462f5AAF31cF3540B9192", "facilitatorUrl": "https://api.cdp.coinbase.com/platform/v2/x402", "maxTimeoutSeconds": 60, "tags": [ "search", "research", "x402" ], "buyerPolicy": { "maxUsdPerCall": 0.25, "allowedNetworks": [ "eip155:8453" ], "requireExactScheme": true, "requirePaymentIdentifier": false } } } } }, "responses": { "200": { "description": "Payment Policy Decision API result", "content": { "application/json": { "schema": { "type": "object" }, "example": { "status": "decided", "service": "payment-policy", "requestId": "paypol_", "policyVersion": "payment-policy-v1", "decision": "allow", "allowed": true, "riskScore": 3, "riskLevel": "low", "amountUsd": 0.007, "resource": { "url": "https://api.exa.ai/search", "host": "api.exa.ai", "method": "POST" }, "payment": { "scheme": "exact", "network": "eip155:8453", "payTo": "0x6d6E695b09861467c7d462f5AAF31cF3540B9192", "amountUnits": "7000" }, "reasonCodes": [ "service.tags-sensitive" ], "replay": { "paymentIdentifier": "agent-run-2026-06-23-001", "idempotencyReady": true }, "binding": { "paymentPayloadResource": null, "resourceMatchesPaymentPayload": null }, "privacy": { "safeForLog": true, "redactedResourceUrl": "https://api.exa.ai/search", "sensitiveFields": [] }, "recommendedAction": "sign_and_retry_payment" } } } }, "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/evidence/verify": { "post": { "summary": "Evidence Verification API", "description": "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.", "operationId": "evidence_verify", "tags": [ "x402", "evidence", "ai-agents", "verification", "agent-commerce", "audit" ], "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.05" }, "protocols": [ { "x402": {} } ] }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "subject": { "type": "object", "description": "Optional run subject: kind, serviceId, endpoint, method, resourceUrl, runId." }, "artifacts": { "type": "array", "description": "Evidence artifacts (shared Hermes contract): x402_challenge, x402_receipt, payment_policy_decision, service_response, agent_run_log, human_approval, and other typed artifacts.", "items": { "type": "object" } }, "policy": { "type": "object", "description": "Verification policy: expected serviceId/endpoint/method/network/payTo/priceCents, allowedSources, minArtifacts, maxArtifactAgeSeconds, and require* flags per artifact type." } }, "required": [ "artifacts" ] }, "example": { "subject": { "kind": "agent_service_call", "serviceId": "payment-policy-decide", "method": "POST", "runId": "run-42" }, "artifacts": [ { "type": "x402_challenge", "source": "https://hermesplant.com/.well-known/x402", "serviceId": "payment-policy-decide", "endpoint": "/api/agent-services/payment-policy/decide", "method": "POST", "network": "eip155:8453", "priceCents": 5, "hash": { "algorithm": "sha256", "value": "" } } ], "policy": { "expectedServiceId": "payment-policy-decide", "expectedNetwork": "eip155:8453", "expectedPriceCents": 5, "requireX402Challenge": true, "requireArtifactHashes": true } } } } }, "responses": { "200": { "description": "Evidence Verification API result", "content": { "application/json": { "schema": { "type": "object" }, "example": { "status": "verified", "service": "evidence-verify", "requestId": "ev_", "decision": "verified", "confidence": 0.94, "verified": true, "artifactSummary": { "total": 3, "hashed": 3, "synthetic": 0 }, "missingArtifacts": [], "reasonCodes": [ "evidence.verified" ], "recommendedAction": "persist_evidence_and_use_result" } } } }, "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/assurance/attest": { "post": { "summary": "Assurance Attest", "description": "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.", "operationId": "assurance_attest", "tags": [ "assurance", "signed-receipts", "ai-agents", "x402", "audit-trail", "agent-commerce", "compliance" ], "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.05" }, "protocols": [ { "x402": {} } ] }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "protocol": { "type": "string", "description": "\"x402\" or \"mcp\"." }, "subject": { "type": "object", "description": "Who acted: runId (required), agentId, purpose." }, "intent": { "type": "object", "description": "x402: resourceUrl+method (+scheme/network/asset/amountUnits/payTo). mcp: serverId+toolName (+toolArguments or toolArgumentsHash)." }, "policy": { "type": "object", "description": "Optional buyer policy (policyId+version, caps, allow-lists). Omit for a binding-only attestation under the permissive policy." }, "outcome": { "type": "object", "description": "Optional settlement outcome: outcome fulfilled|failed|rejected, settlementId, responseStatus, evidenceHashes[]." } }, "required": [ "protocol", "subject", "intent" ] }, "example": { "protocol": "x402", "subject": { "runId": "run-42", "purpose": "enrich leads" }, "intent": { "resourceUrl": "https://api.example.com/search", "method": "POST", "network": "eip155:8453", "amountUnits": "7000", "payTo": "0x6d6E695b09861467c7d462f5AAF31cF3540B9192" }, "outcome": { "outcome": "fulfilled", "settlementId": "0xsettle", "responseStatus": 200 } } } } }, "responses": { "200": { "description": "Assurance Attest result", "content": { "application/json": { "schema": { "type": "object" }, "example": { "status": "attested", "service": "assurance", "record": { "attestationId": "att_", "kind": "agent-action-attestation", "protocol": "x402", "bindingHash": "", "verdict": "allow", "outcome": { "outcome": "fulfilled", "settlementId": "0xsettle" }, "attestedAt": "2026-07-12T00:00:00.000Z" }, "integrity": { "canonicalization": "hermes-stable-json-v1", "recordHash": "", "signatureAlgorithm": "HMAC-SHA-256", "signature": "", "keyId": "assurance-primary" }, "verify": { "url": "https://hermesplant.com/api/agent-services/assurance/verify", "method": "POST" } } } } }, "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/mcp-risk/score": { "post": { "summary": "MCP Server Risk Analyzer", "description": "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).", "operationId": "mcp_risk_score", "tags": [ "mcp", "agent-security", "ai-agents", "x402", "tool-security", "mcp-risk" ], "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.05" }, "protocols": [ { "x402": {} } ] }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "server": { "type": "string", "description": "MCP server name/URL (optional)" }, "tools": { "type": "array", "description": "The server's tool manifest", "items": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" } }, "permissions": { "type": "array", "items": { "type": "string" } }, "inputSchema": { "type": "object" }, "network": { "type": "boolean" } }, "required": [ "name" ] } }, "authModel": { "type": "string", "description": "e.g. oauth, token, none" }, "priorTools": { "type": "array", "items": { "type": "string" }, "description": "Tool names from a prior manifest, to diff capability growth" } }, "required": [ "tools" ] }, "example": { "server": "github.com/acme/mcp-filesystem", "authModel": "none", "tools": [ { "name": "delete_path", "description": "Recursively delete any path on the filesystem", "scopes": [ "fs:*" ], "inputSchema": { "properties": { "path": { "type": "string" } } } }, { "name": "read_env_and_post", "description": "Read environment secrets and upload to a webhook URL", "network": true } ] } } } }, "responses": { "200": { "description": "MCP Server Risk Analyzer result", "content": { "application/json": { "schema": { "type": "object" }, "example": { "status": "scored", "service": "mcp-risk-score", "requestId": "mcp_", "risk": "critical", "requiresApproval": true, "findingsCount": 5, "byFactor": { "destructive-action": 1, "over-broad-scope": 1, "sensitive-egress": 1, "weak-auth": 1 }, "recommendedAction": "block_install_until_scoped_and_approved" } } } }, "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/walletguard/score": { "post": { "summary": "WalletGuard", "description": "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.", "operationId": "walletguard_score", "tags": [ "wallet-risk-scoring", "wallet-screening", "ai-agents", "x402", "aml", "sanctions", "counterparty-risk", "crypto-compliance", "preflight" ], "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.10" }, "protocols": [ { "x402": {} } ] }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "wallet": { "type": "string", "description": "Wallet address (0x + 32-48 hex chars)" }, "labels": { "type": "array", "items": { "type": "string" }, "description": "Labels like exchange:binance, contract:..., sanctions:..." }, "transfers": { "type": "array", "items": { "type": "object", "properties": { "direction": { "type": "string", "enum": [ "in", "out" ] }, "valueUsd": { "type": "number", "minimum": 0 }, "counterparty": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } } }, "required": [ "direction" ] } }, "exposures": { "type": "array", "items": { "type": "string" }, "description": "Signals e.g. mixer:tornado, sanctions:ofac" }, "sanctionsHits": { "type": "array", "items": { "type": "string" } }, "fundingSources": { "type": "array", "items": { "type": "object", "properties": { "source": { "type": "string" }, "share": { "type": "number" }, "verified": { "type": "boolean" }, "labels": { "type": "array", "items": { "type": "string" } } }, "required": [ "source", "share", "verified" ] } } }, "required": [ "wallet" ] }, "example": { "wallet": "0x9999999999999999999999999999999999999999", "sanctionsHits": [ "OFAC-SDN-9999" ], "exposures": [ "sanctions:ofac", "other" ], "labels": [ "high-risk:ofac-listed" ] } } } }, "responses": { "200": { "description": "WalletGuard result", "content": { "application/json": { "schema": { "type": "object" }, "example": { "status": "scored", "service": "walletguard", "requestId": "wg-5a6c8099", "wallet": "0x9999999999999999999999999999999999999999", "riskScore": 50, "riskLevel": "critical", "findings": [ { "id": "sanctions.hit:0", "rule": "sanctions.hit", "severity": "critical", "why": "Wallet appears on sanctions / OFAC / blacklist", "evidence": "sanctionsHits[0]=OFAC-SDN-9999; exposures[0]=sanctions:ofac; labels[0]=high-risk:ofac-listed", "fix": "Do not send or receive funds; freeze and escalate to compliance." } ], "findingsCount": 1, "fundSourceBreakdown": [], "recommendedAction": "block_and_escalate" } } } }, "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/emailguard/validate": { "post": { "summary": "EmailGuard", "description": "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.", "operationId": "emailguard_validate", "tags": [ "email", "validation", "enrichment", "ai-agents", "x402", "data-quality" ], "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.02" }, "protocols": [ { "x402": {} } ] }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "description": "The email address to validate and score." }, "name": { "type": "string", "description": "Optional contact name associated with the email." }, "domain": { "type": "string", "description": "Optional explicit domain hint (usually derived from email)." }, "mxPresent": { "type": "boolean", "description": "Caller-supplied hint whether the domain has MX records. Never performs DNS itself." } }, "required": [ "email" ] }, "example": { "email": "alice+work@gnail.com", "name": "Alice Example", "mxPresent": true } } } }, "responses": { "200": { "description": "EmailGuard result", "content": { "application/json": { "schema": { "type": "object" }, "example": { "valid": true, "deliverabilityScore": 55, "riskLevel": "medium", "normalized": { "localPart": "alice", "domain": "gnail.com", "canonical": "alice@gnail.com" }, "classification": { "disposable": false, "roleBased": false, "freeProvider": false, "typoSuggestion": "gmail.com" }, "checks": [ { "rule": "rfc5322-syntax", "pass": true, "severity": "info", "why": "Email must contain a valid local part and domain with a dot.", "evidence": "parsed local=alice domain=gnail.com", "fix": null }, { "rule": "typo-suggestion", "pass": false, "severity": "warn", "why": "Domain is close to a popular provider and may be a typo.", "evidence": "input domain=\"gnail.com\" suggestion=\"gmail.com\"", "fix": "Use alice@gmail.com instead." } ] } } } }, "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/portfolioguard/score": { "post": { "summary": "PortfolioGuard", "description": "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.", "operationId": "portfolioguard_score", "tags": [ "portfolio-risk-analysis", "risk", "ai-agents", "x402", "finance", "portfolio", "scoring" ], "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.15" }, "protocols": [ { "x402": {} } ] }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "holdings": { "type": "array", "description": "List of positions with symbol, weight (0-1), optional returns[], sector, assetClass.", "items": { "type": "object", "properties": { "symbol": { "type": "string" }, "weight": { "type": "number" }, "returns": { "type": "array", "items": { "type": "number" } }, "sector": { "type": "string" }, "assetClass": { "type": "string" } }, "required": [ "symbol", "weight" ] } }, "periodReturns": { "type": "array", "description": "Optional time series of portfolio or market period returns (preferred for volatility/sharpe/MDD).", "items": { "type": "number" } }, "riskFreeRate": { "type": "number", "description": "Optional risk-free rate for Sharpe (default 0)." } }, "required": [ "holdings" ] }, "example": { "holdings": [ { "symbol": "AAPL", "weight": 0.25, "sector": "Technology" }, { "symbol": "BND", "weight": 0.35, "sector": "Bonds" }, { "symbol": "GLD", "weight": 0.15, "sector": "Commodity" }, { "symbol": "VTI", "weight": 0.25, "sector": "Equity" } ], "periodReturns": [ 0.01, -0.004, 0.007, 0.002, -0.01 ], "riskFreeRate": 0 } } } }, "responses": { "200": { "description": "PortfolioGuard result", "content": { "application/json": { "schema": { "type": "object" }, "example": { "riskScore": 64, "riskLevel": "medium", "metrics": { "volatility": 0.0071, "sharpe": 0.42, "maxDrawdown": 0.014, "concentrationHHI": 0.2375, "diversificationScore": 76, "effectiveHoldings": 4.21 }, "findings": [ { "rule": "weights-sum-sanity", "severity": "info", "why": "Weights should sum to approximately 1.0.", "evidence": "sum=1", "fix": null }, { "rule": "single-position-concentration", "severity": "info", "why": "No position exceeds 25%.", "evidence": "maxWeight=0.35", "fix": null } ], "breakdown": { "bySector": { "Technology": { "weight": 0.25, "count": 1 }, "Bonds": { "weight": 0.35, "count": 1 } }, "topPositions": [ { "symbol": "BND", "weight": 0.35 }, { "symbol": "AAPL", "weight": 0.25 } ] } } } } }, "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/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", "irr", "ai-agents", "x402", "dcf", "xirr", "npv", "moic", "cash-flow-analysis", "cashflow", "valuation" ], "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", "waterfall", "ai-agents", "x402", "private-equity", "carried-interest", "preferred-return", "lp-gp", "real-estate" ], "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 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.", "operationId": "bond_analyze", "tags": [ "finance", "bond", "ai-agents", "x402", "fixed-income", "yield-to-maturity", "duration", "convexity", "loan", "amortization" ], "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", "options", "ai-agents", "x402", "black-scholes", "greeks", "delta", "gamma", "vega", "theta", "derivatives" ], "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", "dcf", "ai-agents", "x402", "valuation", "irr", "waterfall", "sensitivity", "private-equity", "underwriting" ], "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" } } } }, "/api/agent-services/spend-assurance/run": { "post": { "summary": "Agent Spend Assurance", "description": "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.", "operationId": "spend_assurance", "tags": [ "agent-spend", "x402", "ai-agents", "wallet-screening", "payment-policy", "evidence", "signed-receipt", "preflight" ], "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.25" }, "protocols": [ { "x402": {} } ] }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "runId": { "type": "string", "description": "Optional caller run identifier." }, "wallet": { "type": "object", "description": "WalletGuard context: wallet plus optional labels, sanctionsHits, exposures, transfers, and fundingSources." }, "payment": { "type": "object", "description": "Payment Policy input: resource, x402 challenge fields, buyer policy, and optional replay context." } }, "required": [ "wallet", "payment" ] }, "example": { "runId": "run-42", "wallet": { "wallet": "0x9999999999999999999999999999999999999999", "labels": [ "exchange:verified" ] }, "payment": { "resourceUrl": "https://api.example.com/data", "method": "POST", "scheme": "exact", "network": "eip155:8453", "amountUnits": "100000", "payTo": "0x1111111111111111111111111111111111111111", "buyerPolicy": { "maxUsdPerCall": 1 } } } } } }, "responses": { "200": { "description": "Agent Spend Assurance result", "content": { "application/json": { "schema": { "type": "object" }, "example": { "status": "assessed", "service": "spend-assurance", "decision": "allow", "allowed": true, "wallet": { "riskScore": 0, "riskLevel": "low", "recommendedAction": "proceed_with_standard_controls" }, "payment": { "decision": "allow", "allowed": true, "recommendedAction": "sign_and_retry_payment" }, "evidence": { "decision": "verified", "verified": true }, "recommendedAction": "sign_and_retry_payment", "receipt": { "algorithm": "HMAC-SHA-256", "verifyUrl": "https://hermesplant.com/api/agent-services/assurance/verify" } } } } }, "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/investment-evidence/analyze": { "post": { "summary": "Investment Evidence Bundle", "description": "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.", "operationId": "investment_evidence", "tags": [ "investment-analysis", "cashflow", "ai-agents", "x402", "portfolio-risk", "dcf", "irr", "evidence", "signed-receipt" ], "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.25" }, "protocols": [ { "x402": {} } ] }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "runId": { "type": "string", "description": "Optional caller run or deal identifier." }, "cashflow": { "type": "object", "description": "CashflowLens input: cashflows plus optional discount rate, DCF, NAV, and periods per year." }, "portfolio": { "type": "object", "description": "PortfolioGuard input: holdings plus optional portfolio or holding return series and risk-free rate." } }, "required": [ "cashflow", "portfolio" ] }, "example": { "runId": "deal-42", "cashflow": { "cashflows": [ -1000000, 50000, 60000, 70000, 1200000 ], "discountRate": 0.08 }, "portfolio": { "holdings": [ { "symbol": "VTI", "weight": 0.6 }, { "symbol": "BND", "weight": 0.4 } ], "periodReturns": [ 0.01, -0.004, 0.007 ] } } } } }, "responses": { "200": { "description": "Investment Evidence Bundle result", "content": { "application/json": { "schema": { "type": "object" }, "example": { "status": "analyzed", "service": "investment-evidence", "cashflow": { "service": "cashflowlens", "summary": { "npv": 162512.34, "irrAnnual": 0.1287, "moic": 1.38 } }, "portfolio": { "riskScore": 24, "riskLevel": "low", "metrics": { "concentrationHHI": 0.52, "diversificationScore": 48 } }, "evidence": { "decision": "verified", "verified": true }, "recommendedAction": "persist_signed_analysis", "receipt": { "algorithm": "HMAC-SHA-256", "verifyUrl": "https://hermesplant.com/api/agent-services/assurance/verify" } } } } }, "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/assurance/verify": { "post": { "summary": "Assurance Verify (free)", "description": "Free public verifier for Hermes-signed assurance records: POST {record, integrity} and the server recomputes the canonical hash (hermes-stable-json-v1 + SHA-256) and HMAC-SHA-256 signature, reporting recordHashValid / signatureValid / valid. No key, no wallet, no payment.", "operationId": "assurance_verify", "tags": [ "assurance", "signed-receipts", "free" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "record": { "type": "object", "description": "The attestation/decision/receipt record object" }, "integrity": { "type": "object", "description": "The integrity block returned with the record (recordHash, signature, keyId)" } }, "required": [ "record", "integrity" ] } } } }, "responses": { "200": { "description": "Verification result", "content": { "application/json": { "example": { "status": "verified", "service": "assurance", "valid": true, "recordHashValid": true, "signatureValid": true, "keyId": "assurance-primary" } } } } } } } }, "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." } }, "schemas": { "ProductSummary": { "type": "object", "properties": { "slug": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "priceCents": { "type": "integer" }, "currency": { "type": "string" }, "mode": { "type": "string", "enum": [ "payment", "subscription" ] }, "interval": { "type": [ "string", "null" ] }, "deliveryType": { "type": "string" }, "url": { "type": "string" }, "x402": { "type": "object", "properties": { "available": { "type": "boolean" }, "endpoint": { "type": "string" }, "price": { "type": "string" }, "network": { "type": "string" }, "scheme": { "type": "string" }, "reason": { "type": "string" } } } }, "required": [ "slug", "name", "description", "priceCents", "currency", "mode", "deliveryType", "url" ] }, "ContentPage": { "type": "object", "properties": { "path": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "lastModified": { "type": "string", "format": "date-time" }, "intent": { "type": "string" } }, "required": [ "path", "title", "description", "url" ] }, "LegalUrls": { "type": "object", "properties": { "terms": { "type": "string", "format": "uri" }, "privacy": { "type": "string", "format": "uri" }, "refunds": { "type": "string", "format": "uri" }, "cancellation": { "type": "string", "format": "uri" }, "contact": { "type": "string", "format": "uri" } } }, "ReviewQueueSubmitRequest": { "type": "object", "properties": { "command": { "type": "string", "description": "Shell command or agent action being requested" }, "repo": { "type": "string" }, "branch": { "type": "string" }, "actor": { "type": "string" }, "reason": { "type": "string" }, "diffStat": { "type": "string" } }, "required": [ "command" ] }, "ReviewQueueDecision": { "type": "object", "properties": { "status": { "type": "string", "example": "review_queued" }, "service": { "type": "string", "example": "reviewqueue-agent-submit" }, "requestId": { "type": "string" }, "risk": { "type": "string", "enum": [ "low", "medium", "high", "critical" ] }, "requiresHuman": { "type": "boolean" }, "recommendedAction": { "type": "string" } }, "required": [ "status", "service", "requestId", "risk", "requiresHuman", "recommendedAction" ] }, "DestructGuardScoreRequest": { "type": "object", "properties": { "command": { "type": "string", "description": "Shell command or agent action to score" }, "repo": { "type": "string" }, "cwd": { "type": "string" }, "actor": { "type": "string" }, "intent": { "type": "string" }, "diffStat": { "type": "string" } }, "required": [ "command" ] }, "DestructGuardScore": { "type": "object", "properties": { "status": { "type": "string", "example": "scored" }, "service": { "type": "string", "example": "destructguard-command-score" }, "requestId": { "type": "string" }, "risk": { "type": "string", "enum": [ "low", "medium", "high", "critical" ] }, "requiresApproval": { "type": "boolean" }, "matchedRules": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "risk": { "type": "string" }, "category": { "type": "string" }, "reason": { "type": "string" } } } }, "recommendedAction": { "type": "string" } }, "required": [ "status", "service", "requestId", "risk", "requiresApproval", "recommendedAction" ] } } }, "tags": [ { "name": "Agent Commerce Assurance", "description": "Policy-bound authorization, signed execution receipts, and organization history for exact x402 and MCP actions." } ] }