Documentation

Protocol semantics are documented by Derive and are not repeated here. Read them first, then come back for the Python bindings.

• Derive v3 documentation
• Quickstart and depositing
• Action signing, session keys and access scopes
• Migrating from v2, written to double as a SKILL.md for a coding agent
• llms.txt, an index of every page for agents
• Machine readable specs, which this client is generated from: openapi.json, websocket.asyncapi.json, subscriptions.asyncapi.json

Install

pip install derive-py

Python 3.11 or newer.

Configure

Configuration comes from the environment, or from a .env file in the working directory (default), or from a custom path. Keep private keys out of it: store them in an encrypted keystore and let .env name the keystore. A plaintext DERIVE_SESSION_KEY still works, for the shared testnet keys in .env.template, for unattended runs where a secrets manager injects it, and for existing setups. There is no password variable on purpose: a keystore whose password sits next to it in .env protects nothing.

All variables are optional:

from_env() takes a session_key_path if you would rather keep the key in a file than in the environment, and an env_file to point at a .env elsewhere. Without from_env(), HTTPClient(ClientConfig(chain=Chain.ETHEREUM)) is a public-data client.

A wallet with no Derive account yet is valid: connect() succeeds, and the first deposit creates the account. examples/01-deposit.py walks through it, from creating an owner keystore to a funded subaccount, and examples/02-session-keys.py then registers a session key in its own keystore, so day-to-day trading never needs the owner key.

.env.template holds working testnet credentials. They are published on purpose so the examples run with no setup, and they are worthless: never reuse that key for anything else.

Quickstart

from derive_py import HTTPClient
from derive_py.data_types import D, Direction, OrderType

client = HTTPClient.from_env()

# Public market data needs no credentials and no connect().
ticker = client.markets.get_ticker(instrument_name="ETH-PERP")

# connect() validates the credentials and warms the instrument cache.
# Anything touching subaccount state needs it.
client.connect()

order = client.orders.create(
    instrument_name="ETH-PERP",
    amount=D("0.1"),
    limit_price=D("1000"),
    direction=Direction.buy,
    order_type=OrderType.limit,
)

client.disconnect()

D builds a Decimal. Pass decimals, never floats: amounts and prices are quantized to the instrument's amount_step and tick_size, and the protocol rejects rather than truncates excess precision.

Clients

Only WebSocketClient carries subscriptions. It also holds one connection open rather than paying setup on every call, so it is the one to reach for when latency matters. Its connect() is mandatory, since there is no transport before it. Both HTTP clients open their session lazily on first use, so they need connect() only for credential validation and cached state.

When its connection drops, WebSocketClient fails requests in flight with RequestAbandoned, reconnects with backoff, logs in again and resubscribes every channel, and keeps retrying until disconnect(). Messages sent during the outage are not replayed. If you subscribe, pass on_state_change to connect() and re-read anything built from the stream when it reports CONNECTED after RECONNECTING; examples/04-subscribe.py shows how. Subscribing without one logs a warning, once.

All three expose the same operations:

WebSocketClient adds public_channels, private_channels, subscriptions, connection_state and on_state_change. Every operation is also reachable per subaccount, subaccount.orders and so on, when one client drives several.

Anything not wrapped is reachable through client.public_api and client.private_api, which are generated from the specs above and cover the whole RPC surface.

Examples

Runnable and heavily commented, ordered by the v3 onboarding flow: your first deposit creates the account, then session keys, then the rest.

git clone git@github.com:derivexyz/derive-py.git
cd derive-py
pip install -e .
cp .env.template .env
python examples/03-market-data.py

01-deposit.py is the only one needing a funded L1 key and an RPC endpoint. The rest run against testnet with the credentials in .env.template.

CLI

drv --help          # every command
drv tree            # the tree below, from your installed version
drv market ticker ETH-PERP

drv
├── account.......... Account details.
│   ├── get.......... Account details.
│   └── portfolios... Get all portfolios of a wallet.
├── collateral....... Manage collateral.
│   └── get.......... Get subaccount collaterals.
├── market........... Query market data: currencies, instruments, tickers.
│   ├── currency..... Get currency details.
│   ├── instrument... Get instrument details.
│   ├── ticker....... Get ticker details.
│   └── universe..... List risk universes, their managers and accepted collaterals.
├── mmp.............. Market maker protection configuration.
│   ├── get-config... Get the current mmp config for a subaccount (optionally filtered by currency).
│   ├── reset........ Resets (unfreezes) the mmp state for a subaccount (optionally filtered by currency).
│   └── set-config... Set the mmp config for the subaccount and currency.
├── order............ Create, view, list, and cancel orders.
│   ├── cancel....... Cancel a single order.
│   ├── cancel-all... Cancel all orders.
│   ├── create....... Create a new order.
│   ├── get.......... Get state of an order by order id.
│   └── list-open.... List all open orders of a subaccount.
├── position......... Inspect and transfer positions across subaccounts.
│   ├── list......... List active positions of a subaccount.
│   └── transfer..... Transfer part of a position to another subaccount of the same wallet.
├── system........... Query system-level information.
│   ├── rate-limits.. Get the caller's current rate limits.
│   ├── time......... Get the current system time.
│   └── transaction.. Get a transaction by its operation UUID.
└── tree............. Print the command tree structure.

Development

git clone git@github.com:derivexyz/derive-py.git
cd derive-py
make install            # dependencies and git hooks

make fmt lint typecheck # while working
make tests              # hits the live testnet API
make all                # everything CI runs, in the order CI runs it

make all regenerates the client from the published specs, the API reference and the generated blocks in this README, then formats, lints, type checks and tests. CI runs the same targets and fails on a dirty tree, so run it before pushing and commit whatever it regenerates.

make codegen-all        # regenerate models, API and tests from the specs
make docs               # regenerate the README blocks and build the site
make demo               # re-record the CLI gif, needs cowsay, gum, asciinema, agg

shell.nix provides all of it, recording tools included.

Releasing

poetry run tbump 0.1.1

Tagging triggers the release workflow, which builds, creates a GitHub release and publishes to PyPI.

Contributors

Zarathustra	8ball030	8ball030-max	Saikat K	Andrei Augustin	DomRom
Mf

This client library is developed with support from Derive, who host it under their organization. Requests include default referral_code and client identifiers. All code is open source and auditable.

Resources

• Derive
• Protocol documentation
• Discord
• X / Twitter
• Sibling SDKs: derive-ts, derive-rs

Licence

MIT, see LICENSE.

Disclaimer

This software is provided as-is, without warranty. Trading derivatives involves substantial risk of loss.