asyncapi: 3.1.0

info:
  title: TokenTip Events API
  version: 0.1.0
  description: |
    The event-driven half of the TokenTip API — the tip lifecycle, key changes,
    and (for operators) solvency and abuse signals, as they happen.

    **Two scopes, one contract.** A `tt_` API token is either *creator*-scoped
    (your own account) or *operator*-scoped (system-wide). The token's scope
    decides which channel it may open and which events it receives.

    **Two delivery modes, identical payloads.** Subscribe however suits you:
      - **Webhooks** — TokenTip signs each event (HMAC-SHA256) and POSTs it to a
        URL you register. Verify the signature; the scheme mirrors the one
        TokenTip uses on inbound Stripe webhooks.
      - **SSE stream** — open an authenticated `text/event-stream` and receive
        the same envelopes live.

    Every event shares an `EventEnvelope` (`id`, `type`, `created`, `scope`,
    `data`). Switch on `type`; the `data` shape is fixed per event. The `id` is
    an idempotency key — TokenTip may redeliver, so consumers should dedupe.

    This is the AsyncAPI (event) surface; the synchronous request/response
    surface is described separately in `openapi.yaml`. The two share the schemas
    in `components/schemas.yaml`.
  contact:
    name: TokenTip
    url: https://tokentip.to/
    email: dj@codetestcode.io
  license:
    name: Proprietary — see Terms of Service
    url: https://tokentip.to/terms
  externalDocs:
    description: TokenTip
    url: https://tokentip.to/

defaultContentType: application/json

servers:
  production:
    host: tokentip.to
    protocol: https
    description: >-
      TokenTip production. Events reach you as signed webhooks (HTTPS POST to a
      URL you register) or over an authenticated SSE stream.
    security:
      - $ref: './components/security.yaml#/bearerToken'

channels:
  creatorEvents:
    address: /v1/events
    title: Creator account events
    description: >-
      Your own account's lifecycle. Open the SSE stream at this address with a
      creator-scoped token, or receive the same messages via registered
      webhooks.
    messages:
      tipCreated: { $ref: './components/messages.yaml#/TipCreated' }
      tipHeld: { $ref: './components/messages.yaml#/TipHeld' }
      tipSettled: { $ref: './components/messages.yaml#/TipSettled' }
      tipRefunded: { $ref: './components/messages.yaml#/TipRefunded' }
      tipDisputed: { $ref: './components/messages.yaml#/TipDisputed' }
      keyRotated: { $ref: './components/messages.yaml#/KeyRotated' }

  operatorEvents:
    address: /v1/operator/events
    title: Operator (system-wide) events
    description: >-
      Every creator's lifecycle events plus operator-only solvency and abuse
      signals. Requires an operator-scoped token.
    messages:
      tipCreated: { $ref: './components/messages.yaml#/TipCreated' }
      tipHeld: { $ref: './components/messages.yaml#/TipHeld' }
      tipSettled: { $ref: './components/messages.yaml#/TipSettled' }
      tipRefunded: { $ref: './components/messages.yaml#/TipRefunded' }
      tipDisputed: { $ref: './components/messages.yaml#/TipDisputed' }
      keyRotated: { $ref: './components/messages.yaml#/KeyRotated' }
      solvencyWarning: { $ref: './components/messages.yaml#/SolvencyWarning' }
      settlementBlocked: { $ref: './components/messages.yaml#/SettlementBlocked' }
      tipVelocityBlocked: { $ref: './components/messages.yaml#/TipVelocityBlocked' }

operations:
  publishCreatorEvents:
    action: send
    channel: { $ref: '#/channels/creatorEvents' }
    title: Creator event feed
    summary: TokenTip emits your account's lifecycle events to your stream or webhooks.
    description: >-
      From your perspective these are `receive`d. Requires a creator-scoped
      token; you will only ever see events for your own account.
    security:
      - $ref: './components/security.yaml#/bearerToken'
    bindings:
      http:
        method: POST
    messages:
      - $ref: '#/channels/creatorEvents/messages/tipCreated'
      - $ref: '#/channels/creatorEvents/messages/tipHeld'
      - $ref: '#/channels/creatorEvents/messages/tipSettled'
      - $ref: '#/channels/creatorEvents/messages/tipRefunded'
      - $ref: '#/channels/creatorEvents/messages/tipDisputed'
      - $ref: '#/channels/creatorEvents/messages/keyRotated'

  publishOperatorEvents:
    action: send
    channel: { $ref: '#/channels/operatorEvents' }
    title: Operator event feed
    summary: >-
      TokenTip emits system-wide lifecycle events plus solvency and abuse
      signals to an operator subscriber.
    security:
      - $ref: './components/security.yaml#/bearerToken'
    bindings:
      http:
        method: POST
    messages:
      - $ref: '#/channels/operatorEvents/messages/tipSettled'
      - $ref: '#/channels/operatorEvents/messages/tipDisputed'
      - $ref: '#/channels/operatorEvents/messages/keyRotated'
      - $ref: '#/channels/operatorEvents/messages/solvencyWarning'
      - $ref: '#/channels/operatorEvents/messages/settlementBlocked'
      - $ref: '#/channels/operatorEvents/messages/tipVelocityBlocked'
