Hermes Plant Agent Commerce 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: Agent Commerce Assurance
  description: Policy-bound authorization, signed execution receipts, and organization history for exact x402 and MCP actions.
paths:
  /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
      operationId: postApiAssuranceDecisions
      x-operation-id-source: derived
  /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
      operationId: postApiAssuranceReceipts
      x-operation-id-source: derived
  /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
      operationId: getApiAssuranceHistory
      x-operation-id-source: derived
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