openapi: 3.0.3
info:
  title: Monaco Protocol API
  description: REST API for the Monaco Protocol hybrid CLOB exchange.
  version: 1.0.0
servers:
- url: https://develop.apimonaco.xyz
  description: Development server
- url: https://staging.apimonaco.xyz
  description: Staging server (Testnet)
paths:
  /api/v1/accounts/balances:
    get:
      tags:
      - AccountsService
      - Accounts
      summary: Get user balances
      description: |-
        Get user balances.

         Get the current user's token balances with pagination support. Returns
         available, locked, and total balance for each token.
      operationId: get_user_balances
      parameters:
      - name: page
        in: query
        schema:
          type: integer
          format: uint32
          minimum: 1
          maximum: 10000
        description: Page number (1-indexed)
      - name: page_size
        in: query
        schema:
          type: integer
          format: uint32
          minimum: 1
          maximum: 100
          default: 20
        description: Items per page (max 100)
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetBalancesResponse'
        '400':
          description: Invalid request
        '401':
          description: Authentication required
        '500':
          description: Internal server error
      security:
      - bearerAuth: []
  /api/v1/accounts/balances/{asset_id}:
    get:
      tags:
      - AccountsService
      - Accounts
      summary: Get user balance by asset
      description: |-
        Get user balance by asset.

         Get the current user's balance for a specific asset. Returns available,
         locked, and total balance. If no balance exists for a valid asset, returns
         zero balances. If the asset ID is invalid or not found, returns 404.
      operationId: get_user_balance_by_asset
      parameters:
      - name: asset_id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetBalanceByAssetResponse'
        '400':
          description: Invalid request
        '401':
          description: Authentication required
        '404':
          description: Asset not found
        '500':
          description: Internal server error
      security:
      - bearerAuth: []
  /api/v1/accounts/me:
    get:
      tags:
      - AccountsService
      - Accounts
      summary: Get user profile
      description: |-
        Get user profile.

         Get the current user's profile with token balances, recent movements,
         and recent orders. Use `source` to control data source: `hot_storage`
         (fast, real-time), `cold_storage` (historical), or `both` (hybrid).
      operationId: get_user_profile
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetProfileResponse'
        '400':
          description: Invalid request
        '401':
          description: Authentication required
        '404':
          description: User not found
        '500':
          description: Internal server error
      security:
      - bearerAuth: []
  /api/v1/accounts/me/portfolio:
    get:
      tags:
      - AccountsService
      - Accounts
      summary: Get portfolio stats
      description: |-
        Get portfolio stats.

         Get aggregate portfolio statistics for the authenticated user,
         scoped by time period. Includes volume, PnL, fees, equity, and
         win/loss metrics.
      operationId: get_portfolio_stats
      parameters:
      - name: period
        in: query
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetPortfolioStatsResponse'
        '400':
          description: Invalid period parameter
        '401':
          description: Authentication required
        '500':
          description: Internal server error
      security:
      - bearerAuth: []
  /api/v1/accounts/me/portfolio/chart:
    get:
      tags:
      - AccountsService
      - Accounts
      summary: Get portfolio chart time series
      description: |-
        Get portfolio chart time series.

         Get bucketed time series data for portfolio charts. Supports volume
         and PnL metrics with configurable time periods and automatic bucket sizing.
      operationId: get_portfolio_chart
      parameters:
      - name: period
        in: query
        schema:
          type: string
      - name: metric
        in: query
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetPortfolioChartResponse'
        '400':
          description: Invalid period or metric parameter
        '401':
          description: Authentication required
        '500':
          description: Internal server error
      security:
      - bearerAuth: []
  /api/v1/accounts/movements:
    get:
      tags:
      - AccountsService
      - Accounts
      summary: Get user movements
      description: |-
        Get user movements.

         Get the current user's ledger movements (transaction history) with
         pagination and filtering support.
      operationId: get_user_movements
      parameters:
      - name: page
        in: query
        schema:
          type: integer
          format: uint32
          minimum: 1
          maximum: 10000
        description: Page number (1-indexed)
      - name: page_size
        in: query
        schema:
          type: integer
          format: uint32
          minimum: 1
          maximum: 100
          default: 20
        description: Items per page (max 100)
      - name: transaction_type
        in: query
        schema:
          type: string
          enum:
          - DEPOSIT
          - WITHDRAWAL
          - TRADE
          - FEE
          - FUNDING
          - LIQUIDATION
          - INTEREST
          - REWARD
          - CHAIN_SYNC
          minLength: 1
        description: Transaction type
      - name: entry_type
        in: query
        schema:
          type: string
          enum:
          - CREDIT
          - DEBIT
          - LOCK
          - UNLOCK
          - FEE
          minLength: 1
        description: Ledger entry type
      - name: asset_id
        in: query
        schema:
          type: string
          minLength: 1
          format: uuid
        description: Asset identifier (UUID)
      - name: order_by
        in: query
        schema:
          type: string
          default: DESC
          enum:
          - ASC
          - DESC
          minLength: 1
        description: Sort direction for created_at
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetMovementsResponse'
        '400':
          description: Invalid request
        '401':
          description: Authentication required
        '404':
          description: User not found
        '500':
          description: Internal server error
      security:
      - bearerAuth: []
  /api/v1/accounts/sub-accounts:
    get:
      tags:
      - AccountsService
      - Accounts
      summary: List sub-accounts with balances
      description: |-
        List sub-accounts with balances.

         List all sub-accounts with their token balances for a master account.
         Only returns sub-accounts that belong to the same application as the
         requesting user.
      operationId: list_sub_accounts_with_balances
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListSubAccountsResponse'
        '400':
          description: Invalid request
        '401':
          description: Authentication required
        '403':
          description: Only master accounts can view sub-accounts
        '500':
          description: Internal server error
      security:
      - bearerAuth: []
  /api/v1/accounts/sub-accounts/limits:
    post:
      tags:
      - AccountsService
      - Account Limits
      summary: Create sub-account limit
      description: |-
        Create sub-account limit.

         Create a new limit for a sub-account. Only master accounts can create
         limits for their sub-accounts.
      operationId: create_sub_account_limit
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateLimitRequest'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateLimitResponse'
        '201':
          description: Limit created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateLimitResponse'
        '400':
          description: Invalid request or limit already exists
        '401':
          description: Authentication required
        '403':
          description: Only master accounts can set sub-account limits
        '404':
          description: Sub-account relationship not found or asset not found
        '500':
          description: Internal server error
      security:
      - bearerAuth: []
  /api/v1/accounts/sub-accounts/{sub_account_id}/limits:
    get:
      tags:
      - AccountsService
      - Account Limits
      summary: Get sub-account limits
      description: |-
        Get sub-account limits.

         Get all limits for a sub-account. Users can only view limits for their
         own accounts or their sub-accounts.
      operationId: get_sub_account_limits
      parameters:
      - name: sub_account_id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetLimitsResponse'
        '400':
          description: Invalid request
        '401':
          description: Authentication required
        '403':
          description: Only master accounts can view sub-account limits
        '404':
          description: Sub-account not found
        '500':
          description: Internal server error
      security:
      - bearerAuth: []
  /api/v1/accounts/sub-accounts/{sub_account_id}/limits/{asset_id}:
    put:
      tags:
      - AccountsService
      - Account Limits
      summary: Update sub-account limit
      description: |-
        Update sub-account limit.

         Update an existing limit for a sub-account. Only master accounts can
         update limits for their sub-accounts.
      operationId: update_sub_account_limit
      parameters:
      - name: sub_account_id
        in: path
        required: true
        schema:
          type: string
      - name: asset_id
        in: path
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateLimitRequest'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdateLimitResponse'
        '400':
          description: Invalid request
        '401':
          description: Authentication required
        '403':
          description: Only master accounts can update sub-account limits
        '404':
          description: Limit not found
        '500':
          description: Internal server error
      security:
      - bearerAuth: []
    delete:
      tags:
      - AccountsService
      - Account Limits
      summary: Delete sub-account limit
      description: |-
        Delete sub-account limit.

         Delete a limit for a sub-account. Only master accounts can delete limits
         for their sub-accounts.
      operationId: delete_sub_account_limit
      parameters:
      - name: sub_account_id
        in: path
        required: true
        schema:
          type: string
      - name: asset_id
        in: path
        required: true
        schema:
          type: string
      - name: limit_id
        in: query
        schema:
          type: string
          minLength: 1
          format: uuid
        description: Limit identifier (UUID)
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteLimitResponse'
        '400':
          description: Invalid request
        '401':
          description: Authentication required
        '403':
          description: Only master accounts can delete sub-account limits
        '404':
          description: Limit not found
        '500':
          description: Internal server error
      security:
      - bearerAuth: []
  /api/v1/accounts/trades:
    get:
      tags:
      - AccountsService
      - Accounts
      summary: Get user trade history
      description: |-
        Get user trades.

         Get the authenticated user's trade history with pagination.
         Returns trades where the user was either maker or taker, with
         user-specific side and fee information.
      operationId: get_user_trades
      parameters:
      - name: page
        in: query
        schema:
          type: integer
          format: uint32
          minimum: 1
          maximum: 10000
        description: Page number (1-indexed)
      - name: page_size
        in: query
        schema:
          type: integer
          format: uint32
          minimum: 1
          maximum: 100
          default: 20
        description: Items per page (max 100)
      - name: trading_pair_id
        in: query
        schema:
          type: string
          minLength: 1
          format: uuid
        description: Trading pair identifier (UUID)
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetUserTradesResponse'
        '400':
          description: Invalid request
        '401':
          description: Authentication required
        '500':
          description: Internal server error
      security:
      - bearerAuth: []
  /api/v1/applications/balances:
    get:
      tags:
      - ApplicationsService
      - Applications (Backend)
      summary: List application balances
      description: |-
        List application balances.

         Returns a paginated list of all user balances for this application.
         Requires backend authentication via secret key.
      operationId: list_application_balances
      parameters:
      - name: page
        in: query
        schema:
          type: integer
          format: uint32
          minimum: 1
          maximum: 10000
        description: Page number (1-indexed)
      - name: page_size
        in: query
        schema:
          type: integer
          format: uint32
          minimum: 1
          maximum: 100
          default: 20
        description: Items per page (max 100)
      - name: user_id
        in: query
        schema:
          type: string
          minLength: 1
          format: uuid
        description: User identifier (UUID)
      - name: asset_id
        in: query
        schema:
          type: string
          minLength: 1
          format: uuid
        description: Asset identifier (UUID)
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListAppBalancesResponse'
        '400':
          description: Bad request
        '401':
          description: Unauthorized - Invalid or missing x-server-key
        '500':
          description: Internal server error
      security:
      - apiKey: []
  /api/v1/applications/config:
    get:
      tags:
      - ApplicationsService
      - Applications
      summary: Get application configuration
      description: |-
        Get application configuration.

         Returns the configuration for the authenticated application including
         allowed origins, webhook URL, and vault contract address.
      operationId: get_application_config
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetConfigResponse'
        '400':
          description: Bad request
        '401':
          description: Unauthorized - Invalid or missing JWT
        '404':
          description: Application not found
        '500':
          description: Internal server error
      security:
      - bearerAuth: []
  /api/v1/applications/movements:
    get:
      tags:
      - ApplicationsService
      - Applications (Backend)
      summary: List application movements
      description: |-
        List application movements.

         Returns a paginated list of all ledger movements (deposits, withdrawals,
         trades, etc.) for this application. Requires backend authentication via
         secret key.
      operationId: list_application_movements
      parameters:
      - name: page
        in: query
        schema:
          type: integer
          format: uint32
          minimum: 1
          maximum: 10000
        description: Page number (1-indexed)
      - name: page_size
        in: query
        schema:
          type: integer
          format: uint32
          minimum: 1
          maximum: 100
          default: 20
        description: Items per page (max 100)
      - name: user_id
        in: query
        schema:
          type: string
          minLength: 1
          format: uuid
        description: User identifier (UUID)
      - name: transaction_type
        in: query
        schema:
          type: string
          enum:
          - DEPOSIT
          - WITHDRAWAL
          - TRADE
          - FEE
          - FUNDING
          - LIQUIDATION
          - INTEREST
          - REWARD
          - CHAIN_SYNC
          minLength: 1
        description: Transaction type
      - name: entry_type
        in: query
        schema:
          type: string
          enum:
          - CREDIT
          - DEBIT
          - LOCK
          - UNLOCK
          - FEE
          minLength: 1
        description: Ledger entry type
      - name: asset_id
        in: query
        schema:
          type: string
          minLength: 1
          format: uuid
        description: Asset identifier (UUID)
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListAppMovementsResponse'
        '400':
          description: Bad request
        '401':
          description: Unauthorized - Invalid or missing x-server-key
        '500':
          description: Internal server error
      security:
      - apiKey: []
  /api/v1/applications/orders:
    get:
      tags:
      - ApplicationsService
      - Applications (Backend)
      summary: List application orders
      description: |-
        List application orders.

         Returns a paginated list of all orders for this application. Requires
         backend authentication via secret key.
      operationId: list_application_orders
      parameters:
      - name: page
        in: query
        schema:
          type: integer
          format: uint32
          minimum: 1
          maximum: 10000
        description: Page number (1-indexed)
      - name: page_size
        in: query
        schema:
          type: integer
          format: uint32
          minimum: 1
          maximum: 100
          default: 20
        description: Items per page (max 100)
      - name: status
        in: query
        schema:
          type: string
          minLength: 1
        description: Order status (single value or comma-separated list)
      - name: user_id
        in: query
        schema:
          type: string
          minLength: 1
          format: uuid
        description: User identifier (UUID)
      - name: trading_pair_id
        in: query
        schema:
          type: string
          minLength: 1
          format: uuid
        description: Trading pair identifier (UUID)
      - name: side
        in: query
        schema:
          type: string
          enum:
          - BUY
          - SELL
          minLength: 1
        description: Order side
      - name: order_type
        in: query
        schema:
          type: string
          enum:
          - LIMIT
          - MARKET
          - STOP_LOSS
          - TAKE_PROFIT
          - STOP_LIMIT
          - TRAILING_STOP
          minLength: 1
        description: Order type
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListAppOrdersResponse'
        '400':
          description: Bad request
        '401':
          description: Unauthorized - Invalid or missing x-server-key
        '500':
          description: Internal server error
      security:
      - apiKey: []
  /api/v1/applications/users:
    get:
      tags:
      - ApplicationsService
      - Applications (Backend)
      summary: List application users
      description: |-
        List application users.

         Returns a paginated list of all users for this application. Requires
         backend authentication via secret key.
      operationId: list_application_users
      parameters:
      - name: page
        in: query
        schema:
          type: integer
          format: uint32
          minimum: 1
          maximum: 10000
        description: Page number (1-indexed)
      - name: page_size
        in: query
        schema:
          type: integer
          format: uint32
          minimum: 1
          maximum: 100
          default: 20
        description: Items per page (max 100)
      - name: is_active
        in: query
        schema:
          type: boolean
      - name: account_type
        in: query
        schema:
          type: string
          enum:
          - master
          - sub
          minLength: 1
        description: Account type filter
      - name: address
        in: query
        schema:
          type: string
          minLength: 1
        description: Wallet address
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListAppUsersResponse'
        '400':
          description: Bad request
        '401':
          description: Unauthorized - Invalid or missing x-server-key
        '500':
          description: Internal server error
      security:
      - apiKey: []
  /api/v1/auth/backend:
    post:
      tags:
      - AuthService
      - Auth
      summary: Backend service authentication
      description: |-
        Backend service authentication.

         Authenticate a backend service using a secret key. Returns a long-lived
         access token for server-to-server API access.
      operationId: authenticate_backend
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BackendAuthRequest'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BackendAuthResponse'
        '400':
          description: Invalid request parameters
        '401':
          description: Invalid secret key or inactive application
        '500':
          description: Internal server error
  /api/v1/auth/challenge:
    post:
      tags:
      - AuthService
      - Auth
      summary: Create authentication challenge
      description: |-
        Create authentication challenge.

         Generate a cryptographic challenge (nonce) for wallet-based authentication.
         The user must sign the returned message with their private key to prove
         ownership of the wallet.
      operationId: create_challenge
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChallengeRequest'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChallengeResponse'
        '400':
          description: Invalid request parameters
        '403':
          description: Origin not allowed for this application
        '404':
          description: Invalid client_id
        '500':
          description: Internal server error
  /api/v1/auth/refresh:
    post:
      tags:
      - AuthService
      - Auth
      summary: Refresh access token
      description: |-
        Refresh access token.

         Generate a new access token using a valid refresh token. The refresh
         token remains valid for future use.
      operationId: refresh_token
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RefreshRequest'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RefreshResponse'
        '400':
          description: Invalid request parameters
        '401':
          description: Invalid, expired, or revoked refresh token
        '404':
          description: User not found
        '500':
          description: Internal server error
  /api/v1/auth/revoke:
    post:
      tags:
      - AuthService
      - Auth
      summary: Revoke current session
      description: |-
        Revoke current session.

         Revoke the current authenticated session, invalidating the access token.
         The user will need to authenticate again.
      operationId: revoke_session
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RevokeRequest'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RevokeResponse'
        '400':
          description: Request body must be empty
        '401':
          description: Missing or invalid authorization token
        '404':
          description: Session not found
        '500':
          description: Internal server error
      security:
      - bearerAuth: []
  /api/v1/auth/verify:
    post:
      tags:
      - AuthService
      - Auth
      summary: Verify signature and authenticate
      description: |-
        Verify signature and authenticate.

         Verify the signed challenge message and create an authenticated session.
         Returns JWT tokens for subsequent API access.
      operationId: verify_signature
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VerifyRequest'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VerifyResponse'
        '400':
          description: Invalid request parameters, nonce expired, or already used
        '401':
          description: Invalid signature
        '403':
          description: Origin not allowed for this application
        '404':
          description: Invalid nonce or client_id
        '500':
          description: Internal server error
  /api/v1/faucet/mint:
    post:
      tags:
      - FaucetService
      - Faucet
      summary: Mint all testnet tokens
      description: |-
        Mint all testnet tokens.

         Mint all available testnet tokens to the authenticated user's address.
         Rate limited per 24 hours.
      operationId: mint_tokens
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MintTokensResponse'
        '400':
          description: Invalid request
        '401':
          description: Authentication required
        '429':
          description: Rate limit exceeded
        '500':
          description: Internal server error
      security:
      - bearerAuth: []
  /api/v1/fees/simulate:
    get:
      tags:
      - FeesService
      - Fees
      summary: Simulate fees for a potential order
      description: |-
        Simulate fees for a potential order.

         Returns exact fee breakdown for a specific order before placing it,
         including Monaco protocol fees, application fees, total amounts,
         and the maximum quantity affordable at the given price.
      operationId: simulate_fees
      parameters:
      - name: trading_pair_id
        in: query
        schema:
          type: string
          minLength: 1
          format: uuid
        description: Trading pair identifier (UUID)
        required: true
      - name: side
        in: query
        schema:
          type: string
          enum:
          - BUY
          - SELL
          minLength: 1
        description: Order side
        required: true
      - name: price
        in: query
        schema:
          type: string
          minLength: 1
        description: Price as decimal string
        required: true
      - name: quantity
        in: query
        schema:
          type: string
          minLength: 1
        description: Quantity as decimal string
        required: true
      - name: order_type
        in: query
        schema:
          type: string
          enum:
          - LIMIT
          - MARKET
          - STOP_LOSS
          - TAKE_PROFIT
          - STOP_LIMIT
          - TRAILING_STOP
          minLength: 1
        description: Order type
      - name: slippage_tolerance_bps
        in: query
        schema:
          type: integer
          format: int32
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimulateFeesResponse'
        '400':
          description: Bad request (e.g., slippage with LIMIT order)
        '401':
          description: Authentication required
        '404':
          description: Trading pair or application not found
        '500':
          description: Internal server error
      security:
      - bearerAuth: []
  /api/v1/market/pairs:
    get:
      tags:
      - MarketService
      - Market
      summary: Trading Pairs
      description: |-
        Trading Pairs

         Get paginated list of trading pairs with optional filtering by market
         type, base token, quote token, and active status.
      operationId: list_trading_pairs
      parameters:
      - name: page
        in: query
        schema:
          type: integer
          format: uint32
          minimum: 1
          maximum: 10000
        description: Page number (1-indexed)
      - name: page_size
        in: query
        schema:
          type: integer
          format: uint32
          minimum: 1
          maximum: 100
          default: 20
        description: Items per page (max 100)
      - name: market_type
        in: query
        schema:
          type: string
          enum:
          - SPOT
          - MARGIN
          minLength: 1
        description: Filter by market type
      - name: base_token
        in: query
        schema:
          type: string
      - name: quote_token
        in: query
        schema:
          type: string
      - name: is_active
        in: query
        schema:
          type: boolean
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListTradingPairsResponse'
        '400':
          description: Invalid market type parameter
        '500':
          description: Internal server error
  /api/v1/market/pairs/charts/candlestick/{trading_pair_id}/{interval}:
    get:
      tags:
      - MarketService
      - Market
      summary: Candlestick Data
      description: |-
        Candlestick Data

         Get OHLCV (Open, High, Low, Close, Volume) candlestick data for a
         trading pair with configurable interval and time range.
      operationId: get_candles
      parameters:
      - name: trading_pair_id
        in: path
        required: true
        schema:
          type: string
      - name: interval
        in: path
        required: true
        schema:
          type: string
      - name: start_time
        in: query
        schema:
          type: integer
          minimum: 0
          maximum: 4102444800000
          format: int64
        description: Start time as Unix timestamp (milliseconds)
      - name: end_time
        in: query
        schema:
          type: integer
          minimum: 0
          maximum: 4102444800000
          format: int64
        description: End time as Unix timestamp (milliseconds)
      - name: limit
        in: query
        schema:
          type: integer
          format: uint32
          minimum: 1
          maximum: 1000
          default: 100
        description: Max candles to return (max 1000)
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetCandlesResponse'
        '400':
          description: Invalid parameters
        '404':
          description: Trading pair not found or inactive
        '500':
          description: Internal server error
  /api/v1/market/pairs/{trading_pair_id}:
    get:
      tags:
      - MarketService
      - Market
      summary: Trading Pair By ID
      description: |-
        Trading Pair By ID

         Get a specific trading pair by its UUID.
      operationId: get_trading_pair_by_id
      parameters:
      - name: trading_pair_id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetTradingPairResponse'
        '404':
          description: Trading pair not found
        '500':
          description: Internal server error
  /api/v1/market/pairs/{trading_pair_id}/metadata:
    get:
      tags:
      - MarketService
      - Market
      summary: Market Metadata
      description: |-
        Market Metadata

         Returns current price (from latest candle), 24h statistics (high, low,
         volume, change), and market initialization timestamp. 24h fields will
         be null if less than 24 hours of data available.
      operationId: get_market_metadata
      parameters:
      - name: trading_pair_id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetMarketMetadataResponse'
        '404':
          description: Trading pair not found
        '500':
          description: Internal server error
  /api/v1/orderbook/{trading_pair_id}:
    get:
      tags:
      - OrderbookService
      - Orderbook
      summary: Orderbook Snapshot
      description: |-
        Orderbook Snapshot

         Get the complete orderbook snapshot for a trading pair showing all bids
         and asks with their price levels. This is a public endpoint that does
         not require authentication.
      operationId: get_orderbook_snapshot
      parameters:
      - name: trading_pair_id
        in: path
        required: true
        schema:
          type: string
      - name: levels
        in: query
        schema:
          type: integer
          format: uint32
          minimum: 1
          maximum: 100
          default: 20
        description: Number of price levels (max 100)
      - name: trading_mode
        in: query
        schema:
          type: string
          enum:
          - SPOT
          - MARGIN
          minLength: 1
        description: Trading mode
      - name: magnitude
        in: query
        schema:
          type: string
          enum:
          - '0.0001'
          - '0.001'
          - '0.01'
          - '0.1'
          - '1'
          - '10'
          - '100'
          - '1000'
          - '10000'
          minLength: 1
        description: Price grouping magnitude
      - name: denomination
        in: query
        schema:
          type: string
          enum:
          - base
          - quote
          minLength: 1
        description: Price denomination
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetOrderbookResponse'
        '400':
          description: Invalid magnitude or denomination value
        '404':
          description: Trading pair not found
        '500':
          description: Matching engine not initialized or internal error
  /api/v1/orders:
    get:
      tags:
      - OrdersService
      - Orders
      summary: Get user orders
      description: |-
        Get user orders.

         Get orders for the authenticated user with pagination and optional
         filtering by status and trading pair.
      operationId: get_orders
      parameters:
      - name: page
        in: query
        schema:
          type: integer
          format: uint32
          minimum: 1
          maximum: 10000
        description: Page number (1-indexed)
      - name: page_size
        in: query
        schema:
          type: integer
          format: uint32
          minimum: 1
          maximum: 100
          default: 20
        description: Items per page (max 100)
      - name: status
        in: query
        schema:
          type: string
          minLength: 1
        description: Order status (single value or comma-separated list)
      - name: trading_pair_id
        in: query
        schema:
          type: string
          minLength: 1
          format: uuid
        description: Trading pair identifier (UUID)
      - name: order_by
        in: query
        schema:
          type: string
          default: DESC
          enum:
          - ASC
          - DESC
          minLength: 1
        description: Sort direction for created_at
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListOrdersResponse'
        '400':
          description: Invalid query parameters
        '401':
          description: Authentication required
        '403':
          description: User does not belong to application
        '404':
          description: User not found
        '500':
          description: Internal server error
      security:
      - bearerAuth: []
    post:
      tags:
      - OrdersService
      - Orders
      summary: Create new order
      description: |-
        Create new order.

         Create a new order and process it through the matching engine. The order
         will be matched against existing orders in the orderbook.
      operationId: create_order
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateOrderRequest'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateOrderResponse'
        '400':
          description: Invalid order parameters or insufficient balance
        '401':
          description: Authentication required
        '500':
          description: Internal server error or matching engine failure
      security:
      - bearerAuth: []
  /api/v1/orders/batch-cancel:
    post:
      tags:
      - OrdersService
      - Orders
      summary: Batch cancel specific orders
      description: |-
        Batch cancel specific orders.

         Cancel multiple specific orders by their IDs. For canceling all orders,
         use /batch-cancel-all or /batch-cancel-all/{trading_pair_id}.
      operationId: batch_cancel_orders
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchCancelOrdersRequest'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchCancelOrdersResponse'
        '400':
          description: Invalid request - order_ids is required
        '401':
          description: Authentication required
        '500':
          description: Internal server error or matching engine failure
      security:
      - bearerAuth: []
  /api/v1/orders/batch-cancel-all:
    post:
      tags:
      - OrdersService
      - Orders
      summary: Cancel all orders
      description: |-
        Cancel all orders.

         Cancel all active orders for the authenticated user. To cancel orders
         for a specific trading pair, use /batch-cancel-all/{trading_pair_id}.
      operationId: batch_cancel_all
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchCancelAllResponse'
        '401':
          description: Authentication required
        '500':
          description: Internal server error or matching engine failure
      security:
      - bearerAuth: []
  /api/v1/orders/batch-cancel-all/{trading_pair_id}:
    post:
      tags:
      - OrdersService
      - Orders
      summary: Cancel all orders for a trading pair
      description: |-
        Cancel all orders for a trading pair.

         Cancel all active orders for the authenticated user on a specific
         trading pair.
      operationId: batch_cancel_all_by_pair
      parameters:
      - name: trading_pair_id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchCancelAllResponse'
        '400':
          description: Invalid trading pair ID
        '401':
          description: Authentication required
        '500':
          description: Internal server error or matching engine failure
      security:
      - bearerAuth: []
  /api/v1/orders/batch-create:
    post:
      tags:
      - OrdersService
      - Orders
      summary: Batch create orders
      description: |-
        Batch create orders.

         Create multiple orders in a single batch. Each order is processed
         sequentially through the matching engine.
      operationId: batch_create_orders
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchCreateOrdersRequest'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchCreateOrdersResponse'
        '400':
          description: Invalid request
        '401':
          description: Authentication required
        '500':
          description: Internal server error
      security:
      - bearerAuth: []
  /api/v1/orders/batch-replace:
    post:
      tags:
      - OrdersService
      - Orders
      summary: Batch replace orders
      description: |-
        Batch replace orders.

         Replace multiple orders in a single batch. Each order is processed
         sequentially through the matching engine.
      operationId: batch_replace_orders
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchReplaceOrdersRequest'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchReplaceOrdersResponse'
        '400':
          description: Invalid request
        '401':
          description: Authentication required
        '500':
          description: Internal server error
      security:
      - bearerAuth: []
  /api/v1/orders/cancel:
    post:
      tags:
      - OrdersService
      - Orders
      summary: Cancel existing order
      description: |-
        Cancel existing order.

         Cancel an existing order and unlock the reserved funds. Only orders that
         are not yet filled can be cancelled.
      operationId: cancel_order
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CancelOrderRequest'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CancelOrderResponse'
        '400':
          description: Invalid order ID or order already filled/cancelled
        '401':
          description: Authentication required or order doesn't belong to user
        '404':
          description: Order not found
        '500':
          description: Internal server error
      security:
      - bearerAuth: []
  /api/v1/orders/{order_id}:
    get:
      tags:
      - OrdersService
      - Orders
      summary: Get order by ID
      description: |-
        Get order by ID.

         Get a single order by its ID. Users can only access their own orders.
      operationId: get_order_by_id
      parameters:
      - name: order_id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetOrderResponse'
        '400':
          description: Invalid order ID format
        '401':
          description: Authentication required
        '403':
          description: User does not have permission to view this order
        '404':
          description: Order not found or user not found
        '500':
          description: Internal server error
      security:
      - bearerAuth: []
    put:
      tags:
      - OrdersService
      - Orders
      summary: Replace existing order
      description: |-
        Replace existing order.

         Replaces an existing order with new parameters by canceling the original
         order and creating a new one with the updated price/quantity. Priority is
         lost in the order book.
      operationId: replace_order
      parameters:
      - name: order_id
        in: path
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReplaceOrderRequest'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReplaceOrderResponse'
        '400':
          description: Invalid order ID, order cannot be replaced, or insufficient balance
        '401':
          description: Authentication required or order doesn't belong to user
        '404':
          description: Order not found
        '500':
          description: Internal server error
      security:
      - bearerAuth: []
  /api/v1/trades/by-id/{trade_id}:
    get:
      tags:
      - TradesService
      - Trades
      summary: Get Trade by ID
      description: |-
        Get Trade by ID

         Retrieve a single trade by its unique identifier.
      operationId: get_trade_by_id
      parameters:
      - name: trade_id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetTradeByIdResponse'
        '400':
          description: Invalid trade ID
        '404':
          description: Trade not found
        '500':
          description: Internal server error
  /api/v1/trades/{trading_pair_id}:
    get:
      tags:
      - TradesService
      - Trades
      summary: Recent Trades
      description: |-
        Recent Trades

         Get recent trades for a trading pair sorted by execution time.
      operationId: get_trades
      parameters:
      - name: trading_pair_id
        in: path
        required: true
        schema:
          type: string
      - name: page
        in: query
        schema:
          type: integer
          format: uint32
          minimum: 1
          maximum: 10000
        description: Page number (1-indexed)
      - name: page_size
        in: query
        schema:
          type: integer
          format: uint32
          minimum: 1
          maximum: 100
          default: 25
        description: Max trades to return (max 100)
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetTradesResponse'
        '400':
          description: Invalid trading pair ID
        '404':
          description: Trading pair not found
        '500':
          description: Internal server error
  /api/v1/whitelist:
    post:
      tags:
      - WhitelistService
      - Whitelist
      summary: Submit whitelist application
      description: |-
        Submit whitelist application.

         Submit a whitelist application to join Monaco Protocol. The user will be
         created with is_active = false and will need to be approved by an admin.
      operationId: submit_whitelist
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SubmitWhitelistRequest'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubmitWhitelistResponse'
        '400':
          description: Invalid request parameters
        '409':
          description: Wallet address or email already registered
        '500':
          description: Internal server error
  /health:
    get:
      tags:
      - HealthService
      - Health
      summary: Health check
      description: |-
        Health check.

         Returns the current health status of the API gateway and its connected
         services. Can be used for monitoring and load balancer health checks.
      operationId: health_check
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicHealthCheckResponse'
        '503':
          description: Service is unhealthy
components:
  schemas:
    AccountBalance:
      type: object
      properties:
        token:
          nullable: true
          type: string
          description: Token contract address
        symbol:
          example: USDC
          type: string
          description: Token symbol
          nullable: true
        decimals:
          example: 6
          type: integer
          description: Token decimal places
          format: int32
          nullable: true
        available_balance:
          example: '1000.50'
          type: string
          description: Available (unlocked) balance in token units
          nullable: true
        locked_balance:
          example: '50.25'
          type: string
          description: Balance locked in open orders
          nullable: true
        total_balance:
          example: '1050.75'
          type: string
          description: Total balance (available + locked + margin_locked)
          nullable: true
        available_balance_raw:
          example: '1000500000'
          type: string
          description: Raw available balance in smallest token unit
          nullable: true
        locked_balance_raw:
          example: '50250000'
          type: string
          description: Raw locked balance in smallest token unit
          nullable: true
        asset_id:
          example: 123e4567-e89b-12d3-a456-426614174000
          type: string
          description: Asset UUID
          format: uuid
          nullable: true
        margin_locked:
          example: '300.00'
          type: string
          description: Balance posted as collateral into margin (perps) accounts, in token units
          nullable: true
        margin_locked_raw:
          example: '300000000'
          type: string
          description: Raw margin-locked collateral in smallest token unit
          nullable: true
    AppUser:
      type: object
      properties:
        id:
          example: 123e4567-e89b-12d3-a456-426614174000
          type: string
          description: User UUID
          format: uuid
          nullable: true
        address:
          maxLength: 42
          type: string
          description: Wallet address
          nullable: true
          pattern: ^0x[0-9a-fA-F]{40}$
          minLength: 42
        username:
          example: trader123
          type: string
          description: Display username
          nullable: true
        account_type:
          example: master
          type: string
          description: 'Account type: master or sub'
          nullable: true
        can_withdraw:
          example: true
          type: boolean
          description: Whether the user is allowed to withdraw
          nullable: true
        created_at:
          example: 2023-11-13T10:30:00Z
          type: string
          description: Account creation timestamp (ISO 8601)
          nullable: true
        email:
          type: string
          description: Email address
          nullable: true
        is_active:
          example: true
          type: boolean
          description: Whether the user account is active
          nullable: true
        is_banned:
          example: false
          type: boolean
          description: Whether the user is banned
          nullable: true
        master_account_id:
          type: string
          description: Master account ID (for sub-accounts)
          format: uuid
          nullable: true
        updated_at:
          example: 2023-11-13T10:35:00Z
          type: string
          description: Last update timestamp (ISO 8601)
          nullable: true
    ApplicationBalance:
      type: object
      properties:
        available_balance:
          type: string
          description: Available balance for trading
          nullable: true
        created_at:
          type: string
          description: Balance creation timestamp (ISO 8601)
          nullable: true
        decimals:
          type: integer
          description: Token decimals
          format: int32
          nullable: true
        id:
          type: string
          description: Balance UUID
          format: uuid
          nullable: true
        last_sync_at:
          type: string
          description: Last sync timestamp (ISO 8601)
          nullable: true
        last_sync_block:
          type: string
          description: Last sync block number
          nullable: true
        locked_balance:
          type: string
          description: Locked balance
          nullable: true
        margin_locked:
          type: string
          description: Margin locked balance
          nullable: true
        on_chain_balance:
          type: string
          description: On-chain balance
          nullable: true
        symbol:
          type: string
          description: Token symbol
          nullable: true
        token:
          type: string
          description: Token address
          nullable: true
        total_balance:
          type: string
          description: Total balance
          nullable: true
        updated_at:
          type: string
          description: Balance last update timestamp (ISO 8601)
          nullable: true
        user_id:
          type: string
          description: User UUID who owns this balance
          format: uuid
          nullable: true
    ApplicationMovement:
      type: object
      properties:
        amount:
          type: string
          description: Transaction amount
          nullable: true
        balance_after:
          type: string
          description: Balance after this transaction
          nullable: true
        balance_before:
          type: string
          description: Balance before this transaction
          nullable: true
        balance_id:
          type: string
          description: Balance UUID this movement affects
          format: uuid
          nullable: true
        block_number:
          type: string
          description: Blockchain block number
          nullable: true
        created_at:
          type: string
          description: Transaction timestamp (ISO 8601)
          nullable: true
        description:
          type: string
          description: Human readable description
          nullable: true
        entry_type:
          type: string
          description: Type of ledger entry
          nullable: true
        id:
          type: string
          description: Movement UUID
          format: uuid
          nullable: true
        locked_after:
          type: string
          description: Locked balance after transaction
          nullable: true
        locked_before:
          type: string
          description: Locked balance before transaction
          nullable: true
        reference_id:
          type: string
          description: Reference identifier for related operations
          format: uuid
          nullable: true
        reference_type:
          type: string
          description: Reference type
          nullable: true
        token:
          type: string
          description: Token address
          nullable: true
        transaction_type:
          type: string
          description: Type of transaction
          nullable: true
        tx_hash:
          type: string
          description: Blockchain transaction hash
          nullable: true
        user_id:
          type: string
          description: User UUID who owns this movement
          format: uuid
          nullable: true
    ApplicationOrder:
      type: object
      properties:
        id:
          example: 123e4567-e89b-12d3-a456-426614174000
          type: string
          description: Order UUID
          format: uuid
          nullable: true
        user_id:
          example: 123e4567-e89b-12d3-a456-426614174000
          type: string
          description: User UUID who placed the order
          format: uuid
          nullable: true
        trading_pair_id:
          example: 456e7890-e12b-12d3-a456-426614174000
          type: string
          description: Trading pair UUID
          format: uuid
          nullable: true
        order_type:
          example: LIMIT
          type: string
          description: 'Order type: LIMIT, MARKET, STOP_LOSS, TAKE_PROFIT, STOP_LIMIT, or TRAILING_STOP'
          nullable: true
        side:
          example: BUY
          type: string
          description: 'Order side: BUY or SELL'
          nullable: true
        price:
          example: '35000.00'
          type: string
          description: Order price (null for market orders)
          nullable: true
        quantity:
          example: '0.5'
          type: string
          description: Order quantity (normalized for display)
          nullable: true
        quantity_raw:
          example: '500000000'
          type: string
          description: Order quantity in raw format (for precision)
          nullable: true
        filled_quantity:
          example: '0.2'
          type: string
          description: Filled quantity (normalized for display)
          nullable: true
        filled_quantity_raw:
          example: '200000000'
          type: string
          description: Filled quantity in raw format
          nullable: true
        average_fill_price:
          example: '35050.00'
          type: string
          description: Volume-weighted average fill price
          nullable: true
        status:
          example: SUBMITTED
          type: string
          description: Order status
          nullable: true
        trading_mode:
          example: SPOT
          type: string
          description: 'Trading mode: SPOT or MARGIN'
          nullable: true
        time_in_force:
          example: GTC
          type: string
          description: 'Time in force: GTC, IOC, or FOK'
          nullable: true
        created_at:
          example: 2023-11-13T10:30:00Z
          type: string
          description: Order creation timestamp (ISO 8601)
          nullable: true
        updated_at:
          example: 2023-11-13T10:35:00Z
          type: string
          description: Order last update timestamp (ISO 8601)
          nullable: true
    BackendAuthRequest:
      required:
      - secret_key
      type: object
      properties:
        secret_key:
          example: sk_live_abc123def456
          type: string
          description: Backend secret key (sk_xxx)
      additionalProperties: false
    BackendAuthResponse:
      type: object
      properties:
        app_id:
          example: 123e4567-e89b-12d3-a456-426614174000
          type: string
          description: Application UUID
          nullable: true
        client_id:
          example: monaco-frontend
          type: string
          description: Application client identifier
          nullable: true
        name:
          example: Monaco Trading Frontend
          type: string
          description: Application display name
          nullable: true
    BatchCancelAllResponse:
      type: object
      properties:
        total_requested:
          example: 10
          type: integer
          description: Number of orders requested to cancel
          format: int32
          nullable: true
        total_cancelled:
          example: 10
          type: integer
          description: Number of orders successfully cancelled
          format: int32
          nullable: true
        total_failed:
          example: 0
          type: integer
          description: Number of cancellations that failed
          format: int32
          nullable: true
        results:
          type: array
          items:
            $ref: '#/components/schemas/BatchCancelResult'
          nullable: true
    BatchCancelError:
      type: object
      properties:
        code:
          example: ORDER_ALREADY_FILLED
          type: string
          description: Machine-readable error code
          nullable: true
        message:
          example: Order has already been fully filled
          type: string
          description: Human-readable error message
          nullable: true
    BatchCancelOrdersRequest:
      required:
      - order_ids
      type: object
      properties:
        order_ids:
          minItems: 1
          type: array
          items:
            type: string
            minLength: 1
            format: uuid
          description: List of order UUIDs to cancel
      additionalProperties: false
    BatchCancelOrdersResponse:
      type: object
      properties:
        total_requested:
          example: 5
          type: integer
          description: Number of orders requested to cancel
          format: int32
          nullable: true
        total_cancelled:
          example: 4
          type: integer
          description: Number of orders successfully cancelled
          format: int32
          nullable: true
        total_failed:
          example: 1
          type: integer
          description: Number of cancellations that failed
          format: int32
          nullable: true
        results:
          type: array
          items:
            $ref: '#/components/schemas/BatchCancelResult'
          nullable: true
    BatchCancelResult:
      type: object
      properties:
        order_id:
          example: 123e4567-e89b-12d3-a456-426614174000
          type: string
          description: Order UUID
          format: uuid
          nullable: true
        cancelled_at:
          example: 2023-11-13T10:35:00Z
          type: string
          description: Cancellation timestamp (ISO 8601). Present on success; absent when `error` is set.
          nullable: true
        error:
          $ref: '#/components/schemas/BatchCancelError'
    BatchCreateError:
      type: object
      properties:
        code:
          example: INSUFFICIENT_BALANCE
          type: string
          description: Machine-readable error code
          nullable: true
        message:
          example: Insufficient balance to place order
          type: string
          description: Human-readable error message
          nullable: true
    BatchCreateOrderItem:
      required:
      - trading_pair_id
      - order_type
      - side
      - quantity
      type: object
      properties:
        trading_pair_id:
          example: 456e7890-e12b-12d3-a456-426614174000
          type: string
          description: Trading pair UUID
          format: uuid
        order_type:
          example: LIMIT
          type: string
          description: 'Order type: LIMIT or MARKET'
        side:
          example: BUY
          type: string
          description: 'Order side: BUY or SELL'
        price:
          example: '35000.00'
          type: string
          description: Limit price as decimal string (required for LIMIT orders)
          nullable: true
        quantity:
          example: '0.5'
          type: string
          description: Order quantity as decimal string
        trading_mode:
          example: SPOT
          type: string
          description: 'Trading mode: SPOT or MARGIN (default: SPOT)'
          nullable: true
        slippage_tolerance_bps:
          example: 50
          maximum: 10000
          type: integer
          description: Maximum slippage tolerance in basis points (market orders only)
          format: int32
          nullable: true
        use_master_balance:
          example: false
          type: boolean
          description: Use master account balance for sub-account orders
          nullable: true
        expiration_date:
          example: 2026-06-01T00:00:00Z
          type: string
          description: Order expiration date (ISO 8601, must be in the future)
          nullable: true
        time_in_force:
          example: GTC
          type: string
          description: 'Time in force: GTC, IOC, or FOK'
          nullable: true
      additionalProperties: false
    BatchCreateOrdersRequest:
      required:
      - orders
      type: object
      properties:
        orders:
          minItems: 1
          type: array
          items:
            $ref: '#/components/schemas/BatchCreateOrderItem'
      additionalProperties: false
    BatchCreateOrdersResponse:
      type: object
      properties:
        total_requested:
          example: 5
          type: integer
          description: Number of orders requested to create
          format: int32
          nullable: true
        total_succeeded:
          example: 4
          type: integer
          description: Number of orders successfully created
          format: int32
          nullable: true
        total_failed:
          example: 1
          type: integer
          description: Number of creations that failed
          format: int32
          nullable: true
        results:
          type: array
          items:
            $ref: '#/components/schemas/BatchCreateResult'
          nullable: true
    BatchCreateResult:
      type: object
      properties:
        order_id:
          example: 123e4567-e89b-12d3-a456-426614174000
          type: string
          description: Created order UUID
          format: uuid
          nullable: true
        match_result:
          $ref: '#/components/schemas/MatchResult'
        error:
          $ref: '#/components/schemas/BatchCreateError'
    BatchReplaceError:
      type: object
      properties:
        code:
          example: ORDER_NOT_FOUND
          type: string
          description: Machine-readable error code
          nullable: true
        message:
          example: Order not found or already filled
          type: string
          description: Human-readable error message
          nullable: true
    BatchReplaceOrderItem:
      required:
      - order_id
      type: object
      properties:
        order_id:
          example: 123e4567-e89b-12d3-a456-426614174000
          type: string
          description: Order UUID to replace
          format: uuid
        price:
          example: '35500.00'
          type: string
          description: New limit price (if changing)
          nullable: true
        quantity:
          example: '0.7'
          type: string
          description: New quantity (if changing)
          nullable: true
        use_master_balance:
          example: false
          type: boolean
          description: Use master account balance for sub-account orders
          nullable: true
      additionalProperties: false
    BatchReplaceOrdersRequest:
      required:
      - orders
      type: object
      properties:
        orders:
          minItems: 1
          type: array
          items:
            $ref: '#/components/schemas/BatchReplaceOrderItem'
      additionalProperties: false
    BatchReplaceOrdersResponse:
      type: object
      properties:
        total_requested:
          example: 3
          type: integer
          description: Number of orders requested to replace
          format: int32
          nullable: true
        total_succeeded:
          example: 3
          type: integer
          description: Number of orders successfully replaced
          format: int32
          nullable: true
        total_failed:
          example: 0
          type: integer
          description: Number of replacements that failed
          format: int32
          nullable: true
        results:
          type: array
          items:
            $ref: '#/components/schemas/BatchReplaceResult'
          nullable: true
    BatchReplaceResult:
      type: object
      properties:
        original_order_id:
          example: 123e4567-e89b-12d3-a456-426614174000
          type: string
          description: Original order UUID that was replaced
          format: uuid
          nullable: true
        new_order_id:
          example: 987e6543-e21b-12d3-a456-426614174000
          type: string
          description: New replacement order UUID (if successful)
          format: uuid
          nullable: true
        updated_fields:
          $ref: '#/components/schemas/UpdatedFields'
        match_result:
          $ref: '#/components/schemas/MatchResult'
        error:
          $ref: '#/components/schemas/BatchReplaceError'
    CancelOrderRequest:
      required:
      - order_id
      type: object
      properties:
        order_id:
          example: 123e4567-e89b-12d3-a456-426614174000
          type: string
          description: Order UUID to cancel
          format: uuid
      additionalProperties: false
    CancelOrderResponse:
      type: object
      properties:
        order_id:
          example: 123e4567-e89b-12d3-a456-426614174000
          type: string
          description: Cancelled order UUID
          format: uuid
          nullable: true
        status:
          example: SUCCESS
          type: string
          description: 'Result status: SUCCESS or FAILED'
          nullable: true
        message:
          example: Order cancelled successfully
          type: string
          description: Human-readable status message
          nullable: true
    Candle:
      type: object
      properties:
        timestamp:
          nullable: true
          type: string
          description: Unix timestamp for the start of the candle period in milliseconds
        open:
          example: '35000.00'
          type: string
          description: Opening price
          nullable: true
        high:
          example: '35500.00'
          type: string
          description: Highest price during the period
          nullable: true
        low:
          example: '34800.00'
          type: string
          description: Lowest price during the period
          nullable: true
        close:
          example: '35200.00'
          type: string
          description: Closing price
          nullable: true
        volume:
          example: '125.5'
          type: string
          description: Base token volume traded during the period
          nullable: true
        quote_volume:
          example: '4412600.00'
          type: string
          description: Quote token volume traded during the period
          nullable: true
        trade_count:
          example: 342
          type: integer
          description: Number of trades during the period
          format: uint32
          nullable: true
        close_timestamp_ms:
          nullable: true
          type: string
          description: Unix timestamp for the end of the candle period in milliseconds
    ChallengeRequest:
      required:
      - address
      - session_public_key
      type: object
      properties:
        address:
          description: Ethereum wallet address
          maxLength: 42
          minLength: 42
          pattern: ^0x[0-9a-fA-F]{40}$
          type: string
        client_id:
          example: monaco-frontend
          type: string
          description: Optional application identifier
          nullable: true
        chain_id:
          nullable: true
          type: string
          description: Optional chain ID supplied by SDK clients
        session_public_key:
          description: Lowercase hex (64 chars) ed25519 session public key generated
            locally by the SDK. The returned challenge message embeds this key so the
            wallet's signature binds it; submit the same value to /api/v1/auth/verify.
          maxLength: 64
          minLength: 64
          pattern: ^[0-9a-f]{64}$
          type: string
      additionalProperties: false
    ChallengeResponse:
      type: object
      properties:
        nonce:
          example: abc123def456
          type: string
          description: Unique challenge nonce
          nullable: true
        message:
          example: Sign this message to authenticate with Monaco Protocol...
          type: string
          description: Message to sign
          nullable: true
        expires_at:
          example: 1699876543
          type: integer
          description: Unix timestamp when challenge expires
          format: int32
          nullable: true
    ChartDataPoint:
      type: object
      properties:
        timestamp:
          example: 2026-02-18T00:00:00Z
          type: string
          description: Bucket timestamp (ISO 8601)
          nullable: true
        value:
          example: '-0.002'
          type: string
          description: Metric value for this bucket
          nullable: true
    CreateLimitRequest:
      required:
      - sub_account_id
      - asset_id
      - max_amount
      type: object
      properties:
        sub_account_id:
          example: 123e4567-e89b-12d3-a456-426614174000
          type: string
          description: Sub-account UUID to create the limit for
          format: uuid
        asset_id:
          example: 123e4567-e89b-12d3-a456-426614174000
          type: string
          description: Asset UUID to limit
          format: uuid
        max_amount:
          example: '1000.00'
          minLength: 1
          pattern: ^-?[0-9]{1,28}(\.[0-9]{1,18})?$
          type: string
          description: Maximum amount allowed in token units
        daily_limit:
          example: '500.00'
          minLength: 1
          pattern: ^-?[0-9]{1,28}(\.[0-9]{1,18})?$
          type: string
          description: Maximum daily spending limit in token units
          nullable: true
      additionalProperties: false
    CreateLimitResponse:
      type: object
      properties:
        limit:
          $ref: '#/components/schemas/SubAccountLimit'
    CreateOrderRequest:
      required:
      - trading_pair_id
      - order_type
      - side
      - quantity
      type: object
      properties:
        trading_pair_id:
          example: afae0e16-2d05-4ee9-9ee8-afae0e162d05
          type: string
          description: Trading pair UUID
          format: uuid
        order_type:
          example: LIMIT
          type: string
          description: 'Order type: LIMIT or MARKET'
        side:
          example: BUY
          type: string
          description: 'Order side: BUY or SELL'
        price:
          example: '35000.00'
          type: string
          description: Limit price as decimal string (required for LIMIT orders)
          nullable: true
        quantity:
          example: '0.5'
          type: string
          description: Order quantity as decimal string
        trading_mode:
          example: SPOT
          type: string
          description: 'Trading mode: SPOT or MARGIN (default: SPOT)'
          nullable: true
        slippage_tolerance_bps:
          example: 50
          maximum: 10000
          type: integer
          description: Maximum slippage tolerance in basis points (market orders only)
          format: int32
          nullable: true
        use_master_balance:
          example: false
          type: boolean
          description: Use master account balance for sub-account orders
          nullable: true
        expiration_date:
          example: 2026-06-01T00:00:00Z
          type: string
          description: Order expiration date (ISO 8601, must be in the future)
          nullable: true
        time_in_force:
          example: GTC
          type: string
          description: 'Time in force: GTC, IOC, or FOK'
          nullable: true
      additionalProperties: false
    CreateOrderResponse:
      type: object
      properties:
        order_id:
          example: 123e4567-e89b-12d3-a456-426614174000
          type: string
          description: Created order UUID
          format: uuid
          nullable: true
        status:
          example: SUCCESS
          type: string
          description: 'Result status: SUCCESS or FAILED'
          nullable: true
        message:
          example: Order created successfully
          type: string
          description: Human-readable status message
          nullable: true
        match_result:
          $ref: '#/components/schemas/MatchResult'
    DeleteLimitResponse:
      type: object
      properties:
        message:
          example: Limit deleted successfully
          type: string
          description: Human-readable status message
          nullable: true
    ExecutionPriceRange:
      type: object
      properties:
        best_price:
          example: '2045.00'
          type: string
          description: Best execution price achieved
          nullable: true
        worst_price:
          example: '2052.00'
          type: string
          description: Worst execution price in the fill
          nullable: true
    FailedMint:
      type: object
      properties:
        asset_id:
          example: 123e4567-e89b-12d3-a456-426614174000
          type: string
          description: Asset UUID
          nullable: true
          format: uuid
        symbol:
          example: WBTC
          type: string
          description: Token symbol
          nullable: true
        error:
          example: Mint transaction failed
          type: string
          description: Error message describing why the mint failed
          nullable: true
    GetBalanceByAssetResponse:
      type: object
      properties:
        token:
          nullable: true
          type: string
          description: Token contract address
        symbol:
          example: USDC
          type: string
          description: Token symbol
          nullable: true
        decimals:
          example: 6
          type: integer
          description: Token decimal places
          format: int32
          nullable: true
        available_balance:
          example: '1000.50'
          type: string
          description: Available (unlocked) balance in token units
          nullable: true
        locked_balance:
          example: '50.25'
          type: string
          description: Balance locked in open orders
          nullable: true
        total_balance:
          example: '1050.75'
          type: string
          description: Total balance (available + locked + margin_locked)
          nullable: true
        available_balance_raw:
          example: '1000500000'
          type: string
          description: Raw available balance in smallest token unit
          nullable: true
        locked_balance_raw:
          example: '50250000'
          type: string
          description: Raw locked balance in smallest token unit
          nullable: true
        asset_id:
          example: 123e4567-e89b-12d3-a456-426614174000
          type: string
          description: Asset UUID
          format: uuid
          nullable: true
        margin_locked:
          example: '300.00'
          type: string
          description: Balance posted as collateral into margin (perps) accounts, in token units
          nullable: true
        margin_locked_raw:
          example: '300000000'
          type: string
          description: Raw margin-locked collateral in smallest token unit
          nullable: true
    GetBalancesResponse:
      type: object
      properties:
        balances:
          type: array
          items:
            $ref: '#/components/schemas/AccountBalance'
          nullable: true
        total:
          example: 5
          type: integer
          description: Total number of balances
          format: uint32
          nullable: true
        page:
          example: 1
          type: integer
          description: Current page number
          format: uint32
          nullable: true
        page_size:
          example: 20
          type: integer
          description: Items per page
          format: uint32
          nullable: true
        total_pages:
          example: 1
          type: integer
          description: Total number of pages
          format: uint32
          nullable: true
    GetCandlesResponse:
      type: object
      properties:
        candles:
          type: array
          items:
            $ref: '#/components/schemas/Candle'
          nullable: true
      description: OHLCV candlestick data.
    GetConfigResponse:
      type: object
      properties:
        id:
          example: 123e4567-e89b-12d3-a456-426614174000
          type: string
          description: Application UUID
          nullable: true
        name:
          example: Monaco
          type: string
          description: Application display name
          nullable: true
        allowed_origins:
          type: array
          items:
            type: string
            minLength: 1
          description: List of allowed origins for CORS
          nullable: true
        webhook_url:
          type: string
          description: Webhook URL for notifications
          nullable: true
        vault_contract_address:
          nullable: true
          type: string
          description: Vault contract address for this application
        client_id:
          example: 6fe0da813f1a4adcbe675d52ca530a43
          type: string
          description: Application client ID, embedded in on-chain deposit calls
          nullable: true
    GetLimitsResponse:
      type: object
      properties:
        limits:
          type: array
          items:
            $ref: '#/components/schemas/SubAccountLimit'
          nullable: true
    GetMarketMetadataResponse:
      type: object
      properties:
        base_icon_url:
          example: https://assets.0xmonaco.com/icons/btc.svg
          type: string
          description: URL for the base token icon
          nullable: true
        high_24h:
          example: '96500.00'
          type: string
          description: Highest price in the last 24 hours
          nullable: true
        last_price:
          example: '95432.50'
          type: string
          description: Most recent trade price
          nullable: true
        last_price_timestamp:
          example: '1736742000000'
          type: string
          description: Timestamp of the last trade (ms since epoch)
          nullable: true
        low_24h:
          example: '94200.00'
          type: string
          description: Lowest price in the last 24 hours
          nullable: true
        market_initialization_timestamp:
          example: '1735000000000'
          type: string
          description: When this market was first initialized (ms since epoch)
          nullable: true
        price_change_24h:
          example: '1232.50'
          type: string
          description: Absolute price change in the last 24 hours
          nullable: true
        price_change_percent_24h:
          example: '1.31'
          type: string
          description: Percentage price change in the last 24 hours
          nullable: true
        quote_icon_url:
          example: https://assets.0xmonaco.com/icons/usdc.svg
          type: string
          description: URL for the quote token icon
          nullable: true
        symbol:
          example: BTC/USDC
          type: string
          description: Trading pair symbol
          nullable: true
        volume_24h:
          example: '1234.5678'
          type: string
          description: Base token volume in the last 24 hours
          nullable: true
      description: Market metadata with current price and 24h statistics.
    GetMovementsResponse:
      type: object
      properties:
        movements:
          type: array
          items:
            $ref: '#/components/schemas/LedgerMovement'
          nullable: true
        total:
          example: 150
          type: integer
          description: Total number of movements
          format: uint32
          nullable: true
        page:
          example: 1
          type: integer
          description: Current page number
          format: uint32
          nullable: true
        page_size:
          example: 20
          type: integer
          description: Items per page
          format: uint32
          nullable: true
        total_pages:
          example: 8
          type: integer
          description: Total number of pages
          format: uint32
          nullable: true
    GetOrderResponse:
      type: object
      properties:
        id:
          example: 123e4567-e89b-12d3-a456-426614174000
          type: string
          description: Order UUID
          format: uuid
          nullable: true
        trading_pair_id:
          example: 456e7890-e12b-12d3-a456-426614174000
          type: string
          description: Trading pair UUID
          format: uuid
          nullable: true
        order_type:
          example: LIMIT
          type: string
          description: 'Order type: LIMIT or MARKET'
          nullable: true
        side:
          example: BUY
          type: string
          description: 'Order side: BUY or SELL'
          nullable: true
        price:
          example: '35000.00'
          type: string
          description: Limit price (null for market orders)
          nullable: true
        quantity:
          example: '0.5'
          type: string
          description: Original order quantity
          nullable: true
        filled_quantity:
          example: '0.2'
          type: string
          description: Quantity filled so far
          nullable: true
        average_fill_price:
          example: '35050.00'
          type: string
          description: Volume-weighted average fill price
          nullable: true
        status:
          example: PARTIALLY_FILLED
          type: string
          description: 'Order status: SUBMITTED, PARTIALLY_FILLED, FILLED, CANCELLED, REJECTED, or EXPIRED'
          nullable: true
        trading_mode:
          example: SPOT
          type: string
          description: 'Trading mode: SPOT or MARGIN'
          nullable: true
        time_in_force:
          example: GTC
          type: string
          description: 'Time in force: GTC, IOC, or FOK'
          nullable: true
        created_at:
          example: 2023-11-13T10:30:00Z
          type: string
          description: Order creation timestamp (ISO 8601)
          nullable: true
        updated_at:
          example: 2023-11-13T10:35:00Z
          type: string
          description: Last update timestamp (ISO 8601)
          nullable: true
        expiration_date:
          example: 2023-11-13T10:35:00Z
          type: string
          description: Order expiration date (ISO 8601)
          nullable: true
        application_taker_fee:
          example: '5'
          type: string
          description: Application taker fee in bps
          nullable: true
        monaco_taker_fee:
          example: '10'
          type: string
          description: Monaco protocol taker fee in bps
          nullable: true
        monaco_maker_rebate:
          example: '-2'
          type: string
          description: Monaco maker rebate in bps (negative)
          nullable: true
        total_taker_fees:
          example: '2.63'
          type: string
          description: Total taker fees charged in quote token
          nullable: true
        taker_total_payment:
          example: '17502.63'
          type: string
          description: Total amount paid by taker (price * qty + fees)
          nullable: true
        maker_total_receipt:
          example: '17496.50'
          type: string
          description: Total amount received by maker (price * qty - rebate)
          nullable: true
    GetOrderbookResponse:
      type: object
      properties:
        base_decimals:
          example: 8
          type: integer
          description: Base token decimal places
          format: int32
          nullable: true
        base_token:
          example: BTC
          type: string
          description: Base token symbol
          nullable: true
        data:
          $ref: '#/components/schemas/OrderbookData'
        event_type:
          example: orderbook_snapshot
          type: string
          description: Event type identifier
          nullable: true
        symbol:
          example: BTC/USDC
          type: string
          description: Trading pair symbol
          nullable: true
        trading_pair_id:
          example: 123e4567-e89b-12d3-a456-426614174000
          type: string
          description: Trading pair UUID
          format: uuid
          nullable: true
        quote_decimals:
          example: 6
          type: integer
          description: Quote token decimal places
          format: int32
          nullable: true
        quote_token:
          example: USDC
          type: string
          description: Quote token symbol
          nullable: true
        sequence_number:
          example: 12345
          type: integer
          description: Orderbook sequence number
          format: uint32
          nullable: true
        timestamp:
          example: 2023-11-13T10:30:00Z
          type: string
          description: Snapshot timestamp
          nullable: true
        trading_mode:
          example: Spot
          type: string
          description: Trading mode
          nullable: true
      description: Orderbook snapshot with token metadata and sequence number.
    GetPortfolioChartResponse:
      type: object
      properties:
        metric:
          example: pnl
          type: string
          description: Metric used for this query
          nullable: true
        period:
          example: 30d
          type: string
          description: Period used for this query
          nullable: true
        data:
          type: array
          items:
            $ref: '#/components/schemas/ChartDataPoint'
          nullable: true
    GetPortfolioStatsResponse:
      type: object
      properties:
        period:
          example: 30d
          type: string
          description: Period used for this query
          nullable: true
        volume:
          example: '231.81'
          type: string
          description: Total trade volume (sum of quote_volume)
          nullable: true
        total_trades:
          nullable: true
          type: string
          description: Number of trades in period
        total_orders:
          nullable: true
          type: string
          description: Number of orders in period
        fees_paid:
          example: '0.12'
          type: string
          description: Total fees paid by user
          nullable: true
        pnl:
          example: '-0.01'
          type: string
          description: Profit and loss (CREDIT - DEBIT from trade ledger entries)
          nullable: true
        total_equity:
          example: '280.93'
          type: string
          description: Total equity (sum of all balances)
          nullable: true
        spot_equity:
          example: '280.93'
          type: string
          description: Spot account equity
          nullable: true
        perps_equity:
          example: '0.00'
          type: string
          description: Perpetuals account equity
          nullable: true
        win_loss_ratio:
          example: 0.65
          type: number
          description: Ratio of profitable trades to total trades
          format: double
          nullable: true
        max_drawdown:
          example: '0.00'
          type: string
          description: Maximum peak-to-trough drawdown on running PnL
          nullable: true
    GetProfileResponse:
      type: object
      properties:
        id:
          example: 123e4567-e89b-12d3-a456-426614174000
          type: string
          description: User UUID
          format: uuid
          nullable: true
        address:
          maxLength: 42
          type: string
          description: Wallet address
          nullable: true
          pattern: ^0x[0-9a-fA-F]{40}$
          minLength: 42
        username:
          example: trader123
          type: string
          description: Display username
          nullable: true
        account_type:
          example: master
          type: string
          description: 'Account type: master or sub'
          nullable: true
        can_withdraw:
          example: true
          type: boolean
          description: Whether the user is allowed to withdraw
          nullable: true
        created_at:
          example: 2023-11-13T10:30:00Z
          type: string
          description: Account creation timestamp (ISO 8601)
          nullable: true
        maker_fee_bps:
          example: -1
          type: integer
          description: Base maker fee in basis points from active trading pair
          format: int32
          nullable: true
        taker_fee_bps:
          example: 5
          type: integer
          description: Base taker fee in basis points from active trading pair
          format: int32
          nullable: true
        application_taker_fee_bps:
          example: 0
          type: integer
          description: Additional taker fee in basis points from application
          format: int32
          nullable: true
        application_maker_fee_bps:
          example: 0
          type: integer
          description: Additional maker fee in basis points from application
          format: int32
          nullable: true
    GetTradeByIdResponse:
      type: object
      properties:
        trade:
          $ref: '#/components/schemas/PublicTrade'
      description: A single trade.
    GetTradesResponse:
      type: object
      properties:
        trades:
          type: array
          items:
            $ref: '#/components/schemas/PublicTrade'
          nullable: true
        page:
          example: 1
          type: integer
          description: Current page number
          format: uint32
          nullable: true
        page_size:
          example: 25
          type: integer
          description: Maximum number of trades returned
          format: uint32
          nullable: true
      description: Recent trades for a trading pair.
    GetTradingPairResponse:
      type: object
      properties:
        trading_pair:
          $ref: '#/components/schemas/TradingPairData'
      description: Single trading pair details.
    GetUserTradesResponse:
      type: object
      properties:
        trades:
          type: array
          items:
            $ref: '#/components/schemas/UserTrade'
          nullable: true
        page:
          nullable: true
          type: string
          description: Current page number
        page_size:
          nullable: true
          type: string
          description: Items per page
        total:
          nullable: true
          type: string
          description: Total number of trades
        total_pages:
          nullable: true
          type: string
          description: Total number of pages
    LedgerMovement:
      type: object
      properties:
        id:
          example: 123e4567-e89b-12d3-a456-426614174000
          type: string
          description: Movement UUID
          format: uuid
          nullable: true
        entry_type:
          example: CREDIT
          type: string
          description: 'Ledger entry type: CREDIT, DEBIT, LOCK, UNLOCK, or FEE'
          nullable: true
        transaction_type:
          example: DEPOSIT
          type: string
          description: 'Transaction type: DEPOSIT, WITHDRAWAL, TRADE, or FEE'
          nullable: true
        amount:
          example: '100.50'
          type: string
          description: Human-readable amount in token units
          nullable: true
        token:
          nullable: true
          type: string
          description: Token contract address
        balance_before:
          example: '900.00'
          type: string
          description: Available balance before this movement
          nullable: true
        balance_after:
          example: '1000.50'
          type: string
          description: Available balance after this movement
          nullable: true
        locked_before:
          example: '50.00'
          type: string
          description: Locked balance before this movement
          nullable: true
        locked_after:
          example: '75.00'
          type: string
          description: Locked balance after this movement
          nullable: true
        reference_id:
          example: ref_123456
          type: string
          description: ID of the related entity (order, trade, etc.)
          nullable: true
        reference_type:
          example: deposit
          type: string
          description: Type of the referenced entity
          nullable: true
        description:
          example: USDC deposit
          type: string
          description: Human-readable description of the movement
          nullable: true
        tx_hash:
          nullable: true
          type: string
          description: On-chain transaction hash (if applicable)
        block_number:
          nullable: true
          type: string
          description: Block number of the on-chain transaction
        created_at:
          example: 2023-11-13T10:30:00Z
          type: string
          description: Movement timestamp (ISO 8601)
          nullable: true
        symbol:
          example: USDC
          type: string
          description: Token symbol
          nullable: true
        decimals:
          example: 6
          type: integer
          description: Token decimal places
          format: int32
          nullable: true
        amount_raw:
          example: '100500000'
          type: string
          description: Raw amount in smallest token unit (no decimals)
          nullable: true
        balance_before_raw:
          example: '900000000'
          type: string
          description: Raw available balance before this movement
          nullable: true
        balance_after_raw:
          example: '1000500000'
          type: string
          description: Raw available balance after this movement
          nullable: true
        locked_before_raw:
          example: '50000000'
          type: string
          description: Raw locked balance before this movement
          nullable: true
        locked_after_raw:
          example: '75000000'
          type: string
          description: Raw locked balance after this movement
          nullable: true
        asset_id:
          example: 123e4567-e89b-12d3-a456-426614174000
          type: string
          description: Asset UUID
          format: uuid
          nullable: true
        user_id:
          example: 123e4567-e89b-12d3-a456-426614174000
          type: string
          description: User UUID who owns this movement
          format: uuid
          nullable: true
        balance_id:
          example: 123e4567-e89b-12d3-a456-426614174000
          type: string
          description: Balance UUID this movement affects
          format: uuid
          nullable: true
    ListAppBalancesResponse:
      type: object
      properties:
        balances:
          type: array
          items:
            $ref: '#/components/schemas/ApplicationBalance'
          nullable: true
        total:
          example: 50
          type: integer
          description: Total matching balances
          format: uint32
          nullable: true
        page:
          example: 1
          type: integer
          description: Current page number
          format: uint32
          nullable: true
        page_size:
          example: 20
          type: integer
          description: Items per page
          format: uint32
          nullable: true
        total_pages:
          example: 3
          type: integer
          description: Total number of pages
          format: uint32
          nullable: true
    ListAppMovementsResponse:
      type: object
      properties:
        movements:
          type: array
          items:
            $ref: '#/components/schemas/ApplicationMovement'
          nullable: true
        total:
          example: 150
          type: integer
          description: Total matching movements
          format: uint32
          nullable: true
        page:
          example: 1
          type: integer
          description: Current page number
          format: uint32
          nullable: true
        page_size:
          example: 20
          type: integer
          description: Items per page
          format: uint32
          nullable: true
        total_pages:
          example: 8
          type: integer
          description: Total number of pages
          format: uint32
          nullable: true
    ListAppOrdersResponse:
      type: object
      properties:
        orders:
          type: array
          items:
            $ref: '#/components/schemas/ApplicationOrder'
          nullable: true
        total:
          example: 150
          type: integer
          description: Total matching orders
          format: uint32
          nullable: true
        page:
          example: 1
          type: integer
          description: Current page number
          format: uint32
          nullable: true
        page_size:
          example: 20
          type: integer
          description: Items per page
          format: uint32
          nullable: true
        total_pages:
          example: 8
          type: integer
          description: Total number of pages
          format: uint32
          nullable: true
    ListAppUsersResponse:
      type: object
      properties:
        users:
          type: array
          items:
            $ref: '#/components/schemas/AppUser'
          nullable: true
        total:
          example: 50
          type: integer
          description: Total number of users
          format: uint32
          nullable: true
        page:
          example: 1
          type: integer
          description: Current page number
          format: uint32
          nullable: true
        page_size:
          example: 20
          type: integer
          description: Items per page
          format: uint32
          nullable: true
        total_pages:
          example: 3
          type: integer
          description: Total number of pages
          format: uint32
          nullable: true
    ListOrdersResponse:
      type: object
      properties:
        orders:
          type: array
          items:
            $ref: '#/components/schemas/GetOrderResponse'
          nullable: true
        total:
          example: 150
          type: integer
          description: Total number of orders matching the filter
          format: uint32
          nullable: true
        page:
          example: 1
          type: integer
          description: Current page number
          format: uint32
          nullable: true
        page_size:
          example: 20
          type: integer
          description: Items per page
          format: uint32
          nullable: true
        total_pages:
          example: 8
          type: integer
          description: Total number of pages
          format: uint32
          nullable: true
    ListSubAccountsResponse:
      type: object
      properties:
        sub_accounts:
          type: array
          items:
            $ref: '#/components/schemas/SubAccount'
          nullable: true
        total:
          example: 0
          type: integer
          description: Total number of sub-accounts
          format: uint32
          nullable: true
    ListTradingPairsResponse:
      type: object
      properties:
        trading_pairs:
          type: array
          items:
            $ref: '#/components/schemas/TradingPairData'
          nullable: true
        page:
          example: 1
          type: integer
          description: Current page number
          format: uint32
          nullable: true
        page_size:
          example: 20
          type: integer
          description: Items per page
          format: uint32
          nullable: true
        total:
          example: 50
          type: integer
          description: Total number of trading pairs
          format: uint32
          nullable: true
        total_pages:
          example: 3
          type: integer
          description: Total number of pages
          format: uint32
          nullable: true
      description: Paginated list of trading pairs.
    MatchResult:
      type: object
      properties:
        trades_count:
          example: 2
          type: integer
          description: Number of trades generated by this order
          format: int32
          nullable: true
        total_filled:
          example: '0.2'
          type: string
          description: Total quantity filled
          nullable: true
        remaining_quantity:
          example: '0.3'
          type: string
          description: Remaining unfilled quantity
          nullable: true
        average_fill_price:
          example: '35100.00'
          type: string
          description: Volume-weighted average fill price
          nullable: true
        order_status:
          example: PARTIALLY_FILLED
          type: string
          description: Resulting order status after matching
          nullable: true
        actual_slippage_bps:
          example: 15
          type: integer
          description: Actual slippage incurred in basis points
          format: int32
          nullable: true
        max_slippage_bps:
          example: 50
          type: integer
          description: Maximum slippage tolerance that was set
          format: int32
          nullable: true
        execution_price_range:
          $ref: '#/components/schemas/ExecutionPriceRange'
    MintTokensResponse:
      type: object
      properties:
        minted:
          type: array
          items:
            $ref: '#/components/schemas/MintedToken'
          nullable: true
        failed:
          type: array
          items:
            $ref: '#/components/schemas/FailedMint'
          nullable: true
        remaining_requests_24h:
          example: 4
          type: integer
          description: Remaining faucet requests in next 24h
          format: uint32
          nullable: true
    MintedToken:
      type: object
      properties:
        asset_id:
          example: 123e4567-e89b-12d3-a456-426614174000
          type: string
          description: Asset UUID
          nullable: true
          format: uuid
        symbol:
          example: USDC
          type: string
          description: Token symbol
          nullable: true
        amount:
          example: '10000.00'
          type: string
          description: Amount minted in token units
          nullable: true
        tx_hash:
          nullable: true
          type: string
          description: On-chain transaction hash
    OrderbookData:
      type: object
      properties:
        bids:
          type: array
          items:
            $ref: '#/components/schemas/PriceLevel'
          nullable: true
        asks:
          type: array
          items:
            $ref: '#/components/schemas/PriceLevel'
          nullable: true
        best_bid:
          example: '34900.00'
          type: string
          description: Highest bid price
          nullable: true
        best_ask:
          example: '35100.00'
          type: string
          description: Lowest ask price
          nullable: true
        bid_volume:
          example: '15.5'
          type: string
          description: Total bid-side volume
          nullable: true
        ask_volume:
          example: '12.3'
          type: string
          description: Total ask-side volume
          nullable: true
        price_change:
          $ref: '#/components/schemas/PriceChange'
    PriceChange:
      type: object
      properties:
        price_24h_ago:
          example: '34500.00'
          type: string
          description: Price 24 hours ago
          nullable: true
        price_change_24h:
          example: '500.00'
          type: string
          description: Absolute price change in last 24 hours
          nullable: true
        price_change_percent_24h:
          example: '1.45'
          type: string
          description: Percentage price change in last 24 hours
          nullable: true
    PriceLevel:
      type: object
      properties:
        price:
          example: '35000.00'
          type: string
          description: Price at this level
          nullable: true
        quantity:
          example: '1.5'
          type: string
          description: Total quantity at this price level
          nullable: true
        order_count:
          example: 3
          type: integer
          description: Number of orders at this price level
          format: uint32
          nullable: true
    PublicHealthCheckResponse:
      type: object
      properties:
        status:
          example: healthy
          type: string
          description: 'Health status: healthy or unhealthy'
          nullable: true
        service:
          example: api-gateway
          type: string
          description: Service name
          nullable: true
        version:
          example: 0.1.0
          type: string
          description: Service version
          nullable: true
        timestamp:
          example: 1699872600
          type: integer
          description: Current server timestamp (Unix epoch seconds)
          format: int32
          nullable: true
    PublicTrade:
      type: object
      properties:
        trade_id:
          example: 123e4567-e89b-12d3-a456-426614174000
          type: string
          description: Trade UUID
          format: uuid
          nullable: true
        trading_pair_id:
          example: 456e7890-e12b-12d3-a456-426614174000
          type: string
          description: Trading pair UUID
          format: uuid
          nullable: true
        price:
          example: '35000.00'
          type: string
          description: Execution price
          nullable: true
        quantity:
          example: '0.5'
          type: string
          description: Traded quantity in base token
          nullable: true
        side:
          example: BUY
          type: string
          description: 'Taker side: BUY or SELL'
          nullable: true
        trading_mode:
          example: SPOT
          type: string
          description: 'Trading mode: SPOT or MARGIN'
          nullable: true
        executed_at:
          example: 2023-11-13T10:30:00Z
          type: string
          description: Trade execution timestamp (ISO 8601)
          nullable: true
    RefreshRequest:
      type: object
      properties: {}
      additionalProperties: false
    RefreshResponse:
      type: object
      properties:
        expires_at:
          example: 1699876543
          type: integer
          description: Unix timestamp when the session expires after refresh
          format: int32
          nullable: true
    ReplaceOrderRequest:
      type: object
      properties:
        use_master_balance:
          example: false
          type: boolean
          description: Use master account balance for sub-account orders
          nullable: true
        price:
          example: '35500.00'
          type: string
          description: New limit price (if changing)
          nullable: true
        quantity:
          example: '0.7'
          type: string
          description: New quantity (if changing)
          nullable: true
      additionalProperties: false
    ReplaceOrderResponse:
      type: object
      properties:
        order_id:
          example: 987e6543-e21b-12d3-a456-426614174000
          type: string
          description: New replacement order UUID
          format: uuid
          nullable: true
        status:
          example: SUCCESS
          type: string
          description: 'Result status: SUCCESS or FAILED'
          nullable: true
        message:
          example: Order replaced successfully
          type: string
          description: Human-readable status message
          nullable: true
        original_order_id:
          example: 123e4567-e89b-12d3-a456-426614174000
          type: string
          description: UUID of the original cancelled order
          format: uuid
          nullable: true
        updated_fields:
          $ref: '#/components/schemas/UpdatedFields'
        match_result:
          $ref: '#/components/schemas/MatchResult'
    RevokeRequest:
      type: object
      properties: {}
      additionalProperties: false
    RevokeResponse:
      type: object
      properties:
        message:
          example: Session revoked successfully
          type: string
          description: Human-readable status message
          nullable: true
    SimulateFeesResponse:
      type: object
      properties:
        notional:
          example: '20000.00'
          type: string
          description: Notional value (price x quantity)
          nullable: true
        monaco_taker_fee:
          example: '20.00'
          type: string
          description: Monaco protocol taker fee in quote token
          nullable: true
        monaco_maker_rebate:
          example: '-5.00'
          type: string
          description: Monaco maker rebate in quote token (negative)
          nullable: true
        application_taker_fee:
          example: '10.00'
          type: string
          description: Application-specific taker fee in quote token
          nullable: true
        total_taker_fees:
          example: '30.00'
          type: string
          description: Total taker fees (monaco + application)
          nullable: true
        taker_total_payment:
          example: '20030.00'
          type: string
          description: Total amount paid by taker (notional + fees)
          nullable: true
        maker_total_receipt:
          example: '19995.00'
          type: string
          description: Total amount received by maker (notional - rebate)
          nullable: true
        buy_order_lock_amount:
          example: '20030.00'
          type: string
          description: Amount locked for buy orders. For MARKET orders, includes slippage buffer.
          nullable: true
        monaco_taker_fee_bps:
          example: 10
          type: integer
          description: Monaco taker fee rate in basis points
          format: int32
          nullable: true
        monaco_maker_rebate_bps:
          example: -2
          type: integer
          description: Monaco maker rebate rate in bps (negative)
          format: int32
          nullable: true
        application_taker_fee_bps:
          example: 5
          type: integer
          description: Application taker fee rate in basis points
          format: int32
          nullable: true
        application_name:
          example: Monaco Trading Frontend
          type: string
          description: Application display name
          nullable: true
        max_quantity:
          example: '99.95'
          type: string
          description: Maximum quantity affordable at the given price, accounting for fees and slippage. Powers the 100% range input on the FE.
          nullable: true
        max_quantity_raw:
          example: '99950000000000000000'
          type: string
          description: Maximum quantity in RAW (smallest unit) format
          nullable: true
        slippage_tolerance_bps:
          example: 500
          type: integer
          description: Slippage tolerance used in the calculation (echoed back)
          format: int32
          nullable: true
    SubAccount:
      type: object
      properties:
        id:
          example: 123e4567-e89b-12d3-a456-426614174000
          type: string
          description: Sub-account UUID
          format: uuid
          nullable: true
        address:
          maxLength: 42
          type: string
          description: Sub-account wallet address
          nullable: true
          pattern: ^0x[0-9a-fA-F]{40}$
          minLength: 42
        username:
          example: sub_trader_1
          type: string
          description: Sub-account display username
          nullable: true
        can_withdraw:
          example: false
          type: boolean
          description: Whether the sub-account is allowed to withdraw
          nullable: true
        created_at:
          example: 2023-11-13T10:30:00Z
          type: string
          description: Account creation timestamp (ISO 8601)
          nullable: true
        balances:
          type: array
          items:
            $ref: '#/components/schemas/AccountBalance'
          nullable: true
    SubAccountLimit:
      type: object
      properties:
        id:
          example: 987e6543-e21b-12d3-a456-426614174000
          type: string
          description: Limit UUID
          format: uuid
          nullable: true
        sub_account_id:
          example: 123e4567-e89b-12d3-a456-426614174000
          type: string
          description: Sub-account UUID this limit applies to
          format: uuid
          nullable: true
        token:
          nullable: true
          type: string
          description: Token contract address
        daily_limit:
          example: '1000.00'
          type: string
          description: Maximum daily spending limit in token units
          nullable: true
        used_today:
          example: '250.50'
          type: string
          description: Amount used today against the limit
          nullable: true
        created_at:
          example: 2023-11-13T10:30:00Z
          type: string
          description: Limit creation timestamp (ISO 8601)
          nullable: true
        updated_at:
          example: 2023-11-13T10:30:00Z
          type: string
          description: Last update timestamp (ISO 8601)
          nullable: true
        master_account_id:
          example: 123e4567-e89b-12d3-a456-426614174001
          type: string
          description: Master account UUID that owns this sub-account
          format: uuid
          nullable: true
        max_amount:
          example: '1500.00'
          type: string
          description: Maximum amount allowed in token units
          nullable: true
        last_reset_at:
          example: 2023-11-13T00:00:00Z
          type: string
          description: Last reset timestamp for the daily limit (ISO 8601)
          nullable: true
        is_active:
          example: true
          type: boolean
          description: Whether the limit is active
          nullable: true
    SubmitWhitelistRequest:
      required:
      - wallet_address
      - email
      type: object
      properties:
        wallet_address:
          description: Applicant wallet address
          maxLength: 42
          minLength: 42
          pattern: ^0x[0-9a-fA-F]{40}$
          type: string
        email:
          example: user@example.com
          minLength: 1
          type: string
          description: Applicant email address
          format: email
        twitter_username:
          example: monaco_user
          maxLength: 15
          minLength: 1
          pattern: ^[A-Za-z0-9_]{1,15}$
          type: string
          description: Applicant Twitter/X username
          nullable: true
        telegram_username:
          example: monaco_user
          maxLength: 32
          minLength: 5
          pattern: ^[a-zA-Z0-9_]{5,32}$
          type: string
          description: Applicant Telegram username
          nullable: true
      additionalProperties: false
    SubmitWhitelistResponse:
      type: object
      properties:
        message:
          example: Your whitelist application has been submitted successfully! We'll review it and get back to you soon.
          type: string
          description: Human-readable status message
          nullable: true
        user_id:
          example: 123e4567-e89b-12d3-a456-426614174000
          type: string
          description: Created user UUID (pending approval)
          nullable: true
          format: uuid
    TradingPairData:
      type: object
      properties:
        base_asset_id:
          example: 456e7890-e12b-12d3-a456-426614174000
          type: string
          description: Base asset UUID
          format: uuid
          nullable: true
        base_decimals:
          example: 8
          type: integer
          description: Base token decimal places
          format: int32
          nullable: true
        base_icon_url:
          example: https://cdn.0xmonaco.com/assets/btc.svg
          type: string
          description: Base token icon URL
          nullable: true
        base_token:
          example: BTC
          type: string
          description: Base token symbol
          nullable: true
        base_token_contract:
          nullable: true
          type: string
          description: Base token contract address
        id:
          example: 123e4567-e89b-12d3-a456-426614174000
          type: string
          description: Trading pair UUID
          format: uuid
          nullable: true
        is_active:
          example: true
          type: boolean
          description: Pair active
          nullable: true
        maker_fee_bps:
          example: -2
          type: integer
          description: Maker fee in bps (negative = rebate)
          format: int32
          nullable: true
        market_type:
          example: SPOT
          type: string
          description: 'Market type: SPOT or MARGIN'
          nullable: true
        max_order_size:
          example: '100.0'
          type: string
          description: Maximum order size in base token
          nullable: true
        min_order_size:
          example: '0.0001'
          type: string
          description: Minimum order size in base token
          nullable: true
        quote_asset_id:
          example: 789e0123-e45b-12d3-a456-426614174000
          type: string
          description: Quote asset UUID
          format: uuid
          nullable: true
        quote_decimals:
          example: 6
          type: integer
          description: Quote token decimal places
          format: int32
          nullable: true
        quote_icon_url:
          example: https://cdn.0xmonaco.com/assets/usdc.svg
          type: string
          description: Quote token icon URL
          nullable: true
        quote_token:
          example: USDC
          type: string
          description: Quote token symbol
          nullable: true
        quote_token_contract:
          nullable: true
          type: string
          description: Quote token contract address
        symbol:
          example: BTC/USDC
          type: string
          description: Trading pair symbol
          nullable: true
        taker_fee_bps:
          example: 10
          type: integer
          description: Taker fee (bps)
          format: int32
          nullable: true
        tick_size:
          example: '0.01'
          type: string
          description: Minimum price increment
          nullable: true
      description: Trading pair configuration including tokens, fees, and order limits.
    UpdateLimitRequest:
      type: object
      properties:
        sub_account_id:
          example: 123e4567-e89b-12d3-a456-426614174000
          type: string
          description: Sub-account UUID
          format: uuid
          nullable: true
        asset_id:
          example: 123e4567-e89b-12d3-a456-426614174000
          type: string
          description: Asset UUID
          format: uuid
          nullable: true
        max_amount:
          example: '1500.00'
          minLength: 1
          pattern: ^-?[0-9]{1,28}(\.[0-9]{1,18})?$
          type: string
          description: New maximum amount allowed in token units
          nullable: true
        daily_limit:
          example: '500.00'
          minLength: 1
          pattern: ^-?[0-9]{1,28}(\.[0-9]{1,18})?$
          type: string
          description: New maximum daily spending limit in token units
          nullable: true
        is_active:
          example: true
          type: boolean
          description: Whether the limit is active
          nullable: true
      additionalProperties: false
    UpdateLimitResponse:
      type: object
      properties:
        limit:
          $ref: '#/components/schemas/SubAccountLimit'
    UpdatedFields:
      type: object
      properties:
        price:
          example: '35500.00'
          type: string
          description: New price (if changed)
          nullable: true
        quantity:
          example: '0.7'
          type: string
          description: New quantity (if changed)
          nullable: true
    UserInfo:
      type: object
      properties:
        id:
          example: 123e4567-e89b-12d3-a456-426614174000
          type: string
          description: User UUID
          format: uuid
          nullable: true
        address:
          maxLength: 42
          type: string
          description: Wallet address
          nullable: true
          pattern: ^0x[0-9a-fA-F]{40}$
          minLength: 42
        username:
          example: trader123
          type: string
          description: Display username
          nullable: true
    UserTrade:
      type: object
      properties:
        trade_id:
          example: 123e4567-e89b-12d3-a456-426614174000
          type: string
          description: Trade UUID
          format: uuid
          nullable: true
        trading_pair_id:
          example: 456e7890-e12b-12d3-a456-426614174000
          type: string
          description: Trading pair UUID
          format: uuid
          nullable: true
        price:
          example: '35000.00'
          type: string
          description: Execution price
          nullable: true
        quantity:
          example: '0.5'
          type: string
          description: Traded quantity
          nullable: true
        quote_volume:
          example: '17500.00'
          type: string
          description: Quote volume (price * quantity)
          nullable: true
        side:
          example: Buy
          type: string
          description: 'User''s side: Buy or Sell'
          nullable: true
        fee:
          example: '0.875'
          type: string
          description: Fee paid by this user for this trade
          nullable: true
        fee_token:
          nullable: true
          type: string
          description: Token address of the fee
        executed_at:
          example: 2023-11-13T10:30:00Z
          type: string
          description: Trade execution timestamp (ISO 8601)
          nullable: true
    VerifyRequest:
      required:
      - address
      - signature
      - nonce
      - session_public_key
      type: object
      properties:
        address:
          description: Ethereum wallet address
          maxLength: 42
          minLength: 42
          pattern: ^0x[0-9a-fA-F]{40}$
          type: string
        signature:
          description: Wallet signature over the challenge message
          minLength: 1
          type: string
        nonce:
          example: abc123def456
          minLength: 1
          type: string
          description: Challenge nonce
        client_id:
          example: monaco-frontend
          type: string
          description: Optional application identifier
          nullable: true
        chain_id:
          nullable: true
          type: string
          description: Optional chain ID supplied by SDK clients
        session_public_key:
          description: Lowercase hex (64 chars) ed25519 session public key. Subsequent
            authenticated requests are signed with the matching private key.
          maxLength: 64
          minLength: 64
          pattern: ^[0-9a-f]{64}$
          type: string
      additionalProperties: false
    VerifyResponse:
      type: object
      properties:
        expires_at:
          example: 1699876543
          type: integer
          description: Unix timestamp when the session expires
          format: int32
          nullable: true
        user:
          $ref: '#/components/schemas/UserInfo'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
    apiKey:
      type: apiKey
      name: x-server-key
      in: header
tags:
- name: AccountsService
- name: ApplicationsService
- name: AuthService
- name: FaucetService
- name: FeesService
- name: HealthService
- name: MarketService
- name: OrderbookService
- name: OrdersService
- name: TradesService
- name: WhitelistService
