# Avantis Python SDK

## Docs

- [Introduction](https://sdk.avantisfi.com/index.md): Trade Avantis v2 perpetuals from Python. Gasless by default, no ABIs, no RPC.
- [Quickstart](https://sdk.avantisfi.com/quickstart.md): From zero to a filled trade.
- [Configuration](https://sdk.avantisfi.com/configuration.md): Environment variables, constructor overrides, networks, and signers.
- [Core Concepts](https://sdk.avantisfi.com/concepts.md): Units, keys, execution routes, and receipts: the five things every page assumes.
- [Migrating from v1](https://sdk.avantisfi.com/migration/overview.md): Avantis v2 is live as of August 12, 2026. What changed, what carries over, and how to move your integration.
- [Python SDK: 0.x to 2.x](https://sdk.avantisfi.com/migration/sdk-migration.md): Method-by-method mapping from the v1 TraderClient to the v2 AsyncAvantis client.
- [Direct Integrators](https://sdk.avantisfi.com/migration/direct-integrators.md): v1 to v2 for teams that call the contracts or decode their events directly: MMs, indexers, keepers, risk engines.
- [Market Orders](https://sdk.avantisfi.com/trading/market-orders.md): Open and close positions at the current price.
- [Limit Orders](https://sdk.avantisfi.com/trading/limit-orders.md): Place, update, and cancel resting orders.
- [Take Profit & Stop Loss](https://sdk.avantisfi.com/trading/tp-sl.md): Full-position TP/SL on-chain, partial TP/SL as off-chain trigger orders.
- [Margin & Position Size](https://sdk.avantisfi.com/trading/margin-and-size.md): Deposit or withdraw collateral, and add size to open positions.
- [TWAP Orders](https://sdk.avantisfi.com/trading/twap.md): Execute large orders in time-weighted slices.
- [Positions](https://sdk.avantisfi.com/account/positions.md): Open positions, limit orders, and balances.
- [Portfolio & History](https://sdk.avantisfi.com/account/portfolio.md): Trade history, PnL analytics, and everything the Avantis portfolio page shows.
- [Delegates & API Keys](https://sdk.avantisfi.com/account/delegates.md): Register trading keys that can never touch your funds.
- [Approvals & Claims](https://sdk.avantisfi.com/account/approvals.md): USDC allowances, rebate claims, and builder codes.
- [Markets](https://sdk.avantisfi.com/data/markets.md): Pair catalog, fees, funding, open interest, and spreads.
- [Pair Data Socket.IO](https://sdk.avantisfi.com/data/socket-io.md): Live pair-catalog diffs from the data service. Same payload as GET /v2/trading, streamed as partial updates.
- [Prices & Streams](https://sdk.avantisfi.com/data/prices-and-streams.md): Polled prices and four real-time feeds.
- [Compute](https://sdk.avantisfi.com/data/compute.md): Pure, offline math with exact UI parity: PnL, liquidation, fees, validation.
- [LP Vault](https://sdk.avantisfi.com/more/lp-vault.md): Provide USDC liquidity through the ERC-4626 tranche (avUSDC).
- [Referrals](https://sdk.avantisfi.com/more/referrals.md): Register codes, refer traders, and claim rebates.
- [Execution Modes](https://sdk.avantisfi.com/advanced/execution-modes.md): How orders reach the chain: relayer (gasless) vs direct.
- [Market-Maker Fast Path](https://sdk.avantisfi.com/advanced/mm-fast-path.md): Build and sign orders locally, submit with the fewest possible round-trips.
- [Security Model](https://sdk.avantisfi.com/advanced/security.md): Key permissions, digest verification, and what can never happen.
- [Errors](https://sdk.avantisfi.com/advanced/errors.md): Typed exception taxonomy: catch precisely, retry safely.
- [How the API Works](https://sdk.avantisfi.com/api-reference/overview.md): Build a payload, sign it locally, submit it. The three-step flow behind every endpoint.
- [Get service metadata](https://sdk.avantisfi.com/api-reference/meta/get-service-metadata.md): Call once at startup. Returns everything a client needs to encode and sign correctly without hard-coding anything: chainId, contract addresses, both EIP-712 signing domains (trading and referral), enum mappings, unit conventions (which fields are seconds vs milliseconds, on-chain scaling), and servi…
- [List all tradable pairs](https://sdk.avantisfi.com/api-reference/meta/list-all-tradable-pairs.md): The market catalog: for each pair, its index (used in every trading request), leverage bounds (regular and market_pnl), minimum position size, open-interest headroom, trading schedule, and listing / close-only status. Cached for a few minutes.
- [Liveness probe](https://sdk.avantisfi.com/api-reference/meta/liveness-probe.md): Cheap health check with no dependency calls. Use /ready for dependency status.
- [Readiness probe](https://sdk.avantisfi.com/api-reference/meta/readiness-probe.md): Runs dependency checks (RPC pool chain-id, Avantis data API pair catalog) and returns 503 with a per-component breakdown when any fail. Wire as the Kubernetes readiness probe.
- [Prometheus metrics](https://sdk.avantisfi.com/api-reference/meta/prometheus-metrics.md): Prometheus text exposition: HTTP latency by route, upstream latency/errors per target, relay outcomes, build counters, validation rejections, cache health, Node.js runtime.
- [Get contract addresses](https://sdk.avantisfi.com/api-reference/meta/get-contract-addresses.md): The chainId and Avantis contract addresses this deployment targets.
- [Single pair by index](https://sdk.avantisfi.com/api-reference/meta/single-pair-by-index.md): One trading pair from the catalog: leverage bounds, minimum position size, open-interest headroom, trading schedule, and listing/close-only status.
- [Build an open-position transaction (market, limit, or stop-limit)](https://sdk.avantisfi.com/api-reference/trading/build-an-open-position-transaction-market-limit-or-stop-limit.md): Returns an unsigned transaction that opens a position of collateralUsdc × leverage. Market and market_pnl orders execute immediately (a pending order the Avantis operator fulfills at the oracle price); limit and stop_limit orders queue at openPrice until triggered. Prerequisite: a one-time USDC appr…
- [Build an open-position transaction targeting a fixed base-asset exposure](https://sdk.avantisfi.com/api-reference/trading/build-an-open-position-transaction-targeting-a-fixed-base-asset-exposure.md): Like /v2/trade/open, but the fill targets an exact exposure in base-asset units (e.g. exactly 0.5 ETH) instead of a USD notional; the fill leverage floats within [minLeverage, maxLeverage]. Only market and market_pnl order types are supported.
- [Build a market-close transaction (full or partial)](https://sdk.avantisfi.com/api-reference/trading/build-a-market-close-transaction-full-or-partial.md): Returns an unsigned transaction that closes part or all of an open position at market. The amount is expressed as collateral: pass the position's full collateral (GET /v2/positions → trades[].trade.positionSizeUSDC) for a full close, or less for a partial close. Payout always goes to the trader. Att…
- [Build a market-close transaction for a fixed base-asset exposure](https://sdk.avantisfi.com/api-reference/trading/build-a-market-close-transaction-for-a-fixed-base-asset-exposure.md): Like /v2/trade/close, but the amount to close is expressed in base-asset units (e.g. close exactly 0.25 ETH of exposure). Current exposure is in GET /v2/positions → trades[].coinExposure.
- [Build a transaction that edits a pending limit / stop-limit order](https://sdk.avantisfi.com/api-reference/trading/build-a-transaction-that-edits-a-pending-limit-stop-limit-order.md): Returns an unsigned transaction that updates the trigger price, slippage, and TP/SL of a queued limit order that has not executed yet. Setting takeProfit or stopLoss to 0 removes them.
- [Build a transaction that cancels a pending limit / stop-limit order](https://sdk.avantisfi.com/api-reference/trading/build-a-transaction-that-cancels-a-pending-limit-stop-limit-order.md): Returns an unsigned transaction that cancels a queued limit order and refunds its escrowed USDC collateral to the trader.
- [Build a transaction that adds or removes position collateral](https://sdk.avantisfi.com/api-reference/trading/build-a-transaction-that-adds-or-removes-position-collateral.md): Returns an unsigned transaction that deposits USDC into (or withdraws from) an open position's margin, changing its effective leverage and liquidation price. Executes atomically against a fresh oracle price — the attached `value` is a tiny oracle update fee (1 wei default), not an operator fee. With…
- [Build a transaction that increases an open position](https://sdk.avantisfi.com/api-reference/trading/build-a-transaction-that-increases-an-open-position.md): Returns an unsigned transaction that adds additionalCollateralUsdc × leverage of size to an existing position. Two-step on-chain: your transaction stores a pending order that the Avantis operator fulfills at the oracle price (no ETH fee attached — the operator pays that leg).
- [Build a position-increase transaction targeting a fixed base-asset exposure](https://sdk.avantisfi.com/api-reference/trading/build-a-position-increase-transaction-targeting-a-fixed-base-asset-exposure.md): Like /v2/position/increase, but the added size is expressed in base-asset units; the fill leverage floats within [minLeverage, maxLeverage].
- [Build a transaction that authorizes a delegate (agent key)](https://sdk.avantisfi.com/api-reference/delegate/build-a-transaction-that-authorizes-a-delegate-agent-key.md): Returns an unsigned transaction the TRADER must sign (a delegate can never authorize another delegate). The delegate can then trade on the trader's behalf — open, close, TP/SL — but can never move funds: payouts always go to the trader and the delegate cannot approve USDC or manage delegations. For…
- [Build a transaction that revokes a delegate](https://sdk.avantisfi.com/api-reference/delegate/build-a-transaction-that-revokes-a-delegate.md): Returns an unsigned transaction the TRADER must sign. Revocation is immediate and also invalidates any of the delegate's signed-but-unsubmitted intents (authorization is checked at submission time).
- [Build a USDC approval transaction (one-time trading prerequisite)](https://sdk.avantisfi.com/api-reference/token/build-a-usdc-approval-transaction-one-time-trading-prerequisite.md): Returns an unsigned USDC approve() transaction. Trading requires a one-time approval to TradingStorage from the trader (collateral is always pulled from the trader, even for delegate-signed actions); LP deposits require a separate approval with spender set to the tranche address (see /addresses). Ch…
- [Build a signable open-position intent](https://sdk.avantisfi.com/api-reference/intents/build-a-signable-open-position-intent.md): Gasless equivalent of /v2/trade/open. Returns an EIP-712 payload to sign (trader or a registered delegate may sign) and hand to the Avantis operator for gasless execution. Prerequisite: the trader's one-time USDC approval to TradingStorage.
- [Build a signable open intent targeting a fixed base-asset exposure](https://sdk.avantisfi.com/api-reference/intents/build-a-signable-open-intent-targeting-a-fixed-base-asset-exposure.md): Gasless equivalent of /v2/trade/open-coin: the fill targets an exact base-asset exposure with leverage floating within [minLeverage, maxLeverage]. Returns an EIP-712 payload to sign (trader or a registered delegate may sign) and hand to the Avantis operator for gasless execution.
- [Build a signable close-position intent (full or partial)](https://sdk.avantisfi.com/api-reference/intents/build-a-signable-close-position-intent-full-or-partial.md): Gasless equivalent of /v2/trade/close. Returns an EIP-712 payload to sign (trader or a registered delegate may sign) and hand to the Avantis operator for gasless execution. The intent is bound to the position's current on-chain open timestamp — re-request it after any margin update or partial close,…
- [Build a signable close intent for a fixed base-asset exposure](https://sdk.avantisfi.com/api-reference/intents/build-a-signable-close-intent-for-a-fixed-base-asset-exposure.md): Gasless equivalent of /v2/trade/close-coin. Returns an EIP-712 payload to sign (trader or a registered delegate may sign) and hand to the Avantis operator for gasless execution.
- [Build a signable position-increase intent](https://sdk.avantisfi.com/api-reference/intents/build-a-signable-position-increase-intent.md): Gasless equivalent of /v2/position/increase. Returns an EIP-712 payload to sign (trader or a registered delegate may sign) and hand to the Avantis operator for gasless execution.
- [Build a signable position-increase intent for a fixed base-asset exposure](https://sdk.avantisfi.com/api-reference/intents/build-a-signable-position-increase-intent-for-a-fixed-base-asset-exposure.md): Gasless equivalent of /v2/position/increase-coin. Returns an EIP-712 payload to sign (trader or a registered delegate may sign) and hand to the Avantis operator for gasless execution.
- [Build a signable take-profit / stop-loss update intent](https://sdk.avantisfi.com/api-reference/intents/build-a-signable-take-profit-stop-loss-update-intent.md): Sets or removes a position's TP and SL prices (stopLoss=0 removes the SL; takeProfit=0 resets the TP to the pair's max-gain cap — a position always has a TP on-chain). Returns an EIP-712 payload to sign (trader or a registered delegate may sign) and hand to the Avantis operator for gasless execution…
- [Build a signable partial take-profit / stop-loss intent](https://sdk.avantisfi.com/api-reference/intents/build-a-signable-partial-take-profit-stop-loss-intent.md): Arms a trigger that closes part of a position (coinExposure) when it is hit: either at a fixed price (triggerType=fixed, set `price`) or at a profit/loss percentage (triggerType=percentage, set signed `percentage`). Returns an EIP-712 payload to sign (trader or a registered delegate may sign) and ha…
- [Build a signable cancel for a stored partial TP/SL](https://sdk.avantisfi.com/api-reference/intents/build-a-signable-cancel-for-a-stored-partial-tpsl.md): Builds the EIP-712 CancelOffchainOrder payload over a stored order's entityId (returned when the partial TP/SL was created; re-minted on every update). Sign it and send DELETE /price-triggers with {entityId, signedMessage} to the core API — entityIds are public, so the signature is the proof of owne…
- [Build a signable TWAP open intent](https://sdk.avantisfi.com/api-reference/intents/build-a-signable-twap-open-intent.md): The position is opened in slices spread across runTimeSeconds. POST the signed intent to the twap-app (/twaps/open), which submits the transaction itself and responds with the twapId. Returns an EIP-712 payload to sign (trader or a registered delegate may sign) and hand to the Avantis operator for g…
- [Build a signable TWAP close intent](https://sdk.avantisfi.com/api-reference/intents/build-a-signable-twap-close-intent.md): The exposure is closed in slices spread across runTimeSeconds. POST the signed intent to the twap-app (/twaps/close), which submits the transaction itself. Returns an EIP-712 payload to sign (trader or a registered delegate may sign) and hand to the Avantis operator for gasless execution.
- [Build a signable TWAP cancel intent](https://sdk.avantisfi.com/api-reference/intents/build-a-signable-twap-cancel-intent.md): Cancels a pending TWAP by its on-chain twapId, stopping further slices and refunding unused escrowed collateral. POST the signed intent to the twap-app (/twaps/cancel), which submits the transaction itself. Returns an EIP-712 payload to sign (trader or a registered delegate may sign) and hand to the…
- [Build a signable referral-code registration intent](https://sdk.avantisfi.com/api-reference/intents/build-a-signable-referral-code-registration-intent.md): Gasless equivalent of /v2/referral/register-code: the referrer (or their delegate) signs, the Avantis operator submits. Verifies against the Referral contract's own EIP-712 domain and nonce space.
- [Build a signable intent that links a trader to a referral code](https://sdk.avantisfi.com/api-reference/intents/build-a-signable-intent-that-links-a-trader-to-a-referral-code.md): Gasless equivalent of /v2/referral/set-code: the referee (or their delegate) signs, the Avantis operator submits. Verifies against the Referral contract's own EIP-712 domain and nonce space.
- [Build a signable delegate-authorization intent (gasless onboarding)](https://sdk.avantisfi.com/api-reference/intents/build-a-signable-delegate-authorization-intent-gasless-onboarding.md): Gasless equivalent of /v2/delegate/set — the standard way to register an agent key without the trader spending gas. The TRADER must sign this intent themselves (signerRule is trader-only; a delegate can never authorize another delegate). The message embeds the canonical Avantis terms-of-service stri…
- [Batched Market Execution](https://sdk.avantisfi.com/api-reference/batched-market.md): Submit signed market orders gaslessly and stream the fill lifecycle over SSE. The market-maker fast path.
- [Broadcast a signed transaction through Avantis-operated RPCs](https://sdk.avantisfi.com/api-reference/relay/broadcast-a-signed-transaction-through-avantis-operated-rpcs.md): Submits an already-signed transaction without the caller needing their own RPC endpoint. Pipeline: parse → chainId check → contract whitelist (USDC is restricted to approve() of protocol spenders) → eth_call simulation with revert reasons decoded against the protocol error catalog → broadcast with R…
- [Get transaction status](https://sdk.avantisfi.com/api-reference/relay/get-transaction-status.md): Looks up the transaction receipt: pending (not yet mined / unknown hash), confirmed, or reverted. Stateless — any transaction hash on this chain can be queried.
- [Build a TWAP open transaction (position built in slices over time)](https://sdk.avantisfi.com/api-reference/twap/build-a-twap-open-transaction-position-built-in-slices-over-time.md): Returns an unsigned transaction that escrows collateralUsdc and instructs the Avantis operator to open the position in slices spread across runTimeSeconds — reducing price impact for large orders. Unused collateral is refundable via /v2/twap/cancel.
- [Build a TWAP close transaction (exposure unwound in slices over time)](https://sdk.avantisfi.com/api-reference/twap/build-a-twap-close-transaction-exposure-unwound-in-slices-over-time.md): Returns an unsigned transaction that instructs the Avantis operator to close coinExposureToClose of an open position in slices spread across runTimeSeconds.
- [Build a transaction that cancels a running TWAP](https://sdk.avantisfi.com/api-reference/twap/build-a-transaction-that-cancels-a-running-twap.md): Returns an unsigned transaction that stops further slices of a TWAP order and refunds any unused escrowed collateral to the trader.
- [Build a transaction that registers a new referral code](https://sdk.avantisfi.com/api-reference/referral/build-a-transaction-that-registers-a-new-referral-code.md): Returns an unsigned transaction that registers a referral code owned by the caller. Traders who adopt the code get a fee discount and the owner earns rebates (claim via /v2/referral/claim-rebate). Gasless alternative: /v2/intents/referral-register-code.
- [Build a transaction that links the caller to a referral code](https://sdk.avantisfi.com/api-reference/referral/build-a-transaction-that-links-the-caller-to-a-referral-code.md): Returns an unsigned transaction that adopts an existing (public) referral code as the caller's referrer, activating the fee discount. Gasless alternative: /v2/intents/referral-set-code.
- [Build a transaction that requests access to a private referral code](https://sdk.avantisfi.com/api-reference/referral/build-a-transaction-that-requests-access-to-a-private-referral-code.md): Private codes require the code owner's approval: the trader requests access here, then the owner grants it via /v2/referral/set-code-by-owner.
- [Build a transaction that cancels a pending private-code request](https://sdk.avantisfi.com/api-reference/referral/build-a-transaction-that-cancels-a-pending-private-code-request.md): Withdraws the caller's outstanding private-code access request.
- [Build a transaction that removes the caller's referral code](https://sdk.avantisfi.com/api-reference/referral/build-a-transaction-that-removes-the-callers-referral-code.md): Clears the referral code currently linked to the caller, ending the fee discount.
- [Build a transaction that grants a private code to a trader (code owner only)](https://sdk.avantisfi.com/api-reference/referral/build-a-transaction-that-grants-a-private-code-to-a-trader-code-owner-only.md): The code owner approves a trader's pending request (see /v2/referral/request-special-code), linking the private code to that trader.
- [Build a transaction that starts a referral-code ownership transfer](https://sdk.avantisfi.com/api-reference/referral/build-a-transaction-that-starts-a-referral-code-ownership-transfer.md): Two-step transfer: the current owner nominates a new owner here; the new owner completes it via /v2/referral/accept-ownership.
- [Build a transaction that completes a referral-code ownership transfer](https://sdk.avantisfi.com/api-reference/referral/build-a-transaction-that-completes-a-referral-code-ownership-transfer.md): Signed by the nominated new owner to finalize a transfer started via /v2/referral/transfer-ownership.
- [Build a transaction that claims accumulated referral rebates](https://sdk.avantisfi.com/api-reference/referral/build-a-transaction-that-claims-accumulated-referral-rebates.md): Returns an unsigned transaction that pays out the caller's accrued referrer rebates in USDC.
- [Build a vault deposit transaction (USDC → avUSDC shares)](https://sdk.avantisfi.com/api-reference/lp/build-a-vault-deposit-transaction-usdc-→-avusdc-shares.md): Returns an unsigned transaction that deposits USDC into the Avantis liquidity vault and mints avUSDC shares to the receiver. Prerequisite: USDC approval to the tranche (/v2/token/approve with spender = tranche address). Yield accrues via the share price.
- [Build a vault mint transaction (exact avUSDC shares out)](https://sdk.avantisfi.com/api-reference/lp/build-a-vault-mint-transaction-exact-avusdc-shares-out.md): Like /v2/lp/deposit, but specifies the exact number of avUSDC shares to receive; the USDC cost is computed by the vault at execution. Prerequisite: USDC approval to the tranche.
- [Build a vault withdrawal transaction (exact USDC out)](https://sdk.avantisfi.com/api-reference/lp/build-a-vault-withdrawal-transaction-exact-usdc-out.md): Returns an unsigned transaction that withdraws an exact USDC amount from the vault by burning the corresponding avUSDC shares. Withdrawals are immediate but revert if they would push vault utilization above the protocol threshold — check limits via GET /v2/lp/state.
- [Build a vault redeem transaction (exact avUSDC shares in)](https://sdk.avantisfi.com/api-reference/lp/build-a-vault-redeem-transaction-exact-avusdc-shares-in.md): Like /v2/lp/withdraw, but burns an exact number of avUSDC shares; the USDC received is computed by the vault at execution. Subject to the same utilization threshold.
- [Read vault state (share price, utilization, per-owner limits)](https://sdk.avantisfi.com/api-reference/lp/read-vault-state-share-price-utilization-per-owner-limits.md): Reads the vault totals, share price, utilization ratio, and deposit cap; pass `owner` to also get that account's share balance and current maxWithdraw / maxRedeem limits. Values are strings in on-chain units (USDC 1e6, utilization 1e10).
- [Build a transaction that claims keeper trigger rewards](https://sdk.avantisfi.com/api-reference/misc/build-a-transaction-that-claims-keeper-trigger-rewards.md): For keeper bots: returns an unsigned transaction that pays out rewards accumulated by triggering limit orders and liquidations.
- [Build a transaction that adds USDC to the protocol buffer](https://sdk.avantisfi.com/api-reference/misc/build-a-transaction-that-adds-usdc-to-the-protocol-buffer.md): Permissionless donation of USDC into the VaultManager buffer (used to smooth trader PnL payouts). Requires USDC approval to the VaultManager. This is not an LP deposit — it earns nothing.
- [Build a transaction that registers a builder code](https://sdk.avantisfi.com/api-reference/misc/build-a-transaction-that-registers-a-builder-code.md): For builder partners: registers a fee configuration (percent or fixed per trade) that integrations can attach to trades routed through them. The caller becomes the code owner.
- [Build a transaction that modifies a builder code (owner only)](https://sdk.avantisfi.com/api-reference/misc/build-a-transaction-that-modifies-a-builder-code-owner-only.md): Updates the fee configuration or fee collector of a builder code the caller owns.
- [Suggest (or verify) a free intent nonce](https://sdk.avantisfi.com/api-reference/reads/suggest-or-verify-a-free-intent-nonce.md): Returns a random unused nonce for signing intents, verified against the on-chain TradingRouter nonce bitmap. Pass `check` to verify a specific nonce instead. Nonces are unordered — parallel intents just need distinct values.
- [List open positions and pending limit orders](https://sdk.avantisfi.com/api-reference/reads/list-open-positions-and-pending-limit-orders.md): Reads all open positions (with liquidation price, exposure, and the open timestamp needed for close intents) and pending limit orders for a trader, directly from chain via the Multicall aggregator. All numeric values are decimal strings in on-chain units (USDC 1e6, prices/leverage 1e10).
- [Check a delegate authorization](https://sdk.avantisfi.com/api-reference/reads/check-a-delegate-authorization.md): Reads the on-chain delegation record for a trader + delegate pair. Returns two capability flags because the contracts use different expiry boundaries: canDelegatedAction (direct transactions) and canSignIntents (gasless intents).
- [Check USDC allowance and balance](https://sdk.avantisfi.com/api-reference/reads/check-usdc-allowance-and-balance.md): Reads the trader's USDC balance and how much a protocol contract may pull. An allowance of 0 means trading (or LP deposits) will revert — fix it with /v2/token/approve.

## OpenAPI Specs

- [openapi](https://tx-builder-testnet.avantisfi.com/openapi.json)