Core Concepts

Human units everywhere

Every SDK method takes and returns human units. 100 means 100 USDC, 10 means 10x leverage, prices are plain decimals (3500.5). The SDK handles all on-chain scaling (1e6 for USDC, 1e10 for prices/leverage). Pass strings for exact decimals (collateral="100.25").

Two time bases

Field	Unit
Intent `deadline` / `deadlineMs`	milliseconds (handled by the SDK)
Delegate `expiry_seconds`	seconds

Keys: trader vs API key (delegate)

Trader key: your wallet’s own key. Can do everything.
API key (delegate): a separate key registered to your wallet with one signature (generate one with the Avantis API Key Generator). Can trade, but can never withdraw funds, approve USDC, add delegates, or act on caller-scoped surfaces (referral, claims, LP vault).

Set AVANTIS_TRADER_ADDRESS when using an API key; leave it unset when using the trader key directly. See Delegates.

Execution routes

The default is the relayer, which is gasless: no ETH, no RPC. execution="direct" signs and broadcasts EIP-1559 transactions through your own rpc_url instead. Full details in Execution modes. One exception: update_tp_sl is intent-only in v2 and always goes through the relayer, even in direct mode.

Pairs

Every method accepts a symbol or a pair index interchangeably: "ETH/USD", "eth-usd", or 1.

Receipts and fills

Write methods return an ExecutionReceipt:

Field	Meaning
`route`	`batched-market`, `price-triggers`, `relayer-passthrough`, `twap-api`, `rpc`, or `txbuilder-relay`
`tx_hash`	On-chain hash once settled (may be `None` with `wait=False`)
`request_id`	Relayer queue id (blitz relayer routes)
`tracking_id`	Batched-market lifecycle id (status replay handle)
`order_id`	On-chain order id / twapId, when the API reports it

wait=True (default) follows the order until it settles or relay_poll_timeout_s elapses. On the batched-market route the receipt IS fill-aware: success means the terminal MarketOrderExecuted event arrived, and a protocol-declined fill raises RelayError. On the other relayer routes the receipt confirms your transaction landed, not that the operator filled the order.

For position-level confirmation, poll client.account.positions() after a short delay, or subscribe to the order event stream.

receipt = await client.trade.market_open("ETH/USD", "long", collateral=100, leverage=10)
await asyncio.sleep(3)
positions = await client.account.positions()   # the fill shows up here

Errors

Every failure raises a typed exception from avantis_trader_sdk.errors. See Errors.

Getting Started

Migrating from v1

Trading

Account & Portfolio

Data & Compute

Earn & Grow

Advanced

Human units everywhere

Two time bases

Keys: trader vs API key (delegate)

Execution routes

Pairs

Receipts and fills

Errors

​Human units everywhere

​Two time bases

​Keys: trader vs API key (delegate)

​Execution routes

​Pairs

​Receipts and fills

​Errors

Human units everywhere

Two time bases

Keys: trader vs API key (delegate)

Execution routes

Pairs

Receipts and fills

Errors