asyncapi: 3.0.0

info:
  title: Triport — Stellar Horizon SSE
  version: 0.1.0-n4-stellar-02
  description: |
    Read-only Horizon Server-Sent Events surface. Only the measured live
    ledger and transaction collections are exposed, both starting at
    `cursor=now`. This is a live stream, not access beyond retention.

defaultContentType: application/json

servers:
  production:
    host: triport.io
    pathname: /rpc/stellar/horizon
    protocol: https
    description: |
      Production Horizon facade: `https://triport.io/rpc/stellar/horizon`.
      Send the API key in the `x-token` header and `Accept: text/event-stream`;
      streams start at `?cursor=now`.
    security:
      - $ref: '_shared.yaml#/components/securitySchemes/XTokenHeader'
      - $ref: '_shared.yaml#/components/securitySchemes/BearerAuth'
      - $ref: '_shared.yaml#/components/securitySchemes/ApiKeyQuery'

channels:
  ledgers:
    address: /ledgers
    description: New Horizon ledger records after the connection starts.
    messages:
      LedgerEvent: {$ref: '#/components/messages/LedgerEvent'}
  transactions:
    address: /transactions
    description: New Horizon transaction records after the connection starts.
    messages:
      TransactionEvent: {$ref: '#/components/messages/TransactionEvent'}

operations:
  receiveLedgers:
    action: receive
    channel: {$ref: '#/channels/ledgers'}
    summary: Receive new ledgers from cursor=now.
    bindings:
      http:
        method: GET
        query:
          type: object
          required: [cursor]
          properties:
            cursor: {type: string, const: now}
        bindingVersion: 0.3.0
    messages:
      - {$ref: '#/channels/ledgers/messages/LedgerEvent'}
  receiveTransactions:
    action: receive
    channel: {$ref: '#/channels/transactions'}
    summary: Receive new transactions from cursor=now.
    bindings:
      http:
        method: GET
        query:
          type: object
          required: [cursor]
          properties:
            cursor: {type: string, const: now}
        bindingVersion: 0.3.0
    messages:
      - {$ref: '#/channels/transactions/messages/TransactionEvent'}

components:
  schemas:
    HALLinks:
      type: object
      properties:
        self:
          type: object
          properties:
            href: {type: string}
      additionalProperties: true
    Ledger:
      type: object
      required: [_links, id, paging_token, sequence]
      properties:
        _links: {$ref: '#/components/schemas/HALLinks'}
        id: {type: string}
        paging_token: {type: string}
        hash: {type: string}
        sequence: {type: integer}
        closed_at: {type: string, format: date-time}
      additionalProperties: true
    Transaction:
      type: object
      required: [_links, id, paging_token, hash, ledger, successful]
      properties:
        _links: {$ref: '#/components/schemas/HALLinks'}
        id: {type: string}
        paging_token: {type: string}
        hash: {type: string}
        ledger: {type: integer}
        created_at: {type: string, format: date-time}
        successful: {type: boolean}
      additionalProperties: true

  messages:
    LedgerEvent:
      name: stellarLedger
      title: Horizon ledger SSE data frame
      summary: A newly closed ledger encoded as a Horizon HAL resource.
      contentType: application/json
      payload: {$ref: '#/components/schemas/Ledger'}
    TransactionEvent:
      name: stellarTransaction
      title: Horizon transaction SSE data frame
      summary: A newly ingested transaction encoded as a Horizon HAL resource.
      contentType: application/json
      payload: {$ref: '#/components/schemas/Transaction'}