Paradex WebSocket API
JSON-RPC over WebSocket channels for real-time market data, order book, trades, fills, orders, positions and account updates.
Work with this as data
Every API here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for apis
7 MCP tools reach this
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
Call it yourself
curl for this page
This API
curl "https://apis.io/api/v1/apis/paradex:paradex-websocket-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
AsyncAPI Specification
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