openapi: 3.0.3
info:
  title: Gains Network Backend API
  version: 1.0.0
  description: OpenAPI reference for Gains Network backend-global and public chain-specific trading backend endpoints.
servers:
- url: https://backend-global.gains.trade
  description: Backend Global API
- url: https://backend-arbitrum.gains.trade
  description: Arbitrum trading backend
- url: https://backend-base.gains.trade
  description: Base trading backend
- url: https://backend-polygon.gains.trade
  description: Polygon trading backend
- url: https://backend-sepolia.gains.trade
  description: Arbitrum Sepolia trading backend
- url: http://localhost:3002
  description: Local backend-global development server
tags:
- name: Health
- name: Stats
- name: APR
- name: Trading History
- name: Personal Trading History
- name: Leaderboard
- name: Holding Rates
- name: Contests
- name: Dapp
- name: Wallet
- name: Circle
- name: Solana
- name: Transak
- name: Bridge
- name: Campaigns
- name: VIP
- name: Notifications
- name: Referrals
- name: Trading Backend
- name: Legacy Contests
- name: Rewards
paths:
  /health:
    get:
      operationId: get_health
      summary: Health Check
      description: Check backend service health.
      tags:
      - Health
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
  /api/stats:
    get:
      operationId: get_stats
      summary: Get Chain Stats
      description: Returns protocol and trading statistics for a chain.
      tags:
      - Stats
      parameters:
      - name: chainId
        in: query
        required: true
        schema:
          type: integer
          example: 42161
        description: 'Blockchain chain ID. Common values: 42161 Arbitrum, 8453 Base, 137 Polygon.'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChainStatsResponse'
        '503':
          description: Service not available
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/apr:
    get:
      operationId: get_apr
      summary: Get APR Info
      description: Returns APR and TVL data for staking, vault, burn, and collateral rewards.
      tags:
      - APR
      parameters:
      - name: chainId
        in: query
        required: true
        schema:
          type: integer
          example: 42161
        description: 'Blockchain chain ID. Common values: 42161 Arbitrum, 8453 Base, 137 Polygon.'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '503':
          description: Service not available
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/total-supply:
    get:
      operationId: get_total-supply
      summary: Get GNS Total Supply
      description: Returns the latest GNS total supply from cached stats.
      tags:
      - Stats
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  totalSupply:
                    type: number
                additionalProperties: true
  /api/trading-history/{window}:
    get:
      operationId: get_trading-history
      summary: Get Trading History Window
      description: Returns all trades for a recent time window.
      tags:
      - Trading History
      parameters:
      - name: window
        in: path
        required: true
        schema:
          type: string
          example: 24h
        description: 'Time window: 24h, 48h, or 72h.'
      - name: chainId
        in: query
        required: true
        schema:
          type: integer
          example: 42161
        description: 'Blockchain chain ID. Common values: 42161 Arbitrum, 8453 Base, 137 Polygon.'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  additionalProperties: true
        '400':
          description: Invalid window
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/trading-history/{window}/stats:
    get:
      operationId: get_trading-history-stats
      summary: Get Trading History Stats
      description: Returns precomputed trading stats for a recent time window.
      tags:
      - Trading History
      parameters:
      - name: window
        in: path
        required: true
        schema:
          type: string
          example: 24h
        description: 'Supported values: 24h, 48h, 72h.'
      - name: chainId
        in: query
        required: true
        schema:
          type: integer
          example: 42161
        description: 'Blockchain chain ID. Common values: 42161 Arbitrum, 8453 Base, 137 Polygon.'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TradingHistoryStats'
        '400':
          description: Invalid window
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/personal-trading-history/{address}/stats:
    get:
      operationId: get_personal-trading-stats
      summary: Get Wallet Trading Stats
      description: Returns all-time and 30-day trading statistics for a wallet.
      tags:
      - Personal Trading History
      parameters:
      - name: address
        in: path
        required: true
        schema:
          type: string
          example: '0x0000000000000000000000000000000000000000'
        description: Trader wallet address.
      - name: chainId
        in: query
        required: true
        schema:
          type: integer
          example: 42161
        description: 'Blockchain chain ID. Common values: 42161 Arbitrum, 8453 Base, 137 Polygon.'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PersonalTradingStats'
        '400':
          description: Invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/personal-trading-history/stats:
    post:
      operationId: post_batch-personal-trading-stats
      summary: Get Batch Wallet Trading Stats
      description: Returns trading statistics for multiple wallet addresses.
      tags:
      - Personal Trading History
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - addresses
              - chainId
              properties:
                addresses:
                  type: array
                  items:
                    type: string
                chainId:
                  type: integer
                  example: 42161
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                additionalProperties:
                  $ref: '#/components/schemas/PersonalTradingStats'
        '400':
          description: Invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/personal-trading-history/{address}:
    get:
      operationId: get_personal-trading-history
      summary: Get Wallet Trading History
      description: Returns paginated trading history for one wallet.
      tags:
      - Personal Trading History
      parameters:
      - name: address
        in: path
        required: true
        schema:
          type: string
        description: Trader wallet address.
      - name: chainId
        in: query
        required: true
        schema:
          type: integer
          example: 42161
        description: 'Blockchain chain ID. Common values: 42161 Arbitrum, 8453 Base, 137 Polygon.'
      - name: cursor
        in: query
        required: false
        schema:
          type: integer
        description: Pagination cursor.
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          example: 50
        description: Items to return.
      - name: startDate
        in: query
        required: false
        schema:
          type: string
        description: Optional ISO start date.
      - name: endDate
        in: query
        required: false
        schema:
          type: string
        description: Optional ISO end date.
      - name: pair
        in: query
        required: false
        schema:
          type: string
        description: Optional pair filter.
      - name: action
        in: query
        required: false
        schema:
          type: string
        description: Optional action filter.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedPersonalHistory'
        '400':
          description: Invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/personal-trading-history/batch:
    post:
      operationId: post_batch-personal-trading-history
      summary: Get Batch Wallet Trading History
      description: Returns paginated trading history for multiple wallets.
      tags:
      - Personal Trading History
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - addresses
              - chainId
              properties:
                addresses:
                  type: array
                  items:
                    type: string
                chainId:
                  type: integer
                  example: 42161
                limit:
                  type: integer
                  example: 50
                cursors:
                  type: object
                  additionalProperties:
                    type: integer
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                additionalProperties:
                  $ref: '#/components/schemas/PaginatedPersonalHistory'
        '400':
          description: Invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/leaderboard/{period}:
    get:
      operationId: get_leaderboard
      summary: Get Trader Leaderboard
      description: Returns trader leaderboard for a period or all supported periods.
      tags:
      - Leaderboard
      parameters:
      - name: period
        in: path
        required: true
        schema:
          type: string
          example: '7'
        description: Period in days, or all.
      - name: chainId
        in: query
        required: true
        schema:
          type: integer
          example: 42161
        description: 'Blockchain chain ID. Common values: 42161 Arbitrum, 8453 Base, 137 Polygon.'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                oneOf:
                - type: array
                  items:
                    type: object
                    additionalProperties: true
                - type: object
                  additionalProperties: true
        '503':
          description: Service not available
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/holding-rates/{collateralIndex}/{pairIndex}:
    get:
      operationId: get_holding-rates
      summary: Get Holding Rates
      description: Returns historical borrowing and funding rates for a collateral and pair.
      tags:
      - Holding Rates
      parameters:
      - name: collateralIndex
        in: path
        required: true
        schema:
          type: integer
          example: 1
        description: Collateral index.
      - name: pairIndex
        in: path
        required: true
        schema:
          type: integer
          example: 0
        description: Trading pair index.
      - name: chainId
        in: query
        required: true
        schema:
          type: integer
          example: 42161
        description: 'Blockchain chain ID. Common values: 42161 Arbitrum, 8453 Base, 137 Polygon.'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  holdingRates:
                    type: array
                    items:
                      type: object
                      additionalProperties: true
        '400':
          description: Invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: Service not available
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/contests:
    get:
      operationId: get_contests
      summary: List Contests
      description: Lists trading contests.
      tags:
      - Contests
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: Service initializing
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/contests/{id}:
    get:
      operationId: get_contest-details
      summary: Get Contest Details
      description: Returns details, rewards, and aggregate stats for a contest.
      tags:
      - Contests
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
        description: Contest ID.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: Service initializing
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/contests/{id}/leaderboard:
    get:
      operationId: get_contest-leaderboard
      summary: Get Contest Leaderboard
      description: Returns a contest leaderboard sorted by PnL or volume.
      tags:
      - Contests
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
        description: Contest ID.
      - name: sortBy
        in: query
        required: false
        schema:
          type: string
          example: pnl
        description: 'Sort field: pnl or volume.'
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          example: 50
        description: Items to return.
      - name: offset
        in: query
        required: false
        schema:
          type: integer
          example: 0
        description: Pagination offset.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: Service initializing
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/contests/{id}/leaderboard/{trader}:
    get:
      operationId: get_contest-trader-stats
      summary: Get Contest Trader Stats
      description: Returns stats, rankings, and estimated rewards for a trader in a contest.
      tags:
      - Contests
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
        description: Contest ID.
      - name: trader
        in: path
        required: true
        schema:
          type: string
        description: Trader wallet address.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: Service initializing
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/dapp/latest:
    get:
      operationId: get_latest-dapp
      summary: Get Latest Dapp Version
      description: Returns latest frontend version metadata for a dapp mode.
      tags:
      - Dapp
      parameters:
      - name: dapp
        in: query
        required: false
        schema:
          type: string
          example: evm
        description: Dapp mode.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/dapp/latest/{mode}:
    get:
      operationId: get_latest-dapp-by-mode
      summary: Get Latest Dapp Version By Mode
      description: Returns latest frontend version metadata for a mode path parameter.
      tags:
      - Dapp
      parameters:
      - name: mode
        in: path
        required: true
        schema:
          type: string
          example: evm
        description: Dapp mode.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/dapp/wallet/associated/{address}:
    get:
      operationId: get_wallet-associations
      summary: Get Wallet Associations
      description: Returns wallets associated with an address.
      tags:
      - Wallet
      parameters:
      - name: address
        in: path
        required: true
        schema:
          type: string
        description: Wallet address.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/dapp/wallet/associate:
    post:
      operationId: post_associate-wallet
      summary: Associate Wallet
      description: Creates a wallet association after signature verification.
      tags:
      - Wallet
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - evmAddress
              - chainId
              - signedMessage
              - expectedPublicKey
              properties:
                evmAddress:
                  type: string
                chainId:
                  type: integer
                signedMessage:
                  type: string
                expectedPublicKey:
                  type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Success'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/dapp/circle/messages/{domainId}/{txHash}:
    get:
      operationId: get_circle-messages
      summary: Get Circle Messages
      description: Returns Circle CCTP messages for a transaction.
      tags:
      - Circle
      parameters:
      - name: domainId
        in: path
        required: true
        schema:
          type: string
        description: Circle source domain ID.
      - name: txHash
        in: path
        required: true
        schema:
          type: string
        description: Source transaction hash.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/dapp/solana/usdc-balance/{address}:
    get:
      operationId: get_solana-usdc-balance
      summary: Get Solana Token Balance
      description: Returns a Solana SPL token balance and token account using backend RPC fallbacks.
      tags:
      - Solana
      parameters:
      - name: address
        in: path
        required: true
        schema:
          type: string
        description: Solana wallet address.
      - name: mint
        in: query
        required: false
        schema:
          type: string
        description: SPL token mint. Defaults to mainnet USDC.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '400':
          description: Invalid address or mint
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '502':
          description: Solana RPC lookup failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/dapp/transak/widget-url:
    post:
      operationId: post_transak-widget-url
      summary: Create Transak Widget URL
      description: Creates a Transak on-ramp widget URL.
      tags:
      - Transak
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                widgetParams:
                  type: object
                  additionalProperties: true
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/dapp/bridge/flows:
    post:
      operationId: post_create-bridge-flow
      summary: Create Bridge Flow
      description: Creates a cross-chain bridge flow record.
      tags:
      - Bridge
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - amount
              - src
              - dst
              properties:
                amount:
                  type: string
                src:
                  type: object
                dst:
                  type: object
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BridgeFlowResponse'
        '201':
          description: Bridge flow created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BridgeFlowResponse'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Flow not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/dapp/bridge/flows/{address}:
    get:
      operationId: get_bridge-flows-by-address
      summary: Get Bridge Flows By Address
      description: Returns bridge flows associated with a wallet address.
      tags:
      - Bridge
      parameters:
      - name: address
        in: path
        required: true
        schema:
          type: string
        description: Wallet address.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BridgeFlowResponse'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Flow not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/dapp/bridge/flows/pending/{address}:
    get:
      operationId: get_pending-bridge-flows
      summary: Get Pending Bridge Flows
      description: Returns non-finalized bridge flows associated with a wallet address.
      tags:
      - Bridge
      parameters:
      - name: address
        in: path
        required: true
        schema:
          type: string
        description: Wallet address.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BridgeFlowResponse'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Flow not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/dapp/bridge/flows/hash/{srcHash}:
    get:
      operationId: get_bridge-flow-by-hash
      summary: Get Bridge Flow By Hash
      description: Returns one bridge flow by source transaction hash.
      tags:
      - Bridge
      parameters:
      - name: srcHash
        in: path
        required: true
        schema:
          type: string
        description: Source transaction hash.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BridgeFlowResponse'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Flow not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/dapp/bridge/flows/{srcHash}:
    put:
      operationId: put_update-bridge-flow
      summary: Update Bridge Flow
      description: Updates fields on a bridge flow record.
      tags:
      - Bridge
      parameters:
      - name: srcHash
        in: path
        required: true
        schema:
          type: string
        description: Source transaction hash.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BridgeFlowResponse'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Flow not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    delete:
      operationId: delete_delete-bridge-flow
      summary: Delete Bridge Flow
      description: Deletes a bridge flow record.
      tags:
      - Bridge
      parameters:
      - name: srcHash
        in: path
        required: true
        schema:
          type: string
        description: Source transaction hash.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BridgeFlowResponse'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Flow not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/dapp/bridge/flows/finalize:
    patch:
      operationId: patch_finalize-bridge-flow
      summary: Finalize Bridge Flow
      description: Marks a bridge flow as finalized.
      tags:
      - Bridge
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - circleMessage
              - dstHash
              properties:
                circleMessage:
                  type: string
                dstHash:
                  type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BridgeFlowResponse'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Flow not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/campaigns/eligibility/{address}:
    get:
      operationId: get_campaign-eligibility
      summary: Check Campaign Eligibility
      description: Checks broad EVM address eligibility across active campaigns.
      tags:
      - Campaigns
      parameters:
      - name: address
        in: path
        required: true
        schema:
          type: string
        description: EVM wallet address.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Campaign not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/campaigns/{campaignId}/eligibility/{address}:
    get:
      operationId: get_campaign-eligibility-by-id
      summary: Check Campaign Eligibility By ID
      description: Checks EVM address eligibility for a specific campaign.
      tags:
      - Campaigns
      parameters:
      - name: campaignId
        in: path
        required: true
        schema:
          type: string
        description: Campaign ID.
      - name: address
        in: path
        required: true
        schema:
          type: string
        description: EVM wallet address.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Campaign not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/campaigns/eligibility/solana/{address}:
    get:
      operationId: get_solana-campaign-eligibility
      summary: Check Solana Campaign Eligibility
      description: Checks broad Solana address eligibility across active campaigns.
      tags:
      - Campaigns
      parameters:
      - name: address
        in: path
        required: true
        schema:
          type: string
        description: Solana wallet address.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Campaign not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/campaigns/{campaignId}/eligibility/solana/{address}:
    get:
      operationId: get_solana-campaign-eligibility-by-id
      summary: Check Solana Campaign Eligibility By ID
      description: Checks Solana address eligibility for a specific campaign.
      tags:
      - Campaigns
      parameters:
      - name: campaignId
        in: path
        required: true
        schema:
          type: string
        description: Campaign ID.
      - name: address
        in: path
        required: true
        schema:
          type: string
        description: Solana wallet address.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Campaign not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/vip/{address}:
    get:
      operationId: get_vip-status
      summary: Get VIP Status
      description: Returns VIP status for a wallet.
      tags:
      - VIP
      parameters:
      - name: address
        in: path
        required: true
        schema:
          type: string
        description: Wallet address.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/vip/{address}/ack:
    post:
      operationId: post_ack-vip-status
      summary: Acknowledge VIP Status
      description: Acknowledges that the wallet has seen the VIP prompt.
      tags:
      - VIP
      parameters:
      - name: address
        in: path
        required: true
        schema:
          type: string
        description: Wallet address.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Success'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/notifications/{address}:
    get:
      operationId: get_notifications
      summary: Get Notifications
      description: Returns active notifications for a wallet.
      tags:
      - Notifications
      parameters:
      - name: address
        in: path
        required: true
        schema:
          type: string
        description: Wallet address.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/notifications/{address}/dismiss:
    post:
      operationId: post_dismiss-notification
      summary: Dismiss Notification
      description: Marks one notification as acknowledged.
      tags:
      - Notifications
      parameters:
      - name: address
        in: path
        required: true
        schema:
          type: string
        description: Wallet address.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - notificationId
              properties:
                notificationId:
                  type: integer
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Success'
        '400':
          description: Invalid notification ID
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/referrals/links/{link}/address:
    get:
      operationId: get_referral-link-address
      summary: Resolve Referral Link
      description: Resolves a referral slug to an address.
      tags:
      - Referrals
      parameters:
      - name: link
        in: path
        required: true
        schema:
          type: string
        description: Referral slug.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/referrals/addresses/{address}/link:
    get:
      operationId: get_referral-address-link
      summary: Resolve Referral Address
      description: Resolves a referral address to a slug.
      tags:
      - Referrals
      parameters:
      - name: address
        in: path
        required: true
        schema:
          type: string
        description: Referrer address.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/referrals/config:
    get:
      operationId: get_referral-config
      summary: Referral Config
      description: Returns the EIP-712 domain values and the standard reward rates. Probe this endpoint to detect whether referrals are enabled on a deployment; any non-200 means the feature is unavailable. Never hardcode `chainId` or `distributor`.
      tags:
      - Referrals
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    $ref: '#/components/schemas/ReferralConfig'
        '503':
          description: Referrals are not configured on this deployment
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/referrals/summary/{address}:
    get:
      operationId: get_referral-summary
      summary: Referral Summary
      description: Dashboard composite for one address; code, referral counts, rewards, effective rate and VIP tier. `vip` is null when no tier snapshot exists.
      tags:
      - Referrals
      parameters:
      - name: address
        in: path
        required: true
        schema:
          type: string
        description: EVM address.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    $ref: '#/components/schemas/ReferralSummary'
        '400':
          description: Invalid address
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/referrals/rewards/{address}:
    get:
      operationId: get_referral-rewards
      summary: Referral Rewards
      description: Earnings totals for one address. Note that `claimableMicroUsdc` is lifetime gross earnings and `unpaidMicroUsdc` includes amounts no published batch carries yet; neither is the claimable amount.
      tags:
      - Referrals
      parameters:
      - name: address
        in: path
        required: true
        schema:
          type: string
        description: EVM address.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    $ref: '#/components/schemas/ReferralRewards'
        '400':
          description: Invalid address
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/referrals/referred/{address}:
    get:
      operationId: get_referral-referred
      summary: Referred Wallets
      description: The referrer of this address, and the addresses referred at level 1 and level 2.
      tags:
      - Referrals
      parameters:
      - name: address
        in: path
        required: true
        schema:
          type: string
        description: EVM address.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: object
                    properties:
                      referrer:
                        type: string
                        nullable: true
                      l1:
                        type: array
                        items:
                          type: string
                      l2:
                        type: array
                        items:
                          type: string
        '400':
          description: Invalid address
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/referrals/referred/{address}/detail:
    get:
      operationId: get_referral-referred-detail
      summary: Referred Wallet Detail
      description: Per-wallet rows for the referred set. `earnedUsd` is what the referrer earned from that wallet, not what the wallet earned.
      tags:
      - Referrals
      parameters:
      - name: address
        in: path
        required: true
        schema:
          type: string
        description: EVM address.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    $ref: '#/components/schemas/ReferredDetail'
        '400':
          description: Invalid address
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/referrals/history/{address}:
    get:
      operationId: get_referral-history
      summary: Referral History
      description: Daily accruals ascending, and payments received descending.
      tags:
      - Referrals
      parameters:
      - name: address
        in: path
        required: true
        schema:
          type: string
        description: EVM address.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    $ref: '#/components/schemas/ReferralHistory'
        '400':
          description: Invalid address
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/referrals/proof/{address}:
    get:
      operationId: get_referral-proof
      summary: Claim Proof
      description: Merkle proof against the batch currently active on the distributor. A 404 means nothing is claimable yet, which is a normal state rather than an error. Pass `cumulativeMicroUsdc` to `claim` unchanged; the contract computes the delta.
      tags:
      - Referrals
      parameters:
      - name: address
        in: path
        required: true
        schema:
          type: string
        description: EVM address.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    $ref: '#/components/schemas/ReferralProof'
        '400':
          description: Invalid address
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Nothing claimable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/referrals/binding/{address}:
    get:
      operationId: get_referral-binding
      summary: Resolve Binding
      description: The referrer this address is bound to, or null when unbound. Bindings are set once and permanent.
      tags:
      - Referrals
      parameters:
      - name: address
        in: path
        required: true
        schema:
          type: string
        description: EVM address.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: string
                    nullable: true
        '400':
          description: Invalid address
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/referrals/code/{code}/address:
    get:
      operationId: get_referral-code-owner
      summary: Resolve Code Owner
      description: The address that owns a referral code, or null when the code is unregistered. Use this to pre-flight a bind.
      tags:
      - Referrals
      parameters:
      - name: code
        in: path
        required: true
        schema:
          type: string
        description: Referral code. Trimmed and lowercased server-side.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: string
                    nullable: true
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/referrals/address/{address}/code:
    get:
      operationId: get_referral-owner-code
      summary: Resolve Address Code
      description: The referral code owned by an address, or null. One code per address.
      tags:
      - Referrals
      parameters:
      - name: address
        in: path
        required: true
        schema:
          type: string
        description: EVM address.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: string
                    nullable: true
        '400':
          description: Invalid address
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/referrals/code:
    post:
      operationId: post_referral-register-code
      summary: Register Code
      description: Registers a referral code from an EIP-712 `RegisterCode` signature. No API key; the signature is the sole authority. The same operation is available over GET with the message base64url-encoded in a `message` query parameter, for clients behind an edge that blocks POST.
      tags:
      - Referrals
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SignedReferralWrite'
      responses:
        '201':
          description: Applied
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: object
                    properties:
                      signer:
                        type: string
        '400':
          description: Malformed message, or signature expired
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Recovered signer is not authorized for the subject
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Origin not allowed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: CodeTaken, OwnerHasCode, CodeReserved or BadNonce
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limited
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: Signed referral writes are disabled
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/referrals/bind:
    post:
      operationId: post_referral-bind-code
      summary: Bind Code
      description: Attaches a referrer to a wallet from an EIP-712 `BindCode` signature. Only accepted while the wallet has never traded on a covered chain; afterwards it returns 409 AlreadyTraded permanently. Also available over GET, as for Register Code.
      tags:
      - Referrals
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SignedReferralWrite'
      responses:
        '201':
          description: Applied
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: object
                    properties:
                      signer:
                        type: string
        '400':
          description: Malformed message, or signature expired
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Recovered signer is not authorized for the subject
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Origin not allowed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: AlreadyTraded, AlreadyBound, CodeUnknown, SelfReferral, Cycle or BadNonce
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limited
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: Signed referral writes are disabled, or trade history unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /trading-variables:
    get:
      operationId: get_core-trading-variables
      summary: Get Trading Variables
      description: Returns core trading variables needed by integrators.
      tags:
      - Trading Backend
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
  /trading-variables/all:
    get:
      operationId: get_core-trading-variables-all
      summary: Get All Trading Variables
      description: Returns all cached trading variables.
      tags:
      - Trading Backend
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
  /trading-variables/{keys}:
    get:
      operationId: get_core-trading-variables-by-keys
      summary: Get Trading Variables By Keys
      description: Returns selected trading variable keys.
      tags:
      - Trading Backend
      parameters:
      - name: keys
        in: path
        required: true
        schema:
          type: string
        description: Comma-separated keys.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
  /trading-variables-keys:
    get:
      operationId: get_core-trading-variable-keys
      summary: Get Trading Variable Keys
      description: Returns available trading variable keys.
      tags:
      - Trading Backend
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
  /open-trades:
    get:
      operationId: get_core-open-trades
      summary: Get Open Trades
      description: Returns all known open trades.
      tags:
      - Trading Backend
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
  /open-trades/{address}:
    get:
      operationId: get_core-open-trades-by-address
      summary: Get Open Trades By Address
      description: Returns known open trades for one address.
      tags:
      - Trading Backend
      parameters:
      - name: address
        in: path
        required: true
        schema:
          type: string
        description: Trader wallet address.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
  /open-trades-info:
    get:
      operationId: get_core-open-trades-info
      summary: Get Open Trades Info
      description: Returns metadata and indexes for known open trades.
      tags:
      - Trading Backend
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
  /pending-events:
    get:
      operationId: get_core-pending-events
      summary: Get Pending Events
      description: Returns pending backend event queue data.
      tags:
      - Trading Backend
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
  /user-trading-variables/{address}:
    get:
      operationId: get_core-user-trading-variables
      summary: Get User Trading Variables
      description: Returns user-specific trading variables, pending market orders, fee tiers, and price impact data.
      tags:
      - Trading Backend
      parameters:
      - name: address
        in: path
        required: true
        schema:
          type: string
        description: Trader wallet address.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
  /contest/leaderboard:
    get:
      operationId: get_legacy-contest-leaderboard
      summary: Get Legacy Contest Leaderboard
      description: Returns legacy contest leaderboard cache.
      tags:
      - Legacy Contests
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
  /contest/pnl:
    get:
      operationId: get_legacy-contest-pnl
      summary: Get Legacy Contest PnL
      description: Returns legacy contest PnL history cache.
      tags:
      - Legacy Contests
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
  /contest/pnl-percent:
    get:
      operationId: get_legacy-contest-pnl-percent
      summary: Get Legacy Contest PnL Percent
      description: Returns legacy contest percentage PnL history cache.
      tags:
      - Legacy Contests
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
  /contest/final-open-pnl:
    get:
      operationId: get_legacy-contest-final-open-pnl
      summary: Get Legacy Final Open PnL
      description: Returns final open PnL snapshots for legacy contests.
      tags:
      - Legacy Contests
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
  /contest:
    get:
      operationId: get_legacy-contest
      summary: Get Legacy Contest
      description: Returns legacy contest metadata.
      tags:
      - Legacy Contests
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
  /contest/rewards:
    get:
      operationId: get_legacy-contest-rewards
      summary: Get Legacy Contest Rewards
      description: Returns legacy contest rewards data.
      tags:
      - Legacy Contests
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
  /contest/results:
    get:
      operationId: get_legacy-contest-results
      summary: Get Legacy Contest Results
      description: Returns legacy contest results data.
      tags:
      - Legacy Contests
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
  /contest/cache-update:
    put:
      operationId: put_legacy-contest-cache-update
      summary: Update Legacy Contest Cache
      description: Updates legacy contest cache data.
      tags:
      - Legacy Contests
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
  /rewards/root/{configId}/{epoch}:
    get:
      operationId: get_rewards-root
      summary: Get Rewards Root
      description: Returns the rewards Merkle root for a config and epoch.
      tags:
      - Rewards
      parameters:
      - name: configId
        in: path
        required: true
        schema:
          type: string
        description: Reward config ID.
      - name: epoch
        in: path
        required: true
        schema:
          type: string
        description: Epoch ID.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
  /rewards/root/all/{configId}/{epoch}:
    get:
      operationId: get_rewards-root-all
      summary: Get All Rewards Roots
      description: Returns all rewards Merkle roots matching a config and epoch.
      tags:
      - Rewards
      parameters:
      - name: configId
        in: path
        required: true
        schema:
          type: string
        description: Reward config ID.
      - name: epoch
        in: path
        required: true
        schema:
          type: string
        description: Epoch ID.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
  /rewards/{configId}/{epoch}/{address}:
    get:
      operationId: get_rewards-by-address
      summary: Get Rewards By Address
      description: Returns rewards for one address.
      tags:
      - Rewards
      parameters:
      - name: configId
        in: path
        required: true
        schema:
          type: string
        description: Reward config ID.
      - name: epoch
        in: path
        required: true
        schema:
          type: string
        description: Epoch ID.
      - name: address
        in: path
        required: true
        schema:
          type: string
        description: Wallet address.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
  /rewards/all/{configId}/{epoch}/{address}:
    get:
      operationId: get_rewards-all-by-address
      summary: Get All Rewards By Address
      description: Returns all rewards for one address.
      tags:
      - Rewards
      parameters:
      - name: configId
        in: path
        required: true
        schema:
          type: string
        description: Reward config ID.
      - name: epoch
        in: path
        required: true
        schema:
          type: string
        description: Epoch ID.
      - name: address
        in: path
        required: true
        schema:
          type: string
        description: Wallet address.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
components:
  schemas:
    Error:
      type: object
      properties:
        error:
          type: string
        message:
          type: string
        success:
          type: boolean
      additionalProperties: true
    Success:
      type: object
      properties:
        success:
          type: boolean
      additionalProperties: true
    PersonalTradingStats:
      type: object
      properties:
        totalVolume:
          type: number
          description: All-time leveraged trading volume in USD.
        totalTrades:
          type: integer
          description: All-time trade count.
        winRate:
          type: number
          description: All-time win rate percentage.
        thirtyDayVolume:
          type: number
          description: Leveraged trading volume over the last 30 days in USD.
        updatedAt:
          type: integer
          description: Last incremental update timestamp in milliseconds.
        cacheInitializedAt:
          type: integer
          description: Cache initialization timestamp in milliseconds.
    PaginatedPersonalHistory:
      type: object
      properties:
        data:
          type: array
          items:
            type: object
            additionalProperties: true
        pagination:
          type: object
          properties:
            hasMore:
              type: boolean
            nextCursor:
              type: integer
              nullable: true
            limit:
              type: integer
    ChainStatsResponse:
      type: object
      properties:
        stats:
          type: array
          items:
            type: object
            additionalProperties: true
    TradingHistoryStats:
      type: object
      properties:
        totalVolume:
          type: number
        totalTrades:
          type: integer
        updatedAt:
          type: integer
      additionalProperties: true
    BridgeFlowResponse:
      type: object
      properties:
        success:
          type: boolean
        data:
          type: object
          additionalProperties: true
    ReferralConfig:
      type: object
      properties:
        chainId:
          type: integer
          description: Hub chain the EIP-712 domain and the claim are bound to.
        distributor:
          type: string
          description: Distributor contract, and the EIP-712 verifyingContract.
        l1RateBps:
          type: integer
          description: Standard level-1 rate in basis points.
        l2RateBps:
          type: integer
          description: Standard level-2 rate in basis points.
    ReferralRewards:
      type: object
      properties:
        account:
          type: string
        lifetimeUsd:
          type: string
          description: Decimal USD. Same quantity as claimableMicroUsdc, different unit.
        l1Usd:
          type: string
          description: Decimal USD.
        l2Usd:
          type: string
          description: Decimal USD.
        cashbackUsd:
          type: string
          description: Decimal USD. Zero while cashback is inactive.
        claimableMicroUsdc:
          type: string
          description: Micro-USDC integer. Lifetime gross earnings, NOT the claimable amount.
        settledMicroUsdc:
          type: string
          description: Micro-USDC integer. Already claimed on-chain, from indexed events.
        unpaidMicroUsdc:
          type: string
          description: Micro-USDC integer. Lifetime minus settled; includes amounts not yet in a published batch.
    ReferralSummary:
      type: object
      properties:
        account:
          type: string
        code:
          type: string
          nullable: true
        referralsCount:
          type: object
          properties:
            l1:
              type: integer
            l2:
              type: integer
        rewards:
          $ref: '#/components/schemas/ReferralRewards'
        effectiveRate:
          type: object
          description: Standard programme rate. Negotiated partner rates are applied to earnings but not reflected here.
          properties:
            l1RateBps:
              type: integer
            l2RateBps:
              type: integer
        vip:
          type: object
          nullable: true
          properties:
            tier:
              type: integer
            cashbackBps:
              type: integer
            stakedGns:
              type: string
            volume30dUsd:
              type: string
            stakeTier:
              type: integer
            volumeTier:
              type: integer
            next:
              type: object
              nullable: true
              properties:
                tier:
                  type: integer
                stakedGns:
                  type: string
                volumeUsd:
                  type: string
    ReferredDetail:
      type: object
      properties:
        referrer:
          type: string
          nullable: true
        wallets:
          type: array
          items:
            type: object
            properties:
              address:
                type: string
              type:
                type: string
                enum:
                - L1
                - L2
              boundAt:
                type: integer
                nullable: true
                description: Unix seconds.
              earnedUsd:
                type: string
                description: Decimal USD earned by the referrer from this wallet.
        totals:
          type: object
          properties:
            count:
              type: integer
            earnedUsd:
              type: string
    ReferralHistory:
      type: object
      properties:
        daily:
          type: array
          items:
            type: object
            properties:
              day:
                type: string
                description: YYYY-MM-DD, UTC.
              accruedUsd:
                type: string
                description: Decimal USD.
        claims:
          type: array
          items:
            type: object
            properties:
              tx:
                type: string
              block:
                type: integer
              amountMicroUsdc:
                type: string
                description: Micro-USDC paid by this transaction.
              cumulativeMicroUsdc:
                type: string
                description: Micro-USDC cumulative total at that claim.
    ReferralProof:
      type: object
      properties:
        day:
          type: string
          description: UTC day label of the active batch.
        cumulativeMicroUsdc:
          type: string
          description: Lifetime cumulative entitlement in the active batch. Pass to claim unchanged.
        proof:
          type: array
          items:
            type: string
          description: Merkle proof, bytes32 hex.
    SignedReferralWrite:
      type: object
      required:
      - message
      - signature
      properties:
        message:
          type: object
          description: The signed struct plus a `kind` discriminator. `kind` is transport metadata and is not part of the EIP-712 struct.
          required:
          - kind
          - code
          - nonce
          - validUntil
          properties:
            kind:
              type: string
              enum:
              - register_code
              - bind_code
            owner:
              type: string
              description: Subject for register_code. Must be the signer.
            referee:
              type: string
              description: Subject for bind_code. Must be the signer.
            code:
              type: string
              description: Must match ^[a-z0-9_]{1,31}$. Normalize before signing; the server rejects rather than normalizing.
            nonce:
              type: integer
              format: int64
              description: Strictly increasing per signer, shared across both kinds. Date.now() in milliseconds works.
            validUntil:
              type: integer
              format: int64
              description: Unix seconds. Must be in the future and at most 900 seconds ahead.
        signature:
          type: string
          description: 65-byte ECDSA signature, 0x-prefixed hex. EIP-1271 is not supported.