Package baseline
| Property | Value |
|---|
| Distribution name | ddx-python |
| Import root | ddx |
| Python requirement | >=3.10 |
| Build backend | maturin |
| Rust extension module | ddx._rust |
| Source root in repo | rust-packages/ddx-python |
| Python package source | rust-packages/ddx-python/python |
Public scope of this reference
| Included in this page | Not covered here |
|---|
python/ddx client entrypoints, examples, runtime helpers, and endpoint-family map | devtools, fuzzing, notebooks, and broader contribution workflow docs |
Runtime configuration helpers
| Helper | Effect |
|---|
load_mainnet() | Sets CONTRACT_DEPLOYMENT=derivadex and reinitializes operator context |
load_testnet() | Sets CONTRACT_DEPLOYMENT=testnet and reinitializes operator context |
APP_CONFIG | If unset, the package initializes a bundled app-config path |
CONTRACT_DEPLOYMENT | Selects the deployment profile used by the package runtime |
Lifecycle contract
| Entry or rule | Effect |
|---|
async with DerivaDEXClient(...) | Opens the shared HTTP client, fetches deployment info, binds chain_id and verifying_contract, then connects the realtime client |
| Context-manager exit | Disconnects the realtime client and closes the shared HTTP client |
client.ws access rule | Before the first context-manager entry it raises a runtime error; after one context run the retained realtime client object still exists, but it has already been disconnected on exit |
| REST sub-clients | Lazily initialized on first property access and then reused for the life of the parent client |
Main client entrypoint
DerivaDEXClient is the primary high-level entrypoint.
| Constructor input | Purpose |
|---|
base_url | Base REST/webserver URL |
ws_url | Realtime WebSocket URL |
rpc_url | Ethereum RPC URL |
contract_deployment | Deployment selector used for chain/domain config |
private_key or mnemonic | Wallet credentials for signing and on-chain actions |
timeout and HTTP pool settings | HTTP client tuning |
Client accessors
| Accessor | Surface | Initialization rule |
|---|
client.market | Public market reads | Lazy |
client.trade | Strategy and trade-oriented reads | Lazy |
client.system | Deployment and system reads | Lazy |
client.signed | Signed and encrypted private request submission | Lazy; if created before context entry, chain and verifying-contract fields are backfilled on __aenter__() |
client.on_chain | On-chain approval, deposit, and confirmation flows | Lazy; if created before context entry, the verifying-contract field is backfilled on __aenter__() |
client.ws | Realtime WebSocket subscription and cached feed state | Intended for use inside the parent context manager; before first entry it is unavailable, and after exit the retained client object is disconnected |
REST family map
| Client family | Endpoint group |
|---|
system | exchange metadata, connectivity, server time, deployment info, and high-level stats/system reads |
trade | strategy, trader, positions, metrics, and fee history reads |
market | mark prices, order book history, update history, tickers, and aggregated market views |
signed | encryption-key retrieval plus encrypted /v2/request submission |
on_chain | proof and KYC-adjacent on-chain helper flows used by the client |
Signed client behavior
| Method or property | Purpose |
|---|
get_nonce() | Generates a 32-byte hex nonce for signable intents |
place_order() | Signs, encrypts, and submits one order intent |
place_orders() | Submits multiple order intents sequentially rather than as one protocol batch |
cancel_order() | Signs, encrypts, and submits one cancel intent |
cancel_all() | Cancels all matching open orders for the target scope |
withdraw() | Signs, encrypts, and submits one collateral-withdrawal intent |
update_profile() | Signs, encrypts, and submits one profile-update intent |
| encryption-key fetch | Lazily retrieves and caches the operator encryption key before the first private request |
On-chain client behavior
| Method | Purpose |
|---|
approve() | Approves ERC-20 collateral for the exchange contract |
deposit() | Fetches KYC authorization and deposits collateral into one strategy |
approve_ddx() | Approves DDX transfers for staking or governance-linked flows |
deposit_ddx() | Fetches KYC authorization and deposits DDX |
withdraw() | Fetches checkpoint and proof data, then submits an on-chain withdrawal |
Realtime client behavior
| Method or capability | Contract |
|---|
connect() / disconnect() | Opens or closes the WebSocket, manages the listener task, and clears pending acknowledgement futures on disconnect |
subscribe() / unsubscribe() | Sends raw control-plane payloads and awaits ACKNOWLEDGE |
subscribe_feeds() / unsubscribe_feeds() | Generates the nonce, manages callback registration, and raises on acknowledgement error |
| callback model | Per-feed sync or async callbacks can be registered and are merged into the client callback registry |
| cached state | Order-book, mark-price, and funding-rate state are cached inside the client |
| reconnect behavior | Active subscriptions are restored after reconnect through the internal resubscribe path |
Common example entrypoints
| Example | Purpose |
|---|
python/examples/rest_quickstart.py | Read strategy state, place an order, and cancel it |
python/examples/ws_quickstart.py | Subscribe to order book and mark price feeds |
python/examples/deposit_usdc.py | Approve USDC and deposit to a strategy |
python/examples/auditor.py | Run the on-chain/off-chain auditor loop |
Public source map
| Path | Role |
|---|
python/ddx/derivadex_client.py | High-level client entrypoint |
python/ddx/config.py | Deployment helper functions |
python/ddx/rest_client/clients/*.py | REST-family client implementations |
python/ddx/realtime_client/realtime_client.py | Realtime WebSocket client |
python/examples/*.py | Example workflows |
pyproject.toml | Package metadata, dependency baseline, and maturin config |
Last modified on April 13, 2026