openapi: 3.2.0
info:
  title: HiveMorph v0.1 Receipt Relay API
  description: 'Polymorphic agent runtime — single shape (Merchant), single supermodel (W2 MERCHANT). Three gates: NEED + YIELD + CLEAN-MONEY.'
  version: 0.1.0
tags:
- name: receipt-relay
paths:
  /v1/receipt-relay/health:
    get:
      tags:
      - receipt-relay
      summary: Receipt Relay discovery — modes, evidence tiers, schema
      operationId: relay_health_v1_receipt_relay_health_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
  /v1/receipt-relay/event:
    post:
      tags:
      - receipt-relay
      summary: Sign a self-attested receipt over an arbitrary external event
      operationId: relay_event_v1_receipt_relay_event_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EventRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/receipt-relay/http:
    post:
      tags:
      - receipt-relay
      summary: SSRF-guarded outbound request, signed as relay_observed (or dry_run)
      operationId: relay_http_v1_receipt_relay_http_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/HttpRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/receipt-relay/chain:
    post:
      tags:
      - receipt-relay
      summary: Record a solana_tx/evm_tx receipt (submitted_unverified; optional read-only…
      operationId: relay_chain_v1_receipt_relay_chain_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChainRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    ChainRequest:
      properties:
        chain:
          type: string
          title: Chain
          description: 'One of: solana, base, ethereum.'
        tx:
          type: string
          maxLength: 256
          minLength: 4
          title: Tx
          description: Transaction signature (Solana) or hash (EVM).
        action:
          type: string
          maxLength: 200
          title: Action
          default: chain_tx
        external_system:
          type: string
          maxLength: 120
          title: External System
          default: chain
        network:
          anyOf:
          - type: string
            maxLength: 64
          - type: 'null'
          title: Network
          description: Optional network label, e.g. 'mainnet-beta' or '8453'.
        verify:
          type: boolean
          title: Verify
          description: If true, attempt a read-only public-RPC existence/status lookup.
          default: false
        payload:
          additionalProperties: true
          type: object
          title: Payload
        actor:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Actor
      type: object
      required:
      - chain
      - tx
      title: ChainRequest
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    EventRequest:
      properties:
        action:
          type: string
          maxLength: 200
          minLength: 1
          title: Action
          description: What happened, e.g. 'invoice.paid' or 'stablecoin_transfer'.
        external_system:
          type: string
          maxLength: 120
          title: External System
          description: Source system, e.g. 'circle', 'stripe', 'my-agent'.
          default: unknown
        payload:
          additionalProperties: true
          type: object
          title: Payload
          description: Arbitrary event payload. Hashed into intent_hash; signed as self-attested.
        request_body:
          anyOf:
          - {}
          - type: 'null'
          title: Request Body
          description: Optional request bytes/object to hash into request_hash.
        response_body:
          anyOf:
          - {}
          - type: 'null'
          title: Response Body
          description: Optional response bytes/object to hash into response_hash.
        evidence:
          items: {}
          type: array
          title: Evidence
          description: Optional supporting artifacts; each is hashed into evidence_hashes.
        actor:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Actor
          description: 'Optional actor/agent identifiers (e.g. {''agent_did'': ''...''}).'
      type: object
      required:
      - action
      title: EventRequest
    HttpRequest:
      properties:
        url:
          type: string
          maxLength: 2048
          title: Url
          description: Absolute http(s) URL. Must resolve to a public address (SSRF-guarded).
        method:
          type: string
          maxLength: 10
          title: Method
          default: GET
        headers:
          additionalProperties:
            type: string
          type: object
          title: Headers
          description: Request headers (do not send secrets you don't want hashed).
        body:
          anyOf:
          - type: string
            maxLength: 32768
          - type: 'null'
          title: Body
          description: Optional request body (string).
        external_system:
          type: string
          maxLength: 120
          title: External System
          default: http
        dry_run:
          type: boolean
          title: Dry Run
          description: If true, sign a prepare-only event WITHOUT making the request.
          default: false
        actor:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Actor
      type: object
      required:
      - url
      title: HttpRequest