Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
info:
title: Hermes Plant - Agent Action Safety and Commerce Assurance…
description: 'Deterministic, test-backed controls for AI agents before consequential shell, Git, SQL, infrastructure, deployment, wallet, and x402 payment actions. Use the one-cent Action Safety quick gate for classification; the complete workflow for score, conditional review triage, execution evidence, and a signed receipt; and payment-policy endpoints for spend assurance. Finance and quant utilities remain available as component services. Pay per call over x402 (USDC on Base); no API key required. Pricing: https://hermesplant.com/pricing. Errors: https://hermesplant.com/docs/api/errors. Changelog: https://hermesplant.com/changelog.'
version: 1.0.0
contact:
name: Hermes Plant support
email: contact@hermesplant.com
url: https://hermesplant.com/contact
termsOfService: https://hermesplant.com/legal/terms
license:
name: Proprietary — see Terms of Service
url: https://hermesplant.com/legal/terms
x-pricing-url: https://hermesplant.com/pricing
x-errors-contract-url: https://hermesplant.com/docs/api/errors
x-changelog-url: https://hermesplant.com/changelog
x-changelog-feeds:
rss: https://hermesplant.com/changelog/feed.xml
jsonFeed: https://hermesplant.com/changelog/feed.json
x-x402-manifest-url: https://hermesplant.com/.well-known/x402
x-mcp-server-card-url: https://hermesplant.com/.well-known/mcp/server-card.json
x-llms-txt-url: https://hermesplant.com/llms.txt
x-risk-reversal:
- Refund any settled call whose documented inputs do not reproduce the same output.
- First $1 of calls free for the first 100 verified agents.
x-guidance: Call Hermes Plant before a consequential agent action or x402 payment. Start with POST /api/agent-services/action-safety/quick for a $0.01 deterministic preflight risk classification. Use POST /api/agent-services/action-safety/run when you need the complete $0.25 workflow with conditional review triage, execution evidence, status, and a signed receipt. Use POST /api/agent-services/payment-policy/decide to validate amount, asset, network, recipient, and buyer policy before signing. Use focused component endpoints only when you already own orchestration. Payment is x402 USDC on Base; see https://hermesplant.com/pricing and https://hermesplant.com/docs/api/errors.
x-hermes-guidance:
summary: Call Hermes Plant before a consequential agent action or x402 payment.
workflows:
- name: Agent Action Safety quick gate
start: POST /api/agent-services/action-safety/quick
priceUsd: '0.01'
useWhen: You need a deterministic preflight risk classification before shell, Git, SQL, infrastructure, or deployment work.
- name: Agent Action Safety complete workflow
start: POST /api/agent-services/action-safety/run
priceUsd: '0.25'
useWhen: You need scoring, conditional review triage, execution evidence, status, and a signed receipt.
- name: Agent spend assurance
start: POST /api/agent-services/payment-policy/decide
useWhen: You need to validate a proposed x402 payment against amount, asset, network, recipient, and buyer policy before signing.
selectionRules:
- Use quick for a low-cost preflight; use run when an auditable end-to-end record is required.
- Use focused component endpoints only when the caller already owns workflow orchestration.
- A review recommendation is not a claim that a human approved the action.
payment:
protocol: x402
network: Base
asset: USDC
pricingUrl: https://hermesplant.com/pricing
errorsUrl: https://hermesplant.com/docs/api/errors
proof:
manifest: https://hermesplant.com/.well-known/x402
agentCard: https://hermesplant.com/.well-known/agent.json
changelog: https://hermesplant.com/changelog
servers:
- url: https://hermesplant.com
tags:
- name: X402
paths:
/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
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/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
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_<uuid>
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
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: <challenge-sha256>
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_<uuid>
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
components:
securitySchemes:
oauth2:
type: oauth2
description: Register at POST /api/auth/register, then obtain a token from POST /api/auth/token using client_credentials.
flows:
clientCredentials:
tokenUrl: https://hermesplant.com/api/auth/token
scopes:
catalog:read: Read the product catalog
checkout:create: Start checkout sessions
billing:manage: Open Stripe billing portal for subscribers
assuranceBearer:
type: http
scheme: bearer
description: Organization-scoped Hermes Plant bearer token. A signed-in organization session is also accepted by the application.
externalDocs:
description: API documentation, error contract, pricing, and changelog
url: https://hermesplant.com/docs/api