openapi: 3.1.0
info:
  title: Bullet Trading Account User Data (Beta) API
  description: REST API for the Bullet exchange. Provides Binance FAPI-compatible endpoints for trading, account management, and market data.
  contact:
    name: Bullet
    url: https://bullet.xyz
  license:
    name: Proprietary
  version: 0.1.0
servers:
- url: /
  description: Current server
- url: https://tradingapi.mainnet.bullet.xyz
  description: Mainnet
- url: https://tradingapi.testnet.bullet.xyz
  description: Testnet
- url: https://tradingapi.staging.bullet.xyz
  description: Staging
tags:
- name: User Data (Beta)
paths:
  /fapi/v1/allOrders:
    get:
      tags:
      - User Data (Beta)
      summary: All Orders (order history from ClickHouse)
      operationId: all_orders
      parameters:
      - name: address
        in: query
        description: Account address (required on first request, encoded in cursor for subsequent)
        required: false
        schema:
          type:
          - string
          - 'null'
      - name: symbol
        in: query
        description: Trading pair symbol (optional filter)
        required: false
        schema:
          type:
          - string
          - 'null'
      - name: orderId
        in: query
        description: Return orders with orderId >= this value
        required: false
        schema:
          type:
          - integer
          - 'null'
          format: int64
          minimum: 0
      - name: startTime
        in: query
        description: Start time in microseconds
        required: false
        schema:
          type:
          - integer
          - 'null'
          format: int64
      - name: endTime
        in: query
        description: End time in microseconds
        required: false
        schema:
          type:
          - integer
          - 'null'
          format: int64
      - name: limit
        in: query
        description: Number of results (default 500, max 1000)
        required: false
        schema:
          type:
          - integer
          - 'null'
          minimum: 0
      responses:
        '200':
          description: List of all orders
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedResponse_HistoricalOrder'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '404':
          description: Market not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '502':
          description: Upstream service unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '503':
          description: Historical data service unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
  /fapi/v1/userDeposits:
    get:
      tags:
      - User Data (Beta)
      summary: User Deposit History
      operationId: user_deposits
      parameters:
      - name: address
        in: query
        description: Account address (required on first request, encoded in cursor for subsequent)
        required: false
        schema:
          type:
          - string
          - 'null'
      - name: startTime
        in: query
        description: Start time in microseconds
        required: false
        schema:
          type:
          - integer
          - 'null'
          format: int64
      - name: endTime
        in: query
        description: End time in microseconds
        required: false
        schema:
          type:
          - integer
          - 'null'
          format: int64
      - name: limit
        in: query
        description: Number of results (default 500, max 1000)
        required: false
        schema:
          type:
          - integer
          - 'null'
          minimum: 0
      responses:
        '200':
          description: List of user deposits
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedResponse_UserDeposit'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '502':
          description: Upstream service unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '503':
          description: Historical data service unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
  /fapi/v1/userFundingPayments:
    get:
      tags:
      - User Data (Beta)
      summary: User Funding Payment History
      operationId: user_funding_payments
      parameters:
      - name: address
        in: query
        description: Account address (required on first request, encoded in cursor for subsequent)
        required: false
        schema:
          type:
          - string
          - 'null'
      - name: symbol
        in: query
        description: Trading pair symbol (optional filter)
        required: false
        schema:
          type:
          - string
          - 'null'
      - name: startTime
        in: query
        description: Start time in microseconds (optional filter)
        required: false
        schema:
          type:
          - integer
          - 'null'
          format: int64
      - name: endTime
        in: query
        description: End time in microseconds (optional filter)
        required: false
        schema:
          type:
          - integer
          - 'null'
          format: int64
      - name: limit
        in: query
        description: Number of results (default 500, max 1000)
        required: false
        schema:
          type:
          - integer
          - 'null'
          minimum: 0
      responses:
        '200':
          description: List of user funding payments
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedResponse_UserFundingPayment'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '404':
          description: Market not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '502':
          description: Upstream service unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '503':
          description: Historical data service unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
  /fapi/v1/userLiquidations:
    get:
      tags:
      - User Data (Beta)
      summary: User Liquidation History
      operationId: user_liquidations
      parameters:
      - name: address
        in: query
        description: Account address (required on first request, encoded in cursor for subsequent)
        required: false
        schema:
          type:
          - string
          - 'null'
      - name: symbol
        in: query
        description: Trading pair symbol (optional filter)
        required: false
        schema:
          type:
          - string
          - 'null'
      - name: startTime
        in: query
        description: Start time in microseconds (optional filter)
        required: false
        schema:
          type:
          - integer
          - 'null'
          format: int64
      - name: endTime
        in: query
        description: End time in microseconds (optional filter)
        required: false
        schema:
          type:
          - integer
          - 'null'
          format: int64
      - name: limit
        in: query
        description: Number of results (default 500, max 1000)
        required: false
        schema:
          type:
          - integer
          - 'null'
          minimum: 0
      responses:
        '200':
          description: List of user liquidations
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedResponse_UserLiquidation'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '404':
          description: Market not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '502':
          description: Upstream service unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '503':
          description: Historical data service unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
  /fapi/v1/userTrades:
    get:
      tags:
      - User Data (Beta)
      summary: Account Trade List
      operationId: user_trades
      parameters:
      - name: address
        in: query
        description: Account address (required on first request, encoded in cursor for subsequent)
        required: false
        schema:
          type:
          - string
          - 'null'
      - name: symbol
        in: query
        description: Trading pair symbol (optional filter)
        required: false
        schema:
          type:
          - string
          - 'null'
      - name: startTime
        in: query
        description: Start time in microseconds (optional filter)
        required: false
        schema:
          type:
          - integer
          - 'null'
          format: int64
      - name: endTime
        in: query
        description: End time in microseconds (optional filter)
        required: false
        schema:
          type:
          - integer
          - 'null'
          format: int64
      - name: limit
        in: query
        description: Number of results (default 500, max 1000)
        required: false
        schema:
          type:
          - integer
          - 'null'
          minimum: 0
      responses:
        '200':
          description: List of account trades
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedResponse_UserTrade'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '404':
          description: Market not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '502':
          description: Upstream service unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '503':
          description: Historical data service unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
  /fapi/v1/userWithdrawals:
    get:
      tags:
      - User Data (Beta)
      summary: User Withdrawal History
      operationId: user_withdrawals
      parameters:
      - name: address
        in: query
        description: Account address (required on first request, encoded in cursor for subsequent)
        required: false
        schema:
          type:
          - string
          - 'null'
      - name: startTime
        in: query
        description: Start time in microseconds
        required: false
        schema:
          type:
          - integer
          - 'null'
          format: int64
      - name: endTime
        in: query
        description: End time in microseconds
        required: false
        schema:
          type:
          - integer
          - 'null'
          format: int64
      - name: limit
        in: query
        description: Number of results (default 500, max 1000)
        required: false
        schema:
          type:
          - integer
          - 'null'
          minimum: 0
      responses:
        '200':
          description: List of user withdrawals
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedResponse_UserWithdrawal'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '502':
          description: Upstream service unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '503':
          description: Historical data service unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
components:
  schemas:
    PaginatedResponse_UserDeposit:
      type: object
      description: paginated response wrapper with optional cursor for next page
      required:
      - data
      properties:
        data:
          type: array
          items:
            type: object
            required:
            - asset
            - assetId
            - amount
            - amountNotional
            - txHash
            - eventNumber
            - time
            properties:
              amount:
                type: string
                format: decimal
              amountNotional:
                type: string
                format: decimal
              asset:
                type: string
              assetId:
                type: integer
                format: uint16
                minimum: 0
              eventNumber:
                type: integer
                format: uint64
                minimum: 0
              time:
                type: integer
                format: int64
              txHash:
                type: string
        nextCursor:
          type:
          - string
          - 'null'
    ApiErrorDetail:
      oneOf:
      - $ref: '#/components/schemas/JsonValidationErrorDetail'
      - type: object
      description: 'Typed details body. Variant order is important for untagged

        deserialization: keep the more-specific shape (`JsonValidation`)

        before more-permissive ones. `Upstream` holds the upstream payload

        verbatim (object, string, array, number, etc.) so pre-PR clients

        reading `details.error` (or `details` directly) keep working.'
    PaginatedResponse_UserLiquidation:
      type: object
      description: paginated response wrapper with optional cursor for next page
      required:
      - data
      properties:
        data:
          type: array
          items:
            type: object
            required:
            - symbol
            - liquidateeAddress
            - liquidatorAddress
            - marketId
            - markPrice
            - size
            - side
            - liquidatorReward
            - realizedPnl
            - txHash
            - eventNumber
            - time
            properties:
              eventNumber:
                type: integer
                format: uint64
                minimum: 0
              liquidateeAddress:
                type: string
              liquidatorAddress:
                type: string
              liquidatorReward:
                type: string
                format: decimal
              markPrice:
                type: string
                format: decimal
              marketId:
                type: integer
                format: uint16
                minimum: 0
              realizedPnl:
                type: string
                format: decimal
              side:
                type: string
              size:
                type: string
                format: decimal
              symbol:
                type: string
              time:
                type: integer
                format: int64
              txHash:
                type: string
        nextCursor:
          type:
          - string
          - 'null'
    PaginatedResponse_UserFundingPayment:
      type: object
      description: paginated response wrapper with optional cursor for next page
      required:
      - data
      properties:
        data:
          type: array
          items:
            type: object
            description: user funding payment history
            required:
            - symbol
            - marketId
            - fundingApplied
            - txHash
            - eventNumber
            - time
            properties:
              eventNumber:
                type: integer
                format: uint64
                minimum: 0
              fundingApplied:
                type: string
                format: decimal
              marketId:
                type: integer
                format: uint16
                minimum: 0
              symbol:
                type: string
              time:
                type: integer
                format: int64
              txHash:
                type: string
        nextCursor:
          type:
          - string
          - 'null'
    JsonValidationErrorDetail:
      type: object
      description: 'One JSON shape failure: machine-readable `rule` + full serde

        message including line/column. Surfaced under `details` on the wire.'
      required:
      - rule
      - message
      properties:
        message:
          type: string
          example: 'invalid type: integer `24500000`, expected a string at line 4 column 30'
        rule:
          type: string
          example: wrong_type
    PaginatedResponse_UserTrade:
      type: object
      description: paginated response wrapper with optional cursor for next page
      required:
      - data
      properties:
        data:
          type: array
          items:
            type: object
            required:
            - symbol
            - id
            - orderId
            - side
            - price
            - qty
            - quoteQty
            - realizedPnl
            - commission
            - commissionAsset
            - time
            - positionSide
            - buyer
            - maker
            - address
            - txHash
            properties:
              address:
                type: string
              buyer:
                type: boolean
              clientOrderId:
                type:
                - integer
                - 'null'
                format: uint64
                minimum: 0
              commission:
                type: string
                format: decimal
              commissionAsset:
                type: string
              id:
                type: integer
                format: uint64
                minimum: 0
              maker:
                type: boolean
              orderId:
                type: integer
                format: uint64
                minimum: 0
              positionSide:
                type: string
              price:
                type: string
                format: decimal
              qty:
                type: string
                format: decimal
              quoteQty:
                type: string
                format: decimal
              realizedPnl:
                type: string
                format: decimal
              side:
                type: string
              symbol:
                type: string
              time:
                type: integer
                format: int64
              txHash:
                type: string
        nextCursor:
          type:
          - string
          - 'null'
    PaginatedResponse_UserWithdrawal:
      type: object
      description: paginated response wrapper with optional cursor for next page
      required:
      - data
      properties:
        data:
          type: array
          items:
            type: object
            required:
            - asset
            - assetId
            - amount
            - amountNotional
            - fee
            - txHash
            - eventNumber
            - time
            properties:
              amount:
                type: string
                format: decimal
              amountNotional:
                type: string
                format: decimal
              asset:
                type: string
              assetId:
                type: integer
                format: uint16
                minimum: 0
              eventNumber:
                type: integer
                format: uint64
                minimum: 0
              fee:
                type: string
                format: decimal
              time:
                type: integer
                format: int64
              txHash:
                type: string
        nextCursor:
          type:
          - string
          - 'null'
    ApiErrorResponse:
      type: object
      description: 'Structured API error response matching Bullet API format.


        All error responses from the trading API conform to this schema.'
      required:
      - status
      - message
      properties:
        details:
          oneOf:
          - type: 'null'
          - $ref: '#/components/schemas/ApiErrorDetail'
            description: Structured per-failure details. Shape depends on the variant.
        error_id:
          type:
          - string
          - 'null'
          description: Error identifier for support.
          example: 8b2e4d9f-7a1c-4f0e-9c5d-3e6a8b1c2d4f
        message:
          type: string
          description: Human-readable error message.
          example: 'Transaction validation failed: insufficient funds'
        status:
          type: integer
          format: uint16
          description: HTTP status code.
          example: 400
          minimum: 0
    PaginatedResponse_HistoricalOrder:
      type: object
      description: paginated response wrapper with optional cursor for next page
      required:
      - data
      properties:
        data:
          type: array
          items:
            type: object
            description: historical order for /fapi/v1/allOrders
            required:
            - orderId
            - symbol
            - status
            - price
            - origQty
            - executedQty
            - avgPrice
            - side
            - type
            - time
            - updateTime
            - reduceOnly
            - closePosition
            - positionSide
            - txHashes
            properties:
              avgPrice:
                type: string
                format: decimal
              closePosition:
                type: boolean
              executedQty:
                type: string
                format: decimal
              orderId:
                type: integer
                format: uint64
                minimum: 0
              origQty:
                type: string
                format: decimal
              positionSide:
                type: string
              price:
                type: string
                format: decimal
              reduceOnly:
                type: boolean
              side:
                type: string
              status:
                type: string
                description: 'one of: NEW, PARTIALLY_FILLED, FILLED, CANCELED, EXPIRED'
              symbol:
                type: string
              time:
                type: integer
                format: int64
              txHashes:
                type: array
                items:
                  type: string
              type:
                type: string
              updateTime:
                type: integer
                format: int64
        nextCursor:
          type:
          - string
          - 'null'