Python SDK Guide

The official Python SDK provides Spot, Perps, user-flow, signing, and WebSocket clients. It handles canonical request serialization, EIP-712 signing, signature prefixes, and in-process nonce coordination.

GitHub: sodex-python-sdk-public

Requirements

• Python 3.9 or later

Installation

Install the reviewed 0.2.1 source revision directly from GitHub. This does not require or imply a PyPI release:

python -m pip install "git+https://github.com/sodex-tech/sodex-python-sdk-public.git@732ac02c0297e2b8ce65d23780cdab246c659d63"

Configuration

Client.from_env() uses mainnet by default. Select testnet explicitly when testing signed writes:

export SODEX_NETWORK=testnet
export SODEX_PRIVATE_KEY=0x...

For a registered API key, the private key belongs to the API key while the address and name identify its master account registration:

export SODEX_ACCOUNT_ADDRESS=0x...
export SODEX_API_KEY_NAME=my-bot

Public market data

Public reads do not require a private key:

from sodex.client import Client

client = Client.from_env()
print(client.perps_tickers("BTC-USD")[0])

Signed trading

The high-level client resolves the primary account and symbol identifiers, signs the request, and returns a typed receipt:

from decimal import Decimal

from sodex.client import Client

client = Client.from_env()
receipt = client.perps_order(
    "BTC-USD",
    True,
    Decimal("0.001"),
    limit_price=Decimal("50000"),
)

print(receipt.order_id)

The REST response confirms acceptance, not execution. Save order_id and use an account WebSocket subscription to track order updates and fills.

Account-level actions

API-key management and builder-fee approval must be signed by the master wallet. approve_builder_fee() applies the fee cap to both Spot and Perps:

import os

from sodex.client import Client

master = Client.from_private_key(
    os.environ["SODEX_PRIVATE_KEY"],
    testnet=True,
)
master.approve_builder_fee(
    builder_id=int(os.environ["SODEX_BUILDER_ID"]),
    max_fee_rate=int(os.environ["SODEX_BUILDER_FEE_RATE"]),
)

Builder fee rates use tenths of a basis point: 10 is 1 bp of the order notional, charged to the user and sent to the builder. The approval range is 0 through 2000; use 0 to clear the approval. Spot orders are capped at 2000 (2%) and Perps orders at 200 (0.2%). A user may have at most 10 builder approvals. See Builder Codes in Trading.

Builder-attributed orders

After the master wallet approves the builder on the target engine, include the builder in the signed order:

from decimal import Decimal
from sodex.client import BuilderParams, Client

client = Client.from_env()  # Set the network and registered API key explicitly.
receipt = client.perps_order(
    "BTC-USD",
    True,
    Decimal("0.001"),
    limit_price=Decimal("50000"),
    builder=BuilderParams(id=9, fee=20),
)
print(receipt.order_id)

Use your approved builder ID and an authorized rate; 20 means 2 bp. Spot supports batch attribution; Perps supports a batch default and per-order RawOrder(builder=...) overrides. Omitting the builder leaves it out of the signed payload. Approval on Spot and Perps is not an atomic update: inspect both engines after an ambiguous or partial result.

Discover funding routes

This example performs public reads only and explicitly selects mainnet:

from sodex.client import Client, Config

client = Client(Config(
    base_url="https://mainnet-gw.sodex.dev",
    chain_id=286623,
))
asset, chain = client.get_transfer_route("USDC", "BASE_ETH")
print(asset.coin, asset.decimals, asset.asset_id)
for name, method in (("custody", chain.custody), ("bridge", chain.bridge)):
    if method is None:
        continue
    print(name, "deposit:", method.allow_deposit, "withdraw:", method.allow_withdraw)
    if method.allow_withdraw:
        fee = method.withdraw_fee
        print("minimum:", method.min_withdraw_amount,
              "fee:", fee if fee not in (None, "") else "unknown")

The compatibility argument get_transfer_configs(coin=...) sends the REST filter name. Use chain.withdrawal_method("custody") or "bridge" to select and validate a withdrawal route. custody_available and bridge_available report deposit availability; they must not enable a withdrawal button. Use the selected method's minimum and fee fields instead of the legacy flattened chain minimums. Engine asset ID 0 is valid; nullable engine metadata must not be interpreted as a registered engine asset.

Account stream readiness

This example observes a configured account and places no orders. Set SODEX_NETWORK and SODEX_ACCOUNT_ADDRESS before running it:

import os
from sodex.client import Client as RestClient
from sodex.ws import Client as WebSocketClient

rest = RestClient.from_env()
ws = WebSocketClient.from_base_url(rest.base_url, engine="perps")
subscription = ws.subscribe_account(
    os.environ["SODEX_ACCOUNT_ADDRESS"],
    symbols=["BTC-USD"],
    on_order_update=lambda order: print(order.order_id, order.status),
    on_trade=lambda fill: print(fill.order_id, fill.trade_id, fill.price),
)
try:
    ws.connect()
    subscription.wait_ready(timeout=10)
    input("Subscription acknowledged; press Enter to close.\n")
finally:
    ws.close()

connect() starts background work and returns immediately. wait_ready() waits for subscription acknowledgements and raises on rejection or timeout; it does not establish that account state has been fully reconciled. Never call it from a reader callback. Use one WebSocket client per account owner. After reconnecting, readiness must be re-established and REST state/history must be reconciled; automatic resubscription does not replay missed fills.

Funding completion and recovery

wait_for_deposit() waits for indexing, not destination credit. wait_for_withdrawal() returns recognized terminal records, including failures. Engine transfer calls return acceptance; deposit_evm_to_engine() waits for EVM execution, not engine settlement. Persist identifiers and inspect the relevant outcome before starting a dependent transfer.

Data conventions

• Monetary values use Decimal.

• uint64 identifiers, nonces, and timestamps use Python int.

• Spot uses the spot EIP-712 domain; Perps uses futures; cross-engine user actions use universal.

• Reconcile remote state before retrying an ambiguous signed write with a new nonce.

More examples

See the GitHub examples for account queries, orders, WebSocket streams, deposits, transfers, withdrawals, API-key management, and builder-fee approval.

Related documentation

• REST API

• WebSocket Streams

• Rate Limits