WebSocket channels

asyncapi: 2.6.0
info:
    title: WebSocket channels
    version: 1.7.1
    description: |
        Channels for real-time updates.

        Public market data channels are delivered as SBE binary frames. Negotiate
        the encoding with the sbeSchemaId and sbeSchemaVersion query parameters:

            wss://ws.api.prod.paradex.trade/v1?sbeSchemaId=1&sbeSchemaVersion=1

        An unsupported schema or version is rejected with HTTP 400 at connect.

        Requests and control responses (subscribe, unsubscribe, auth, and their
        acknowledgements and errors) are always JSON-RPC text frames. Only channel
        payloads are binary, and they carry the same fields documented below.

        Generate a decoder from the schema at
        https://github.com/tradeparadex/paradex-py/blob/main/paradex_py/api/sbe/paradex_1_0.xml
        See https://docs.paradex.trade/ws/general-information/binary-encoding-sbe
servers:
    production:
        url: wss://ws.api.prod.paradex.trade/v1?sbeSchemaId=1&sbeSchemaVersion=1
        protocol: wss
        description: |
            Production WebSocket server. The SBE parameters select binary encoding
            for public channel payloads; omitting them is deprecated.
channels:
    /account:
        subscribe:
            summary: Private websocket channel for receiving updates of account status
            message:
                name: accountsummary
                title: AccountSummaryResponse
                payload:
                    $ref: '#/components/schemas/ResponsesAccountSummaryResponse'
                summary: Private websocket channel for receiving updates of account status
                description: |-
                    Subscribe to account messages
                    Authenticate the WebSocket session with the `auth` method before subscribing.
        x-fern-display-name: account
    /auth:
        publish:
            summary: Authenticate the WebSocket session
            description: Validates the JWT bearer token and associates the account with the connection. Must be called before subscribing to private channels or using order management methods.
            tags:
                - name: Session
            message:
                name: authrequest
                title: AuthRequest
                payload:
                    properties:
                        bearer:
                            description: JWT string obtained from POST /auth
                            example: eyJhbGci...
                            type: string
                    required:
                        - bearer
                    type: object
        subscribe:
            summary: auth response
            tags:
                - name: Session
            message:
                name: authresponse
                title: AuthResponse
                payload:
                    properties:
                        node_id:
                            description: Opaque server node identifier
                            type: string
                    type: object
        x-fern-display-name: auth
    /balance_events:
        subscribe:
            summary: Private websocket channel to receive PnL calculation data
            message:
                name: balanceevent
                title: BalanceEventResponse
                payload:
                    $ref: '#/components/schemas/ResponsesBalanceEventResponse'
                summary: Private websocket channel to receive PnL calculation data
                description: |-
                    Subscribe to balance event messages
                    Authenticate the WebSocket session with the `auth` method before subscribing.
        x-fern-display-name: balance_events
    /bbo.{market_symbol}:
        parameters:
            market_symbol:
                $ref: '#/components/parameters/market_symbol'
        subscribe:
            summary: Public websocket channel for tick updates of orderbook best bid/ask prices and amounts
            message:
                name: bboresp
                title: BBOResp
                payload:
                    $ref: '#/components/schemas/ResponsesBBOResp'
                summary: Public websocket channel for tick updates of orderbook best bid/ask prices and amounts
                description: 'Subscribe to market messages. Use `bbo.{market_symbol}` for a single market, `bbo.ALL` for every market, or pass `{"channel": "bbo", "base_asset": "{base_asset}"}` to receive updates for every active options market (OPTION and PERP_OPTION) for the given base asset.'
        x-fern-display-name: bbo.{market_symbol}
    /fills.{market_symbol}:
        parameters:
            market_symbol:
                $ref: '#/components/parameters/market_symbol'
        subscribe:
            summary: Private websocket channel to receive details of fills for specific account
            message:
                name: fillresult
                title: FillResult
                payload:
                    $ref: '#/components/schemas/ResponsesFillResult'
                summary: Private websocket channel to receive details of fills for specific account
                description: |-
                    Subscribe to fill messages for a market
                    Authenticate the WebSocket session with the `auth` method before subscribing.
        x-fern-display-name: fills.{market_symbol}
    /funding_data.{market_symbol}:
        parameters:
            market_symbol:
                $ref: '#/components/parameters/market_symbol'
        subscribe:
            summary: Public websocket channel to receive funding data updates
            message:
                name: fundingdataresult
                title: FundingDataResult
                payload:
                    $ref: '#/components/schemas/ResponsesFundingDataResult'
                summary: Public websocket channel to receive funding data updates
                description: Subscribe to funding data messages for a market
        x-fern-display-name: funding_data.{market_symbol}
    /funding_payments.{market_symbol}:
        parameters:
            market_symbol:
                $ref: '#/components/parameters/market_symbol'
        subscribe:
            summary: Private websocket channel to receive funding payments of an account
            message:
                name: fundingpayment
                title: FundingPayment
                payload:
                    $ref: '#/components/schemas/ResponsesFundingPayment'
                summary: Private websocket channel to receive funding payments of an account
                description: |-
                    Subscribe to funding payment messages for a market
                    Authenticate the WebSocket session with the `auth` method before subscribing.
        x-fern-display-name: funding_payments.{market_symbol}
    /markets[.{market_symbol}]:
        parameters:
            market_symbol:
                $ref: '#/components/parameters/market_symbol'
        subscribe:
            summary: Public websocket channel for live updates to market specifications
            message:
                name: marketevent
                title: MarketEvent
                payload:
                    $ref: '#/components/schemas/ResponsesMarketEvent'
                summary: Public websocket channel for live updates to market specifications
                description: 'Subscribe to market spec changes: new listings (CREATED), settlements (SETTLED), market removals (DELETED) and parameter updates (UPDATED — e.g. price tick size, position limits, margin params). Supports `markets` (all markets) and `markets.{market_symbol}` (specific market). Payload shape mirrors GET /markets/history.'
        x-fern-display-name: markets[.{market_symbol}]
    /markets_summary[.{market_symbol}]:
        parameters:
            market_symbol:
                $ref: '#/components/parameters/market_symbol'
        subscribe:
            summary: Public websocket channel for updates of available markets
            message:
                name: marketsummaryresp
                title: MarketSummaryResp
                payload:
                    $ref: '#/components/schemas/ResponsesMarketSummaryResp'
                summary: Public websocket channel for updates of available markets
                description: 'Subscribe to market summary messages for specific markets or all markets. Supports markets_summary (all markets) and markets_summary.{market_symbol} (specific market) dot-encoded patterns, plus a scoped mutable-filter mode: subscribe with a `markets` array (present, even empty) to filter to a specific set and change that set in place via modify_subscription without re-subscribing.'
        x-fern-display-name: markets_summary[.{market_symbol}]
    /mmp:
        subscribe:
            summary: Private websocket channel to receive market maker protection events
            message:
                name: mmpeventresp
                title: MmpEventResp
                payload:
                    $ref: '#/components/schemas/ResponsesMmpEventResp'
                summary: Private websocket channel to receive market maker protection events
                description: |-
                    Subscribe to `mmp` for market maker protection state changes on the authenticated account, one event per base asset.
                    TRIGGERED: a limit tripped. Open MMP orders on the base asset are cancelled with MMP_TRIGGERED, and new ones with MMP_FROZEN until `frozen_until`, or until a manual reset when it is 0. UNFROZEN and RESET end a freeze. CONFIG_UPDATED carries the new config.
                    Authenticate the WebSocket session with the `auth` method before subscribing.
        x-fern-display-name: mmp
    /modify_subscription:
        publish:
            summary: Modify a scoped subscription's market filter in place
            description: Adds and/or removes markets on a live scoped markets_summary subscription without unsubscribing and resubscribing, so markets that remain in the filter stream uninterrupted. Requires a subscription opened in scoped mode (subscribe with a markets array).
            tags:
                - name: Session
            message:
                name: modify_subscriptionrequest
                title: Modify_subscriptionRequest
                payload:
                    properties:
                        add:
                            description: Markets to add to the subscription's filter in place
                            example: SOL-USD-PERP
                            items:
                                type: string
                            type: array
                        channel:
                            description: Channel of the live scoped subscription to modify (e.g. markets_summary)
                            example: markets_summary
                            type: string
                        remove:
                            description: Markets to remove from the subscription's filter in place
                            example: BTC-USD-PERP
                            items:
                                type: string
                            type: array
                    required:
                        - channel
                    type: object
        subscribe:
            summary: modify_subscription response
            tags:
                - name: Session
            message:
                name: modify_subscriptionresponse
                title: Modify_subscriptionResponse
                payload:
                    properties:
                        add:
                            description: Markets that were added
                            items:
                                type: string
                            type: array
                        channel:
                            description: Channel whose subscription filter was modified
                            type: string
                        remove:
                            description: Markets that were removed
                            items:
                                type: string
                            type: array
                    type: object
        x-fern-display-name: modify_subscription
    /order.cancel:
        publish:
            summary: Cancel a single order
            description: Cancels an order by exchange order ID or by client_id + market. Either id or (client_id + market) must be provided.
            tags:
                - name: Order Management
            message:
                name: order.cancelrequest
                title: OrderCancelRequest
                payload:
                    properties:
                        client_id:
                            description: Client-assigned order ID; requires market when used
                            example: my-order-001
                            type: string
                        id:
                            description: Order ID to cancel; either id or client_id+market is required
                            example: "1234567890"
                            type: string
                        market:
                            description: Market symbol; required when cancelling by client_id
                            example: BTC-USD-PERP
                            type: string
                    type: object
        subscribe:
            summary: order.cancel response
            tags:
                - name: Order Management
            message:
                name: order.cancelresponse
                title: OrderCancelResponse
                payload:
                    properties:
                        order_id:
                            description: Cancelled order ID
                            example: "1234567890"
                            type: string
                        status:
                            description: Cancellation status
                            enum:
                                - QUEUED_FOR_CANCELLATION
                            example: QUEUED_FOR_CANCELLATION
                            type: string
                    type: object
        x-fern-display-name: order.cancel
    /order.cancel_all:
        publish:
            summary: Cancel all open orders
            description: Cancels all open orders for the authenticated account. If market is provided only orders in that market are cancelled.
            tags:
                - name: Order Management
            message:
                name: order.cancel_allrequest
                title: OrderCancel_allRequest
                payload:
                    properties:
                        market:
                            description: If set, only cancel orders in this market; omit to cancel all open orders
                            example: BTC-USD-PERP
                            type: string
                    type: object
        subscribe:
            summary: order.cancel_all response
            tags:
                - name: Order Management
            message:
                name: order.cancel_allresponse
                title: OrderCancel_allResponse
                payload:
                    properties:
                        status:
                            description: Always "ok"
                            example: ok
                            type: string
                    type: object
        x-fern-display-name: order.cancel_all
    /order.cancel_batch:
        publish:
            summary: Cancel multiple orders by ID
            description: Cancels a list of orders by their exchange IDs. Returns a per-order status; the request does not fail if individual orders are not found or already closed.
            tags:
                - name: Order Management
            message:
                name: order.cancel_batchrequest
                title: OrderCancel_batchRequest
                payload:
                    properties:
                        order_ids:
                            description: List of order IDs to cancel
                            example: '["111","222"]'
                            items:
                                type: string
                            type: array
                    required:
                        - order_ids
                    type: object
        subscribe:
            summary: order.cancel_batch response
            tags:
                - name: Order Management
            message:
                name: order.cancel_batchresponse
                title: OrderCancel_batchResponse
                payload:
                    properties:
                        results:
                            description: Per-order outcomes in the same order as order_ids
                            items:
                                properties:
                                    id:
                                        description: Order ID
                                        example: "1234567890"
                                        type: string
                                    market:
                                        description: Market symbol (absent when status is NOT_FOUND)
                                        example: BTC-USD-PERP
                                        type: string
                                    status:
                                        description: Outcome for this order
                                        enum:
                                            - QUEUED_FOR_CANCELLATION
                                            - ALREADY_CLOSED
                                            - NOT_FOUND
                                        type: string
                                type: object
                            type: array
                    type: object
        x-fern-display-name: order.cancel_batch
    /order.cancel_on_disconnect:
        publish:
            summary: Toggle Cancel on Disconnect (CoD)
            description: When enabled, all orders placed (or already tracked) during this connection are automatically cancelled if the WebSocket disconnects unexpectedly. CoD state is scoped to the connection and does not persist across reconnects.
            tags:
                - name: Order Management
            message:
                name: order.cancel_on_disconnectrequest
                title: OrderCancel_on_disconnectRequest
                payload:
                    properties:
                        enabled:
                            description: true to enable Cancel on Disconnect, false to disable
                            type: boolean
                    required:
                        - enabled
                    type: object
        subscribe:
            summary: order.cancel_on_disconnect response
            tags:
                - name: Order Management
            message:
                name: order.cancel_on_disconnectresponse
                title: OrderCancel_on_disconnectResponse
                payload:
                    properties:
                        enabled:
                            description: The new Cancel on Disconnect state for this connection
                            type: boolean
                    type: object
        x-fern-display-name: order.cancel_on_disconnect
    /order.create:
        publish:
            summary: Submit a new order
            description: Creates a single order. Requires authentication and a valid Starknet signature over the order payload. Rate limits are shared with the REST API (same Redis counters).
            tags:
                - name: Order Management
            message:
                name: order.createrequest
                title: OrderCreateRequest
                payload:
                    properties:
                        client_id:
                            description: Client-assigned order ID (max 64 chars)
                            example: my-order-001
                            type: string
                        flags:
                            description: Order flags. MMP is for LIMIT orders on dated options and perpetual futures; only resting maker fills count
                            items:
                                enum:
                                    - REDUCE_ONLY
                                    - MMP
                                type: string
                            type: array
                        instruction:
                            description: Time-in-force instruction
                            enum:
                                - GTC
                                - IOC
                                - POST_ONLY
                                - RPI
                            type: string
                        market:
                            description: Market symbol
                            example: BTC-USD-PERP
                            type: string
                        on_behalf_of_account:
                            description: Isolated margin account address for isolated margin orders
                            example: "0x1234567890abcdef"
                            type: string
                        price:
                            description: Limit price; use "0" for MARKET orders
                            example: "29500.00"
                            type: string
                        recv_window:
                            description: Max milliseconds between signature_timestamp and server receipt (min 10)
                            type: integer
                        side:
                            description: Order side
                            enum:
                                - BUY
                                - SELL
                            type: string
                        signature:
                            description: Starknet signature "[r,s]" over the order payload
                            example: '[r_value,s_value]'
                            type: string
                        signature_timestamp:
                            description: Unix timestamp in milliseconds used for signature verification
                            example: "1696291200000"
                            type: integer
                        size:
                            description: Order size (decimal string)
                            example: "0.01"
                            type: string
                        stp:
                            description: Self-trade prevention
                            enum:
                                - EXPIRE_MAKER
                                - EXPIRE_TAKER
                                - EXPIRE_BOTH
                            type: string
                        trigger_price:
                            description: Trigger price for stop orders
                            example: "29000.00"
                            type: string
                        type:
                            description: Order type
                            enum:
                                - LIMIT
                                - MARKET
                                - STOP_LIMIT
                                - STOP_MARKET
                            type: string
                    required:
                        - market
                        - side
                        - type
                        - size
                        - price
                        - instruction
                        - signature
                        - signature_timestamp
                    type: object
        subscribe:
            summary: order.create response
            tags:
                - name: Order Management
            message:
                name: order.createresponse
                title: OrderCreateResponse
                payload:
                    properties:
                        created_at:
                            description: Matching-engine timestamp in milliseconds
                            example: "1696291200000"
                            type: integer
                        order:
                            description: Created order
                            properties:
                                account:
                                    description: Account address that owns the order
                                    example: 0x4638e30...
                                    type: string
                                avg_fill_price:
                                    description: Volume-weighted average fill price; "0" if unfilled
                                    example: "0"
                                    type: string
                                cancel_reason:
                                    description: Reason for cancellation (populated when status=CLOSED)
                                    example: USER_CANCELED
                                    type: string
                                client_id:
                                    description: Client-assigned order ID
                                    example: my-order-001
                                    type: string
                                created_at:
                                    description: Order creation time in milliseconds
                                    example: "1696291200000"
                                    type: integer
                                flags:
                                    description: Order flags applied
                                    example: '["REDUCE_ONLY"]'
                                    items:
                                        type: string
                                    type: array
                                id:
                                    description: Unique order identifier assigned by exchange
                                    example: "1234567890"
                                    type: string
                                instruction:
                                    description: Time-in-force instruction
                                    enum:
                                        - GTC
                                        - IOC
                                        - POST_ONLY
                                        - RPI
                                    type: string
                                last_updated_at:
                                    description: Order last update time in milliseconds
                                    example: "1696291200000"
                                    type: integer
                                market:
                                    description: Market symbol
                                    example: BTC-USD-PERP
                                    type: string
                                price:
                                    description: Limit price
                                    example: "29500.00"
                                    type: string
                                published_at:
                                    description: Exchange publish time in milliseconds
                                    example: "1696291200000"
                                    type: integer
                                received_at:
                                    description: Exchange receipt time in milliseconds
                                    example: "1696291200000"
                                    type: integer
                                remaining_size:
                                    description: Remaining unfilled size
                                    example: "0.01"
                                    type: string
                                seq_no:
                                    description: Monotonically increasing sequence number for this order's updates
                                    example: "20784"
                                    type: integer
                                side:
                                    description: Order side
                                    enum:
                                        - BUY
                                        - SELL
                                    type: string
                                size:
                                    description: Order size
                                    example: "0.01"
                                    type: string
                                status:
                                    description: Order status
                                    enum:
                                        - NEW
                                        - OPEN
                                        - CLOSED
                                    type: string
                                timestamp:
                                    description: Signature timestamp supplied at creation
                                    example: "1696291200000"
                                    type: integer
                                trigger_price:
                                    description: Trigger price for stop orders
                                    example: "29000.00"
                                    type: string
                                type:
                                    description: Order type
                                    enum:
                                        - LIMIT
                                        - MARKET
                                        - STOP_LIMIT
                                        - STOP_MARKET
                                    type: string
                            type: object
                        received_at:
                            description: Server receipt timestamp in nanoseconds, recorded before any speedbump
                            example: "1696291200123456789"
                            type: integer
                    type: object
        x-fern-display-name: order.create
    /order.create_batch:
        publish:
            summary: Submit multiple orders in a single request
            description: Creates up to the configured maximum number of orders atomically. All signatures are validated before any orders reach the matching engine. Rate limit is consumed once for the entire batch.
            tags:
                - name: Order Management
            message:
                name: order.create_batchrequest
                title: OrderCreate_batchRequest
                payload:
                    properties:
                        orders:
                            description: Array of order create requests (max batch size enforced server-side)
                            items:
                                properties:
                                    client_id:
                                        description: Client-assigned order ID (max 64 chars)
                                        example: my-order-001
                                        type: string
                                    flags:
                                        description: Order flags. MMP is for LIMIT orders on dated options and perpetual futures; only resting maker fills count
                                        items:
                                            enum:
                                                - REDUCE_ONLY
                                                - MMP
                                            type: string
                                        type: array
                                    instruction:
                                        description: Time-in-force instruction
                                        enum:
                                            - GTC
                                            - IOC
                                            - POST_ONLY
                                            - RPI
                                        type: string
                                    market:
                                        description: Market symbol
                                        example: BTC-USD-PERP
                                        type: string
                                    on_behalf_of_account:
                                        description: Isolated margin account address for isolated margin orders
                                        example: "0x1234567890abcdef"
                                        type: strin

# --- truncated at 32 KB (142 KB total) ---
# Full source: https://artifacts.apis.io/paradex/asyncapi/paradex-websocket-asyncapi.yml