Hermes Plant Assurance API

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: assurance
paths:
  /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
      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_<uuid>
                  kind: agent-action-attestation
                  protocol: x402
                  bindingHash: <sha256>
                  verdict: allow
                  outcome:
                    outcome: fulfilled
                    settlementId: 0xsettle
                  attestedAt: '2026-07-12T00:00:00.000Z'
                integrity:
                  canonicalization: hermes-stable-json-v1
                  recordHash: <sha256>
                  signatureAlgorithm: HMAC-SHA-256
                  signature: <hmac>
                  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/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
      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.
externalDocs:
  description: API documentation, error contract, pricing, and changelog
  url: https://hermesplant.com/docs/api