OpenAPI

Machine-readable copy of these pages: docs.md · llms.txt.

Ads live on Dev (ADS_BASE = https://dev.riddlewallet.com). Guide and health live on the hub.

Hub HTTP routes

openapi: 3.0.3
info:
  title: Riddle Hub public API
  version: "1.0.0"
  description: Health, suite ads, and hub Guide. SSO is a Wallet query + cookie, not a JSON login.
servers:
  - url: https://riddlewallet.com
    description: Hub
  - url: https://dev.riddlewallet.com
    description: Dev (ads)
paths:
  /api/health:
    get:
      servers: [{ url: https://riddlewallet.com }]
      summary: Hub liveness
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok: { type: boolean, example: true }
                  service: { type: string, example: riddleweb }
                  at: { type: string, format: date-time }
  /api/ads/active:
    get:
      servers: [{ url: https://dev.riddlewallet.com }]
      summary: Live ad creative
      parameters:
        - in: query
          name: slot
          required: false
          schema: { type: string }
          description: Slot id. Omit to list inventory.
      responses:
        "200":
          description: Creative or inventory
        "400":
          description: UNKNOWN_SLOT
  /api/ai/guide:
    post:
      servers: [{ url: https://riddlewallet.com }]
      summary: Hub Guide (Grok)
      description: |
        Server-only XAI_API_KEY. Model grok-4.6 (GUIDE_MODEL).
        503 when the key is missing. Never send seeds. Streams SSE.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [messages]
              properties:
                messages:
                  type: array
                  items:
                    type: object
                    properties:
                      role: { type: string, enum: [user, assistant] }
                      content: { type: string }
      responses:
        "200":
          description: SSE stream (text/event-stream)
        "400":
          description: messages required / invalid JSON
        "429":
          description: Daily IP rate limit
        "503":
          description: XAI_API_KEY missing or GUIDE_DISABLED=1

SSO (not REST)

GET https://wallet.riddlewallet.com?return=&app=&action=connect

Then cookie rdl_sess Domain=.riddlewallet.com and optional postMessage riddle-wallet:connected. See SSO.

Units reminder

Payload amounts: drops / lamports / wei integers. Never float * 1e6.