openapi: 3.0.0
info:
  title: Dark Matter Protocol API
  description: |
    Dark Matter Protocol API — game state, wallet operations, and monetization endpoints.
    
    All game APIs are serverless functions under `/api/*` on the app origin. Auth for
    money-touching calls is the stateless wallet signature described in the Crash Money Model.
  version: 1.0.0
  contact:
    name: Dark Matter Protocol
    url: https://darkmatter.rdytobash.tech
servers:
  - url: https://darkmatter.rdytobash.tech
    description: Production
tags:
  - name: crash
    description: Crash game endpoints
  - name: entropy
    description: Entropy dice games (Mines, Limbo, Plinko, Keno)
  - name: lootbox
    description: Lootbox endpoints
  - name: wallet
    description: Wallet bridge for vfair platform
  - name: ad-rental
    description: Ad slot rental endpoints
paths:
  /api/crash:
    get:
      tags: [crash]
      summary: Get crash game state
      parameters:
        - name: wallet
          in: query
          required: true
          schema:
            type: string
        - name: authSig
          in: query
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Game state
          content:
            application/json:
              schema:
                type: object
                properties:
                  roundId:
                    type: integer
                  phase:
                    type: string
                    enum: [betting, flight, results]
                  msLeft:
                    type: integer
                  multiplier:
                    type: number
                  crashPoint:
                    type: number
                    nullable: true
                  edgeBps:
                    type: integer
                  history:
                    type: array
                    items:
                      type: object
                      properties:
                        roundId:
                          type: integer
                        crash:
                          type: number
                  recentWins:
                    type: array
                    items:
                      type: object
                      properties:
                        wallet:
                          type: string
                        token:
                          type: string
                        amount:
                          type: string
                        mult:
                          type: number
                        payout:
                          type: string
                  me:
                    type: object
                    properties:
                      chips:
                        type: object
                        properties:
                          ETH:
                            type: string
                          USDG:
                            type: string
                      openBet:
                        type: object
                        nullable: true
                      nonce:
                        type: integer
                  config:
                    type: object
                    properties:
                      bounds:
                        type: object
                        properties:
                          ETH:
                            type: object
                            properties:
                              min:
                                type: string
                              max:
                                type: string
                          USDG:
                            type: object
                            properties:
                              min:
                                type: string
                              max:
                                type: string
                      depositFeeBps:
                        type: integer
  /api/crash/verify-seeds:
    get:
      tags: [crash]
      summary: Verify crash seeds
      responses:
        '200':
          description: Seed verification data
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                  rounds:
                    type: array
                    items:
                      type: object
                      properties:
                        roundId:
                          type: integer
                        seedHash:
                          type: string
                        seed:
                          type: string
                        pepper:
                          type: string
                        crash:
                          type: number
  /api/entropy:
    get:
      tags: [entropy]
      summary: Get entropy games config
      responses:
        '200':
          description: Games config
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                  games:
                    type: array
                    items:
                      type: string
                  bounds:
                    type: object
                    properties:
                      ETH:
                        type: object
                        properties:
                          min:
                            type: string
                          max:
                            type: string
                      USDG:
                        type: object
                        properties:
                          min:
                            type: string
                          max:
                            type: string
                  plinkoTables:
                    type: object
                    properties:
                      low:
                        type: array
                        items:
                          type: number
                      medium:
                        type: array
                        items:
                          type: number
                      high:
                        type: array
                        items:
                          type: number
  /api/lootbox:
    get:
      tags: [lootbox]
      summary: Get lootbox config
      responses:
        '200':
          description: Lootbox config
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                  price:
                    type: string
                  pool:
                    type: string
                  prizes:
                    type: array
                    items:
                      type: object
                      properties:
                        bps:
                          type: integer
                        chance:
                          type: number
                        prize:
                          type: string
                        label:
                          type: string
  /api/wallet/balance:
    get:
      tags: [wallet]
      summary: Get wallet balance
      parameters:
        - name: playerId
          in: query
          required: true
          schema:
            type: string
        - name: currency
          in: query
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Wallet balance
          content:
            application/json:
              schema:
                type: object
                properties:
                  balance:
                    type: number
  /api/wallet/transaction:
    post:
      tags: [wallet]
      summary: Create wallet transaction
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                playerId:
                  type: string
                currency:
                  type: string
                amount:
                  type: number
                partnerTransactionId:
                  type: string
      responses:
        '200':
          description: Transaction result
          content:
            application/json:
              schema:
                type: object
                properties:
                  partnerTransactionId:
                    type: string
                  balance:
                    type: number
                  balanceBefore:
                    type: number
  /api/ad-rental:
    get:
      tags: [ad-rental]
      summary: Get ad rental availability
      responses:
        '200':
          description: Ad rental availability
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                  activeRental:
                    type: object
                    nullable: true
                  availableSlots:
                    type: array
                    items:
                      type: object
                      properties:
                        date:
                          type: string
                        available:
                          type: boolean
                  tiers:
                    type: array
                    items:
                      type: object
                      properties:
                        hours:
                          type: integer
                        days:
                          type: integer
                        label:
                          type: string
                        eth:
                          type: string
                  protocolWallet:
                    type: string