Paradex Python SDK¶
Warning
Experimental SDK, library API is subject to change
paradex_py.paradex.Paradex
¶
Bases: _ClientBase
Paradex class to interact with Paradex REST API.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
env |
Environment
|
Environment |
required |
l1_address |
str
|
L1 address. Defaults to None. |
None
|
l1_private_key |
str
|
L1 private key. Defaults to None. |
None
|
l1_private_key_from_ledger |
bool
|
Derive L2 key from Ledger hardware wallet. Defaults to False. |
False
|
l2_private_key |
str
|
L2 private key. Defaults to None. |
None
|
logger |
Logger
|
Logger. Defaults to None. |
None
|
ws_timeout |
int
|
WebSocket read timeout in seconds. Defaults to None (uses default). |
None
|
http_client |
HttpClient
|
Custom HTTP client for injection. Defaults to None. |
None
|
api_base_url |
str
|
Custom API base URL override. Defaults to None. |
None
|
default_timeout |
float
|
Default HTTP request timeout in seconds. Defaults to None. |
None
|
retry_strategy |
RetryStrategy
|
Custom retry/backoff strategy. Defaults to DefaultRetryStrategy (rate-limit-aware retries). Pass None to disable retries. |
_UNSET
|
request_hook |
RequestHook
|
Hook for request/response observability. Defaults to None. |
None
|
enable_http_compression |
bool
|
Enable HTTP compression (gzip, deflate, br). Defaults to True. |
True
|
auto_start_ws_reader |
bool
|
Whether to automatically start WS message reader. Defaults to True. |
True
|
ws_connector |
WebSocketConnector
|
Custom WebSocket connector for injection. Defaults to None. |
None
|
ws_url_override |
str
|
Custom public WebSocket URL override. Defaults to None. |
None
|
ws_direct_url_override |
str
|
Custom direct (authenticated) WebSocket URL override. Defaults to None. |
None
|
ws_reader_sleep_on_error |
float
|
WebSocket reader sleep duration after errors. Defaults to 1.0. |
1.0
|
ws_reader_sleep_on_no_connection |
float
|
WebSocket reader sleep when no connection. Defaults to 1.0. |
1.0
|
validate_ws_messages |
bool
|
Enable JSON-RPC message validation. Defaults to False. |
False
|
ping_interval |
float
|
WebSocket ping interval in seconds. Defaults to None. |
None
|
disable_reconnect |
bool
|
Disable automatic WebSocket reconnection. Defaults to False. |
False
|
enable_ws_compression |
bool
|
Enable WebSocket per-message compression (RFC 7692). Defaults to True. |
True
|
ws_sbe_enabled |
bool
|
Enable SBE binary encoding on the WebSocket connection. Defaults to False. |
False
|
auto_auth |
bool
|
Whether to automatically handle onboarding/auth. Defaults to True. |
True
|
auth_provider |
AuthProvider
|
Custom authentication provider. Defaults to None. |
None
|
auth_params |
dict
|
Extra query parameters sent with every |
None
|
signer |
Signer
|
Custom order signer for submit/modify/batch operations. Defaults to None. |
None
|
rpc_version |
str
|
RPC version (e.g., "v0_9"). If provided, constructs URL as {base_url}/rpc/{rpc_version}. Defaults to None. |
None
|
config |
SystemConfig
|
System configuration. If provided, uses this config instead of fetching from API. Defaults to None. |
None
|
Examples:
>>> from paradex_py import Paradex
>>> from paradex_py.environment import Environment
>>> paradex = Paradex(env=Environment.TESTNET)
>>> # With custom timeout
>>> paradex = Paradex(env=Environment.TESTNET, ws_timeout=30)
>>> # With simulator-friendly injection (high-frequency, no sleeps)
>>> paradex = Paradex(env=Environment.TESTNET, auto_start_ws_reader=False,
... http_client=custom_client, ws_connector=custom_connector,
... ws_reader_sleep_on_error=0, ws_reader_sleep_on_no_connection=0)
auth_level: AuthLevel
property
¶
Reflects the current authentication state.
Returns AuthLevel.FULL when an account is initialized, AuthLevel.AUTHENTICATED
when only an auth_provider is set (token present, no signing key), or
AuthLevel.UNAUTHENTICATED when neither is available.
Paradex can be constructed without keys and initialized later via
init_account(), so this property reflects the current state.
can_trade: bool
property
¶
True when account is initialized — L2 key is available for signing.
can_withdraw: bool
property
¶
True when account is initialized — full account key, all on-chain operations
available (deposit, withdraw, transfer).
is_authenticated: bool
property
¶
True when an account is initialized or an auth_provider is set.
__init__(env, l1_address=None, l1_private_key=None, l1_private_key_from_ledger=False, l2_private_key=None, logger=None, ws_timeout=None, http_client=None, api_base_url=None, default_timeout=None, retry_strategy=_UNSET, request_hook=None, enable_http_compression=True, auto_start_ws_reader=True, ws_connector=None, ws_url_override=None, ws_direct_url_override=None, ws_reader_sleep_on_error=1.0, ws_reader_sleep_on_no_connection=1.0, validate_ws_messages=False, ping_interval=None, disable_reconnect=False, enable_ws_compression=True, ws_sbe_enabled=False, auto_auth=True, auth_provider=None, auth_params=None, signer=None, rpc_version=None, config=None)
¶
init_account(l1_address, l1_private_key=None, l1_private_key_from_ledger=False, l2_private_key=None, rpc_version=None)
¶
Initialize paradex account with l1 or l2 private keys. Cannot be called if account is already initialized.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
l1_address |
str
|
L1 address |
required |
l1_private_key |
str
|
L1 private key |
None
|
l1_private_key_from_ledger |
bool
|
Derive L2 key from Ledger hardware wallet. Defaults to False. |
False
|
l2_private_key |
str
|
L2 private key |
None
|
rpc_version |
str
|
RPC version (e.g., "v0_9"). If provided, constructs URL as {base_url}/rpc/{rpc_version}. Defaults to None. |
None
|
L2-Only Authentication (Subkeys)¶
For users who only have L2 credentials (subkeys) and don't need L1 onboarding:
paradex_py.paradex_subkey.ParadexSubkey
¶
Bases: ParadexL2
Registered subkey authentication — trade-scoped subclass of ParadexL2 with trade-scoped capabilities (no withdrawals).
Subkeys are registered signing keys scoped to order management only.
Use ParadexL2 directly when authenticating with a main account key.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
env |
Environment
|
Environment |
required |
l2_private_key |
str
|
The subkey's L2 private key (required) |
required |
l2_address |
str
|
The main account address this subkey is registered under. This is not the subkey's own derived address — it must be the address of the parent account that registered this subkey. |
required |
logger |
Logger
|
Logger. Defaults to None. |
None
|
ws_timeout |
int
|
WebSocket read timeout in seconds. Defaults to None. |
None
|
ws_enabled |
bool
|
Whether to create a WebSocket client. Defaults to True. |
True
|
Examples:
>>> from paradex_py import ParadexSubkey
>>> from paradex_py.environment import TESTNET
>>> paradex = ParadexSubkey(
... env=TESTNET,
... l2_private_key="0x<subkey-private-key>",
... l2_address="0x<main-account-address>", # parent account, not subkey address
... )
>>> paradex.can_trade
True
>>> paradex.can_withdraw
False
Usage Examples¶
L1 + L2 Authentication (Traditional):
from paradex_py import Paradex
from paradex_py.environment import Environment
# Requires both L1 and L2 credentials
paradex = Paradex(
env=Environment.TESTNET,
l1_address="0x...",
l1_private_key="0x..."
)
L2-Only Authentication (Subkeys):
from paradex_py import ParadexSubkey
from paradex_py.environment import Environment
# Only requires L2 credentials - no L1 needed
paradex = ParadexSubkey(
env=Environment.TESTNET,
l2_private_key="0x...",
l2_address="0x..."
)
# Use exactly like regular Paradex
await paradex.init_account() # Already initialized
markets = await paradex.api_client.get_markets()
WebSocket Usage:
async def on_message(ws_channel, message):
print(ws_channel, message)
await paradex.ws_client.connect()
await paradex.ws_client.subscribe(ParadexWebsocketChannel.MARKETS_SUMMARY, callback=on_message)
When to Use Each Approach¶
Use Paradex (L1 + L2) when:
- You have both L1 (Ethereum) and L2 (Starknet) credentials
- You have never logged in to Paradex using this account before
- You need to perform on-chain operations (transfers, withdrawals)
Use ParadexSubkey (L2-only) when:
- You only have L2 credentials
- The account has already been onboarded (You have logged in to Paradex before)
- You do not need on-chain operations (withdrawals, transfers)
Key Differences¶
| Feature | Paradex |
ParadexSubkey |
|---|---|---|
| Authentication | L1 + L2 | L2-only |
| Onboarding | ✅ Supported | ❌ Blocked |
| On-chain Operations | ✅ Supported | ❌ Blocked |
| API Access | ✅ Full access | ✅ Full access |
| WebSocket | ✅ Supported | ✅ Supported |
| Order Management | ✅ Supported | ✅ Supported |
API Documentation Links¶
Full details for REST API & WebSocket JSON-RPC API can be found at the following links:
paradex_py.api.api_client.ParadexApiClient
¶
Bases: BlockTradesMixin, HttpClient
Class to interact with Paradex REST API.
Initialized along with Paradex class.
After any REST call, rate limit info from the last response is available as
:attr:last_rate_limit (limit, remaining, reset, window from x-ratelimit-*
headers). Use it to back off before hitting 429 or to wait after one.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
env |
Environment
|
Environment |
required |
logger |
Logger
|
Logger. Defaults to None. |
None
|
http_client |
HttpClient
|
Custom HTTP client for injection. Defaults to None. |
None
|
api_base_url |
str
|
Custom base URL override. Defaults to None. |
None
|
auto_auth |
bool
|
Whether to automatically handle onboarding/auth. Defaults to True. |
True
|
auth_provider |
AuthProvider
|
Custom authentication provider. Defaults to None. |
None
|
signer |
Signer
|
Custom order signer for submit/modify/batch operations. Defaults to None. |
None
|
on_token_expired |
Callable[[], str | None]
|
Called when a manually-injected token
(set via |
None
|
auth_params |
dict
|
Extra query parameters sent with every |
None
|
Examples:
>>> from paradex_py import Paradex
>>> from paradex_py.environment import Environment
>>> paradex = Paradex(env=Environment.TESTNET)
activate_subkey(payload)
¶
Activate a pending subkey via Starknet signature. Private endpoint requires authorization.
The signature must be [r, s] over pedersen(timestamp, eph_public_key), produced by the main account's Starknet key.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
payload |
dict
|
ActivateSubkey fields — account_id, public_key, timestamp, signature, name. |
required |
Returns:
| Type | Description |
|---|---|
dict
|
ActivateSubkeyResponse dict (may include encrypted_key) |
auth_evm(params=None)
¶
Obtain a JWT for an EVM account via POST /v2/auth (SIWE).
cancel_algo_order(algo_order_id)
¶
Cancel an algo order. Private endpoint requires authorization.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
algo_order_id |
str
|
Algo order ID |
required |
cancel_all_orders(params=None)
¶
Cancel all open orders for specific market or for all markets. Private endpoint requires authorization.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
params |
dict | None
|
|
None
|
cancel_order(order_id)
¶
Cancel open order previously sent to Paradex from this account. Private endpoint requires authorization.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
order_id |
str
|
Order Id |
required |
cancel_order_by_client_id(client_id)
¶
Cancel open order previously sent to Paradex from this account. Private endpoint requires authorization.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
client_id |
str
|
Order id as assigned by a trader. |
required |
cancel_orders_batch(order_ids=None, client_order_ids=None)
¶
Cancel batch of orders by order IDs or client order IDs. Private endpoint requires authorization.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
order_ids |
list[str] | None
|
List of order IDs assigned by Paradex |
None
|
client_order_ids |
list[str] | None
|
List of client-assigned order IDs |
None
|
Returns:
| Name | Type | Description |
|---|---|---|
results |
list
|
List of cancellation results for each order |
create_subkey(payload)
¶
Register a new subkey for this account. Private endpoint requires authorization.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
payload |
dict
|
CreateSubkey fields — name, public_key, state ('active' or 'pending'), encrypted_key and eph_public_key (required when state='pending'). |
required |
Returns:
| Type | Description |
|---|---|
None
|
None (server responds with 204 No Content on success) |
create_token(payload)
¶
Create a new authentication token (JWT or API key). Private endpoint requires authorization.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
payload |
dict
|
CreateToken fields — name, token_type, expiry_duration (seconds). |
required |
Returns:
| Type | Description |
|---|---|
dict
|
ApiToken response dict |
fetch_account_info()
¶
Fetch profile for this account. Private endpoint requires authorization.
fetch_account_profile()
¶
Fetch profile for this account. Private endpoint requires authorization.
fetch_account_summary()
¶
Fetch current summary for this account. Private endpoint requires authorization.
fetch_algo_orders(params=None)
¶
Fetch algo orders for the account. Private endpoint requires authorization.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
params |
dict | None
|
|
None
|
Returns:
| Name | Type | Description |
|---|---|---|
results |
list
|
List of algo orders |
fetch_balances()
¶
Fetch all coin balances for this account. Private endpoint requires authorization.
Returns:
| Name | Type | Description |
|---|---|---|
results |
list
|
List of Balances |
fetch_bbo(market)
¶
Fetch best bid/offer for specific market.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
market |
str
|
Market Name |
required |
fetch_fills(params=None)
¶
Fetch history of fills for this account. Private endpoint requires authorization.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
params |
dict | None
|
|
None
|
Returns:
| Name | Type | Description |
|---|---|---|
next |
str
|
The pointer to fetch next set of records (null if there are no records left) |
prev |
str
|
The pointer to fetch previous set of records (null if there are no records left) |
results |
list
|
List of Fills |
fetch_funding_data(params=None)
¶
List historical funding data by market
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
params |
dict | None
|
|
None
|
Returns:
| Name | Type | Description |
|---|---|---|
next |
str
|
The pointer to fetch next set of records (null if there are no records left) |
prev |
str
|
The pointer to fetch previous set of records (null if there are no records left) |
results |
list
|
List of Funding Payments |
fetch_funding_payments(params=None)
¶
Fetch history of funding payments for this account. Private endpoint requires authorization.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
params |
dict | None
|
|
None
|
Returns:
| Name | Type | Description |
|---|---|---|
next |
str
|
The pointer to fetch next set of records (null if there are no records left) |
prev |
str
|
The pointer to fetch previous set of records (null if there are no records left) |
results |
list
|
List of Funding Payments |
fetch_insurance_fund()
¶
Fetch insurance fund information
fetch_klines(symbol, resolution, start_at, end_at, price_kind=None)
¶
Fetch OHLCV candlestick data for a symbol.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
symbol |
str
|
Symbol of the market pair |
required |
resolution |
str
|
Resolution in minutes: 1, 3, 5, 15, 30, 60 |
required |
start_at |
int
|
Start time for klines in milliseconds |
required |
end_at |
int
|
End time for klines in milliseconds |
required |
price_kind |
str | None
|
Which price to use for the klines (optional) |
None
|
Returns:
| Type | Description |
|---|---|
dict
|
List of OHLCV candlestick data |
fetch_liquidations(params=None)
¶
Fetch history of liquidations for this account. Private endpoint requires authorization.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
params |
dict | None
|
|
None
|
Returns:
| Name | Type | Description |
|---|---|---|
results |
list
|
List of Liquidations |
fetch_markets(params=None)
¶
Fetch all markets information.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
params |
dict | None
|
|
None
|
Returns:
| Name | Type | Description |
|---|---|---|
results |
list
|
List of Markets |
fetch_markets_summary(params=None)
¶
Fetch ticker information for specific market.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
params |
dict | None
|
|
None
|
Returns:
| Name | Type | Description |
|---|---|---|
results |
list
|
List of Market Summaries |
fetch_onboarding(params=None)
¶
Check whether an account has been onboarded.
Public endpoint — no authentication required.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
params |
dict | None
|
Query parameters. Exactly one of two forms: Starknet account (
EVM account (
Note: |
None
|
Returns:
| Type | Description |
|---|---|
dict
|
dict with |
dict
|
|
fetch_order(order_id)
¶
Fetch a state of specific order sent from this account. Private endpoint requires authorization.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
order_id |
str
|
order's id as assigned by Paradex. |
required |
fetch_order_by_client_id(client_id)
¶
Fetch a state of specific order sent from this account. Private endpoint requires authorization.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
client_id |
str
|
order's client_id as assigned by a trader. |
required |
fetch_orderbook(market, params=None)
¶
Fetch order-book for specific market.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
market |
str
|
Market Name |
required |
params |
dict | None
|
|
None
|
fetch_orders(params=None)
¶
Fetch open orders for the account. Private endpoint requires authorization.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
params |
dict | None
|
|
None
|
Returns:
| Name | Type | Description |
|---|---|---|
results |
list
|
Orders list |
fetch_orders_history(params=None)
¶
Fetch history of orders for the account. Private endpoint requires authorization.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
params |
dict | None
|
|
None
|
Returns:
| Name | Type | Description |
|---|---|---|
next |
str
|
The pointer to fetch next set of records (null if there are no records left) |
prev |
str
|
The pointer to fetch previous set of records (null if there are no records left) |
results |
list
|
List of Orders |
fetch_points_data(market, program)
¶
Fetch points program data for specific market. Private endpoint requires authorization.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
market |
str
|
Market Name |
required |
program |
str
|
Program Name - example: Maker, Fee |
required |
Returns:
| Name | Type | Description |
|---|---|---|
results |
list
|
List of points data |
fetch_positions()
¶
Fetch all derivatives positions for this account. Private endpoint requires authorization.
Returns:
| Name | Type | Description |
|---|---|---|
next |
str
|
The pointer to fetch next set of records (null if there are no records left) |
prev |
str
|
The pointer to fetch previous set of records (null if there are no records left) |
results |
list
|
List of Positions |
fetch_subaccounts()
¶
Fetch list of sub-accounts for this account. Private endpoint requires authorization.
fetch_subkey(public_key)
¶
Fetch a specific subkey by its public key. Private endpoint requires authorization.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
public_key |
str
|
Public key of the subkey to fetch. |
required |
fetch_subkeys(params=None)
¶
List all subkeys for this account. Private endpoint requires authorization.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
params |
dict | None
|
|
None
|
Returns:
| Name | Type | Description |
|---|---|---|
results |
list
|
List of Subkeys |
fetch_system_config()
¶
Fetch Paradex system config.
Examples:
>>> paradex.api_client.fetch_system_config()
>>> { ..., "paraclear_decimals": 8, ... }
fetch_system_state()
¶
Fetch Paradex system status.
Examples:
>>> paradex.api_client.fetch_system_state()
>>> { "status": "ok" }
fetch_system_time()
¶
Fetch Paradex system time.
Examples:
>>> paradex.api_client.fetch_system_time()
>>> { "server_time": "1710956478221" }
Returns:
| Name | Type | Description |
|---|---|---|
server_time |
dict
|
Paradex Server time |
fetch_tokens(params=None)
¶
List authentication tokens for this account. Private endpoint requires authorization.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
params |
dict | None
|
|
None
|
Returns:
| Name | Type | Description |
|---|---|---|
results |
list
|
List of ApiToken entries |
fetch_tradebusts(params=None)
¶
Fetch history of tradebusts for this account.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
params |
dict | None
|
|
None
|
Returns:
| Name | Type | Description |
|---|---|---|
next |
str
|
The pointer to fetch next set of records (null if there are no records left) |
prev |
str
|
The pointer to fetch previous set of records (null if there are no records left) |
results |
list
|
List of Tradebusts |
fetch_trades(params)
¶
Fetch Paradex exchange trades for specific market.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
params |
dict
|
|
required |
Returns:
| Name | Type | Description |
|---|---|---|
next |
str
|
The pointer to fetch next set of records (null if there are no records left) |
prev |
str
|
The pointer to fetch previous set of records (null if there are no records left) |
results |
list
|
List of Trades |
fetch_transactions(params=None)
¶
Fetch history of transactions initiated by this account. Private endpoint requires authorization.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
params |
dict | None
|
|
None
|
Returns:
| Name | Type | Description |
|---|---|---|
next |
str
|
The pointer to fetch next set of records (null if there are no records left) |
prev |
str
|
The pointer to fetch previous set of records (null if there are no records left) |
results |
list
|
List of Transactions |
fetch_transfers(params=None)
¶
Fetch history of transfers initiated by this account. Private endpoint requires authorization.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
params |
dict | None
|
|
None
|
Returns:
| Name | Type | Description |
|---|---|---|
next |
str
|
The pointer to fetch next set of records (null if there are no records left) |
prev |
str
|
The pointer to fetch previous set of records (null if there are no records left) |
results |
list
|
List of Transfers |
init_account_evm(account)
¶
Initialize an EVM account and run the v2 onboarding/auth flow.
modify_order(order_id, order, signer=None)
¶
Modify an open order previously sent to Paradex from this account. Private endpoint requires authorization.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
order_id |
str
|
Order Id |
required |
order |
Order
|
Order update |
required |
signer |
Signer | None
|
Optional custom signer. Uses instance signer or account signer if None. |
None
|
onboarding_evm()
¶
Onboard an EVM account via POST /v2/onboarding (SIWE).
revoke_subkey(public_key)
¶
Revoke a subkey permanently. Private endpoint requires authorization.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
public_key |
str
|
Public key of the subkey to revoke. |
required |
revoke_token(lookup_id)
¶
Revoke an authentication token by its lookup ID. Private endpoint requires authorization.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
lookup_id |
str
|
Lookup ID of the token to revoke. |
required |
set_token(jwt)
¶
Inject a JWT token directly, bypassing the standard onboarding/auth flow.
Used by ParadexApiKey to supply a pre-generated token, and also useful
for testing/simulation scenarios.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
jwt |
str
|
JWT token string |
required |
submit_algo_order(order, algo_type, duration_seconds, frequency=None, signer=None)
¶
Submit an algo order (e.g. TWAP) to Paradex. Private endpoint requires authorization.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
order |
Order
|
Order with type=MARKET, price=0, containing market/side/size. |
required |
algo_type |
str
|
Algo type (e.g. "TWAP"). |
required |
duration_seconds |
int
|
Duration in seconds (30-86400, multiple of 30). |
required |
frequency |
int | None
|
Interval in seconds between child orders (default: 30). |
None
|
signer |
Signer | None
|
Optional custom signer. Uses instance signer or account signer if None. |
None
|
Returns:
| Type | Description |
|---|---|
dict
|
Algo order response dict. |
submit_order(order, signer=None)
¶
Send order to Paradex. Private endpoint requires authorization.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
order |
Order
|
Order containing all required fields. |
required |
signer |
Signer | None
|
Optional custom signer. Uses instance signer or account signer if None. |
None
|
submit_orders_batch(orders, signer=None)
¶
Send batch of orders to Paradex. Private endpoint requires authorization.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
orders |
list[Order]
|
List of orders containing all required fields. |
required |
signer |
Signer | None
|
Optional custom signer. Uses instance signer or account signer if None. |
None
|
Returns:
| Name | Type | Description |
|---|---|---|
orders |
list
|
List of Orders |
errors |
list
|
List of Errors |
update_subkey(public_key, payload)
¶
Update a subkey (e.g. rename it). Private endpoint requires authorization.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
public_key |
str
|
Public key of the subkey to update. |
required |
payload |
dict
|
UpdateSubkey fields — name. |
required |
paradex_py.api.ws_client.ParadexWebsocketChannel
¶
Bases: Enum
Enum class to define the channels for Paradex Websocket API.
Attributes:
| Name | Type | Description |
|---|---|---|
ACCOUNT |
str
|
Private websocket channel for receiving updates of account status |
BALANCE_EVENTS |
str
|
Private websocket channel to receive PnL calculation data |
BBO |
str
|
Public websocket channel for tick updates of orderbook best bid/ask prices and amounts |
BLOCK_TRADES |
str
|
Private websocket channel to receive block trade updates |
FILLS |
str
|
Private websocket channel to receive details of fills for specific account |
FUNDING_DATA |
str
|
Public websocket channel to receive funding data updates |
FUNDING_PAYMENTS |
str
|
Private websocket channel to receive funding payments of an account |
MARKETS_SUMMARY |
str
|
Public websocket channel for updates of available markets |
ORDERS |
str
|
Private websocket channel to receive order updates |
ORDER_BOOK |
str
|
Public websocket channel for orderbook snapshot updates at most every 50ms or 100ms, optionally grouped by price tick (production only) |
POSITIONS |
str
|
Private websocket channel to receive updates when position is changed |
TRADES |
str
|
Public websocket channel to receive updates on trades in particular market |
TRADEBUSTS |
str
|
Private websocket channel to receive fills that are busted by a blockchain |
TRANSACTIONS |
str
|
Private websocket channel for receiving transaction details of fills |
TRANSFERS |
str
|
Websocket channel for receiving transfer updates |
paradex_py.api.ws_client.WsRpcError
¶
Bases: Exception
Raised when a WebSocket JSON-RPC response contains an error.
paradex_py.api.ws_client.ParadexWebsocketClient
¶
Class to interact with Paradex WebSocket JSON-RPC API.
Initialized along with Paradex class.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
env |
Environment
|
Environment |
required |
logger |
Optional[Logger]
|
Logger. Defaults to None. |
None
|
ws_timeout |
Optional[int]
|
WebSocket read timeout in seconds. Defaults to 20s. |
None
|
auto_start_reader |
bool
|
Whether to automatically start the message reader. Defaults to True. |
True
|
connector |
Optional[WebSocketConnector]
|
Custom WebSocket connector for injection. Defaults to None. |
None
|
ws_url_override |
Optional[str]
|
Custom WebSocket URL override. Defaults to None. |
None
|
reader_sleep_on_error |
float
|
Sleep duration after connection errors. Set to 0 for no sleep. Defaults to 1.0. |
1.0
|
reader_sleep_on_no_connection |
float
|
Sleep duration when no connection. Set to 0 for no sleep. Defaults to 1.0. |
1.0
|
validate_messages |
bool
|
Enable pydantic message validation. Requires pydantic. Defaults to False. |
False
|
ping_interval |
float
|
WebSocket ping interval in seconds. None uses websockets default. Defaults to None. |
None
|
disable_reconnect |
bool
|
Disable automatic reconnection for tight simulation control. Defaults to False. |
False
|
enable_compression |
bool
|
Enable WebSocket per-message compression (RFC 7692). Defaults to True. |
True
|
api_client |
Optional[Any]
|
Reference to ParadexApiClient for token refresh. Defaults to None. |
None
|
direct |
bool
|
Connect to the direct WebSocket endpoint
( |
False
|
Examples:
>>> from paradex_py import Paradex
>>> from paradex_py.environment import Environment
>>> paradex = Paradex(env=Environment.TESTNET)
>>> paradex.ws_client.connect()
>>> # With custom timeout
>>> from paradex_py.api.ws_client import ParadexWebsocketClient
>>> ws_client = ParadexWebsocketClient(env=Environment.TESTNET, ws_timeout=30)
>>> # With manual pumping disabled
>>> ws_client = ParadexWebsocketClient(env=Environment.TESTNET, auto_start_reader=False)
>>> # High-frequency simulator mode (no sleeps)
>>> ws_client = ParadexWebsocketClient(env=Environment.TESTNET,
... reader_sleep_on_error=0, reader_sleep_on_no_connection=0)
>>> # With typed message validation
>>> ws_client = ParadexWebsocketClient(env=Environment.TESTNET, validate_messages=True)
>>> # With API client for automatic token refresh on reconnect
>>> from paradex_py import Paradex
>>> paradex = Paradex(env=Environment.TESTNET, l1_address="0x...", l1_private_key="0x...")
>>> # WebSocket client automatically refreshes expired tokens when reconnecting
cancel_all_orders(market=None)
async
¶
Cancel all open orders over WebSocket (order.cancel_all).
Mirrors :meth:paradex_py.api.api_client.ParadexApiClient.cancel_all_orders.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
market |
str | None
|
If provided, cancel only orders in this market. |
None
|
Returns:
| Type | Description |
|---|---|
dict
|
Server result dict containing |
Raises:
| Type | Description |
|---|---|
WsRpcError
|
On server-side error. |
cancel_on_disconnect(enabled)
async
¶
Toggle Cancel-on-Disconnect for this WebSocket session (order.cancel_on_disconnect).
Off by default. Each new WebSocket session starts with CoD disabled.
Call cancel_on_disconnect(True) after connecting and authenticating to
arm it for the session.
When enabled, the server automatically cancels all orders that were submitted via this session if the WebSocket connection drops. The tracking set is managed entirely server-side and is scoped to the current connection — it resets on every reconnect, so re-enable CoD after each reconnect if needed.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
enabled |
bool
|
|
required |
Returns:
| Type | Description |
|---|---|
dict
|
Server result dict containing |
Raises:
| Type | Description |
|---|---|
WsRpcError
|
If the server rejects the request. |
Examples:
>>> async def main():
... paradex = Paradex(env=TESTNET, l1_address="0x...", l1_private_key="0x...")
... await paradex.ws_client.connect()
... # Arm cancel-on-disconnect for this session
... await paradex.ws_client.cancel_on_disconnect(True)
... # Orders submitted now will be cancelled if the connection drops
... order = Order(market="BTC-USD-PERP", ...)
... result = await paradex.ws_client.submit_order(order)
... # Disable CoD when no longer needed
... await paradex.ws_client.cancel_on_disconnect(False)
cancel_order(order_id)
async
¶
Cancel an order by ID over WebSocket (order.cancel).
Mirrors :meth:paradex_py.api.api_client.ParadexApiClient.cancel_order.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
order_id |
str
|
Paradex-assigned order ID. |
required |
Returns:
| Type | Description |
|---|---|
dict
|
Server result dict containing |
Raises:
| Type | Description |
|---|---|
WsRpcError
|
If the order cannot be cancelled. |
cancel_order_by_client_id(client_id, market)
async
¶
Cancel an order by client ID over WebSocket (order.cancel).
Mirrors :meth:paradex_py.api.api_client.ParadexApiClient.cancel_order_by_client_id.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
client_id |
str
|
Trader-assigned client order ID. |
required |
market |
str
|
Market the order belongs to (required by the server). |
required |
Returns:
| Type | Description |
|---|---|
dict
|
Server result dict containing |
Raises:
| Type | Description |
|---|---|
WsRpcError
|
If the order cannot be cancelled. |
cancel_orders_batch(order_ids)
async
¶
Cancel a batch of orders by ID over WebSocket (order.cancel_batch).
Mirrors :meth:paradex_py.api.api_client.ParadexApiClient.cancel_orders_batch.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
order_ids |
list[str]
|
List of Paradex-assigned order IDs to cancel. |
required |
Returns:
| Type | Description |
|---|---|
dict
|
Server result dict containing per-order cancellation outcomes. |
Raises:
| Type | Description |
|---|---|
WsRpcError
|
On server-side error. |
close()
async
¶
Close the WebSocket connection and clean up resources.
This method should be called when done using the WebSocket client to properly clean up connections and background tasks.
Examples:
>>> import asyncio
>>> from paradex_py.api.ws_client import ParadexWebsocketClient
>>> from paradex_py.environment import Environment
>>> async def main():
... ws_client = ParadexWebsocketClient(env=Environment.TESTNET)
... try:
... await ws_client.connect()
... # Use websocket client
... finally:
... await ws_client.close()
>>> asyncio.run(main())
connect()
async
¶
Connect to Paradex WebSocket API.
Returns:
| Name | Type | Description |
|---|---|---|
bool |
bool
|
True if connection is successful. |
Examples:
>>> from paradex_py import Paradex
>>> from paradex_py.environment import TESTNET
>>> async def main():
... paradex = Paradex(env=TESTNET)
... await paradex.ws_client.connect()
>>> import asyncio
>>> asyncio.run(main())
get_subscriptions()
¶
Get current subscription map.
Returns:
| Type | Description |
|---|---|
dict[str, bool]
|
Dictionary mapping channel names to subscription status |
inject(message)
async
¶
Inject a raw message string into the message processing pipeline.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
message |
str
|
Raw JSON string to process as if received from WebSocket. |
required |
modify_order(order_id, order, signer=None)
async
¶
Modify an open order over WebSocket (order.modify).
Mirrors :meth:paradex_py.api.api_client.ParadexApiClient.modify_order.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
order_id |
str
|
ID of the order to modify. |
required |
order |
Order
|
Order object carrying the updated fields and a fresh signature. |
required |
signer |
Signer | None
|
Optional custom signer. Falls back to the account signer. |
None
|
Returns:
| Type | Description |
|---|---|
dict
|
Server result dict containing the updated |
Raises:
| Type | Description |
|---|---|
WsRpcError
|
If the server rejects the modification. |
pump_once()
async
¶
Manually pump one message from the WebSocket connection.
Returns:
| Name | Type | Description |
|---|---|---|
bool |
bool
|
True if a message was processed, False if no message available or connection closed. |
pump_until(predicate, timeout_s=10.0)
async
¶
Deterministic consumption helper for simulators.
Pumps messages until predicate returns True or timeout is reached. Useful for waiting for specific message conditions in tests.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
predicate |
Callable[[dict], bool]
|
Function that takes a message dict and returns True to stop |
required |
timeout_s |
float
|
Maximum time to wait in seconds |
10.0
|
Returns:
| Type | Description |
|---|---|
int
|
Number of messages processed before predicate was satisfied or timeout |
Examples:
Wait for BBO message with specific price¶
count = await ws_client.pump_until( lambda msg: msg.get('params', {}).get('channel', '').startswith('bbo') and float(msg.get('data', {}).get('bid', 0)) > 50000, timeout_s=5.0 )
submit_order(order, signer=None)
async
¶
Create an order over WebSocket (order.create).
Mirrors :meth:paradex_py.api.api_client.ParadexApiClient.submit_order.
The connection must be authenticated before calling this method.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
order |
Order
|
Order to submit. |
required |
signer |
Signer | None
|
Optional custom signer. Falls back to the account signer. |
None
|
Returns:
| Type | Description |
|---|---|
dict
|
Server result dict containing |
Raises:
| Type | Description |
|---|---|
WsRpcError
|
If the server rejects the order. |
submit_orders_batch(orders, signer=None)
async
¶
Create a batch of orders over WebSocket (order.create_batch).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
orders |
list[Order]
|
Orders to submit. |
required |
signer |
Signer | None
|
Optional custom signer. Falls back to the account signer. |
None
|
Returns:
| Type | Description |
|---|---|
dict
|
Server result dict containing per-order outcomes. |
Raises:
| Type | Description |
|---|---|
WsRpcError
|
If the server rejects the batch. |
subscribe(channel, callback, params=None)
async
¶
Subscribe to a websocket channel with optional parameters. Callback function is invoked when a message is received.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
channel |
ParadexWebsocketChannel
|
Channel to subscribe |
required |
callback |
Callable
|
Callback function |
required |
params |
Optional[dict]
|
Parameters for the channel. Defaults to None. |
None
|
Examples:
from paradex_py import Paradex from paradex_py.environment import TESTNET from paradex_py.api.ws_client import ParadexWebsocketChannel, ParadexWebsocketClient async def main(): ... async def on_message(ws_channel, message): ... print(ws_channel, message) ... paradex = Paradex(env=TESTNET) ... await paradex.ws_client.connect() ... await paradex.ws_client.subscribe(ParadexWebsocketChannel.MARKETS_SUMMARY, callback=on_message) import asyncio asyncio.run(main())
subscribe_by_name(channel_name, callback=None)
async
¶
Subscribe to a channel by exact name string.
This is useful for simulation tooling where you want to subscribe to channels with exact names without using the enum formatting.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
channel_name |
str
|
Exact channel name (e.g., "bbo.BTC-USD-PERP") |
required |
callback |
Callable | None
|
Optional callback function. If provided, registers the callback. |
None
|
unsubscribe_by_name(channel_name)
async
¶
Unsubscribe from a channel by exact name string.
Symmetric with subscribe_by_name for complete channel lifecycle control.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
channel_name |
str
|
Exact channel name (e.g., "bbo.BTC-USD-PERP") |
required |
paradex_py.account.account.ParadexAccount
¶
Class to generate and manage Paradex account.
Initialized along with Paradex class.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
config |
SystemConfig
|
SystemConfig |
required |
l1_address |
str
|
Ethereum address |
required |
l1_private_key |
Optional[str]
|
Ethereum private key. Defaults to None. |
None
|
l2_private_key |
Optional[str]
|
Paradex private key. Defaults to None. |
None
|
rpc_version |
Optional[str]
|
RPC version (e.g., "v0_9"). If provided, constructs URL as {base_url}/rpc/{rpc_version}. Defaults to None. |
None
|
Examples:
>>> from paradex_py import Paradex
>>> from paradex_py.environment import Environment
>>> paradex = Paradex(env=Environment.TESTNET, l1_address="0x...", l1_private_key="0x...")
>>> paradex.account.l2_address
>>> paradex.account.l2_public_key
>>> paradex.account.l2_private_key
sign_block_offer(offer_data)
¶
Sign block offer data using Starknet account. Args: offer_data (dict): Block offer data containing offer details Returns: dict: Signed block offer data
sign_block_trade(block_trade_data)
¶
Sign block trade data using Starknet account. Args: block_trade_data (dict): Block trade data containing trade details Returns: dict: Signed block trade data
paradex_py.account.subkey_account.SubkeyAccount
¶
Bases: ParadexAccount
Subkey account for L2-only API authentication (no on-chain operations).
This account type is designed for subkey usage where only L2 credentials are available and no L1 onboarding is required.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
config |
SystemConfig
|
SystemConfig |
required |
l2_private_key |
str
|
L2 private key (required) |
required |
l2_address |
str
|
L2 address of the main account (required) |
required |
Examples:
>>> from paradex_py.account.subkey_account import SubkeyAccount
>>> from paradex_py.environment import Environment
>>> account = SubkeyAccount(
... config=config,
... l2_private_key="0x...",
... l2_address="0x..."
... )