openapi: 3.1.0
info:
  title: Bullet Trading Account Rollup 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: Rollup
paths:
  /rollup/constants:
    get:
      summary: Get the rollup constants.
      operationId: constants
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RollupConstants'
        '503':
          description: Constants not available
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
      tags:
      - Rollup
  /rollup/schema:
    get:
      summary: Get the rollup schema (unwrapped).
      operationId: schema
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
        '503':
          description: Schema not available
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
      tags:
      - Rollup
  /rollup/simulate:
    post:
      summary: Simulate a transaction against the current rollup state without committing.
      description: 'Pass-through proxy to the sequencer''s `/rollup/simulate`. The body is a JSON

        `SimulateParameters` document (runtime `call` + `sender`), NOT a signed borsh

        tx, so this route intentionally skips the tx validators and forwards the

        request unchanged — mirroring the rest of the `/rollup/*` passthrough.'
      operationId: simulate
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SimulateParameters'
        required: true
      responses:
        '200':
          description: Simulation completed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimulateOutcome'
        '400':
          description: Invalid simulation request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '422':
          description: Simulation request failed validation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '500':
          description: Simulation failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '502':
          description: Upstream service unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
      tags:
      - Rollup
components:
  schemas:
    RollupConstants:
      type: object
      description: Response from the `/rollup/constants` endpoint.
      required:
      - chain_id
      - chain_name
      - gas_token_id
      - hyperlane_domain
      - address_prefix
      properties:
        address_prefix:
          type: string
        chain_id:
          type: integer
          format: uint64
          minimum: 0
        chain_name:
          type: string
        gas_token_id:
          type: string
        hyperlane_domain:
          type: integer
          format: uint64
          minimum: 0
    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.'
    FailOutcome:
      type: object
      description: Skipped simulation outcome.
      required:
      - reason
      properties:
        reason:
          type: string
          description: The reason the transaction was skipped
    SimulateOutcome:
      oneOf:
      - allOf:
        - $ref: '#/components/schemas/SuccessOutcome'
          description: The transaction executed successfully.
        - type: object
          required:
          - outcome
          properties:
            outcome:
              type: string
              enum:
              - success
        description: The transaction executed successfully.
      - allOf:
        - $ref: '#/components/schemas/RevertOutcome'
          description: The transaction reverted during execution.
        - type: object
          required:
          - outcome
          properties:
            outcome:
              type: string
              enum:
              - reverted
        description: The transaction reverted during execution.
      - allOf:
        - $ref: '#/components/schemas/FailOutcome'
          description: The transaction was skipped due to pre-execution errors.
        - type: object
          required:
          - outcome
          properties:
            outcome:
              type: string
              enum:
              - skipped
        description: The transaction was skipped due to pre-execution errors.
      description: 'Outcome of a transaction simulation.


        Discriminated on `outcome`, mirroring the sequencer''s `SimulateOutcome`

        (`sov-rollup-apis`): `success` / `reverted` / `skipped`.'
    TxDetailsParameter:
      type: object
      description: Optional transaction details for a simulation request.
      properties:
        gas_limit:
          type: array
          items:
            type: integer
            format: int64
            minimum: 0
          description: Gas limit for the transaction, as an array of u64 values
        max_fee:
          type: string
          description: Maximum fee the sender is willing to pay
        max_priority_fee_bips:
          type: integer
          format: uint64
          description: Maximum priority fee in basis points
          minimum: 0
    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
    SuccessOutcome:
      type: object
      description: Successful simulation outcome.
      required:
      - gas_used
      - priority_fee
      - events
      properties:
        events:
          type: array
          items:
            $ref: '#/components/schemas/SimulatedEvent'
          description: Events emitted during execution
        gas_used:
          type: string
          description: Gas consumed by the transaction (gas-token amount, as a decimal string)
        priority_fee:
          type: string
          description: Priority fee paid (gas-token amount, as a decimal string)
    SequencerParameter:
      type: object
      description: Optional sequencer configuration for a simulation request.
      properties:
        da_address:
          type: string
          description: Custom data availability address for the sequencer
        rollup_address:
          type: string
          description: Custom rollup address for the sequencer
    RevertOutcome:
      type: object
      description: Reverted simulation outcome.
      required:
      - detail
      properties:
        detail:
          type: object
          description: Structured detail about the revert (`ErrorContext`, an arbitrary JSON object)
    SimulateParameters:
      type: object
      description: 'Parameters for a transaction simulation request.


        Mirrors the sequencer''s `SimulateParameters`. Documentation-only: like

        `/tx/submit`, the handler forwards the raw body, so this type is not

        deserialized in-process.'
      required:
      - sender
      - call
      properties:
        call:
          type: object
          description: The runtime call to simulate, provided as JSON
        sender:
          type: string
          description: The credential ID of the transaction sender
        sequencer:
          $ref: '#/components/schemas/SequencerParameter'
          description: Optional sequencer configuration
        tx_details:
          $ref: '#/components/schemas/TxDetailsParameter'
          description: Optional transaction details (gas limit, fees)
        uniqueness:
          type: object
          description: Optional uniqueness data for the transaction
    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
    SimulatedEvent:
      type: object
      description: An event emitted during transaction simulation.
      required:
      - value
      - key
      - module
      properties:
        key:
          type: string
          description: The event key
        module:
          type: string
          description: The module that emitted the event
        value:
          type: object
          description: The event data (arbitrary JSON)