dYdX Documentation

Get Account Balance

The Get Account Balance query retrieves the balance of a specified account address for a particular denomination.

This function is crucial for obtaining the current funds available in a wallet within blockchain network.

Method Declaration

Python

async def get_account_balance(
    self,
    address: str,
    denom: str,
) -> bank_query.QueryBalanceResponse

Parameters

Parameter	Location	Type	Required	Description
`address`	query	Address	true	The wallet address that owns the subaccount.
`denom`	query	Denom	true	The denomination of the balance.

Response

Status	Meaning	Schema
`200`	OK	Coin

Examples: Python | Rust

Get Latest Block Height

The Get Latest Block Height function asynchronously retrieves the most recent block height from a blockchain network.

This information is typically returned as an integer value wrapped in a specific data type or promise, indicating the current height of the blockchain.

Method Declaration

Python

async def latest_block_height(self) -> int

Parameters

Response

Status	Meaning	Schema
`200`	OK	Height

Examples: Python | Rust

Get User Fee Tier

The Get User Fee Tier function retrieves the perpetual fee tier associated with a specific wallet address, providing information on the user's current fee structure.

This is essential for users to understand the fees applicable to their transactions on the platform.

Method Declaration

Python

async def get_user_fee_tier(
    self, address: str
) -> fee_tier_query.QueryUserFeeTierResponse

Unification Plan

Parameters

Parameter	Location	Type	Required	Description
`user`	query	Address	true	The wallet address that owns the subaccount.

Response

Status	Meaning	Schema
`200`	OK	PerpetualFeeTier

Examples: Python | TypeScript | Rust

List Orders

Retrieves orders for a specific subaccount, with various filtering options to narrow down the results based on order characteristics.

Method Declaration

Python

async def get_subaccount_orders(
    self,
    address: str,
    subaccount_number: int,
    ticker: Optional[str] = None,
    ticker_type: TickerType = TickerType.PERPETUAL,
    side: Optional[OrderSide] = None,
    status: Optional[OrderStatus] = None,
    type: Optional[OrderType] = None,
    limit: Optional[int] = None,
    good_til_block_before_or_at: Optional[int] = None,
    good_til_block_time_before_or_at: Optional[str] = None,
    return_latest_orders: Optional[bool] = None,
) -> Any

Unification Plan

Parameters

Parameter	Location	Type	Required	Description
`address`	query	Address	true	The wallet address that owns the subaccount.
`subaccount_number`	query	SubaccountNumber	true	The identifier for the specific subaccount within the wallet address.
`limit`	query	u32	false	Maximum number of asset positions to return in the response.
`ticker`	query	Ticker	false	The ticker filter.
`side`	query	OrderSide	false	The order side filter.
`status`	query	OrderStatus	false	The order status filter.
`type`	query	OrderType	false	The order type filter.
`good_til_block_before_or_at`	query	Height	false	The block number filter for orders good until before or at.
`good_til_block_time_before_or_at`	query	DateTime in utc	false	The timestamp filter for orders good until before or at.
`return_latest_orders`	query	bool	false	Whether to return only the latest orders.

Response

Status	Meaning	Schema	Description
`200`	OK	ListOrdersResponse	The orders data.

Get Fills

Retrieves fill records for a specific subaccount on the exchange.

This function queries the dYdX indexer API to fetch fill data (executed orders) associated with a particular subaccount. The endpoint being called is /v4/fills.

A fill represents a trade that has been executed on the exchange.

Method Declaration

Python

async def get_subaccount_fills(
    self,
    address: str,
    subaccount_number: int,
    ticker: Optional[str] = None,
    ticker_type: TickerType = TickerType.PERPETUAL,
    limit: Optional[int] = None,
    created_before_or_at_height: Optional[int] = None,
    created_before_or_at: Optional[str] = None,
) -> Any

Unification Plan

Rename all methods to get_fills - shorter is better.
Add a Subaccount pair to Python and JavaScript, since it's always a pair
Rename created_before_or_at_time parameter to created_before_or_at
page optional parameter is missing in Python
page optional parameter is missing in Rust
In Rust market field of the options struct must be ticker
In Rust market_type field of the options struct must be ticker_type

Parameters

Parameter	Location	Type	Required	Description
`address`	query	Address	true	The wallet address that owns the subaccount.
`subaccount_number`	query	SubaccountNumber	true	The identifier for the specific subaccount within the wallet address.
`ticker`	query	Ticker	false	The market symbol to filter fills by (e.g., "BTC-USD"). If not provided, fills for all markets will be returned.
`ticker_type`	query	MarketType	false	The type of market to filter by.
`limit`	query	u32	false	Maximum number of asset positions to return in the response.
`created_before_or_at_height`	query	Height	false	Restricts results to positions created at or before a specific blockchain height.
`created_before_or_at`	query	DateTime	false	Restricts results to positions created at or before a specific timestamp (ISO 8601 format).
`page`	query	u32	false	The page number for paginated results.

Response

A promise that resolves to fill data containing details such as order ID, market, side (buy/sell), size, price, execution time, and other fill-specific information.

Status	Meaning	Schema	Description
`200`	OK	FillResponseObject ⛁	The fills data.

Markets

// TODO: Add description

Method Declaration

Python

Unification Plan

Parameters

Parameter	Location	Type	Description
`address`	query	[Address]	The wallet address that owns the subaccount.

Optional

Parameter	Location	Type	Description
`limit`	query	[u32]	Maximum number of asset positions to return in the response.

Response

Status	Meaning	Schema
`200`	[OK]	[AssetPositionResponseObject] ⛁

List Positions

Retrieves perpetual positions for a specific subaccount. This method allows you to query and filter the active or historical perpetual positions associated with a particular subaccount.

Method Declaration

Python

async def get_subaccount_perpetual_positions(
    self,
    address: str,
    subaccount_number: int,
    status: Optional[PositionStatus] = None,
    limit: Optional[int] = None,
    created_before_or_at_height: Optional[int] = None,
    created_before_or_at: Optional[str] = None,
) -> Any

Unification Plan

Parameters

Parameter	Location	Type	Required	Description
`address`	query	Address	true	The wallet address that owns the subaccount.
`subaccount_number`	query	SubaccountNumber	true	The identifier for the specific subaccount within the wallet address.
`status`	query	PerpetualPositionStatus	false	Filter to retrieve positions with a specific status. If not provided, all positions will be returned regardless of status.
`limit`	query	u32	false	Maximum number of asset positions to return in the response.
`created_before_or_at_height`	query	Height	false	Restricts results to positions created at or before a specific blockchain height.
`created_before_or_at`	query	DateTime	false	Restricts results to positions created at or before a specific timestamp (ISO 8601 format).

Response

Status	Meaning	Schema	Description
`200`	OK	PerpetualPositionResponseObject ⛁	The perpetual positions data.

Get Rewards Params

The Get Rewards Params function retrieves the parameters for the rewards system, providing insight into the set configurations for earning and distributing rewards.

This API call returns a structured response detailing these parameters, ensuring users have access to the current rewards setup for planning and analysis.

Method Declaration

Python

async def get_rewards_params(self) -> rewards_query.QueryParamsResponse

Unification Plan

Rename Params to RewardsParams in Rust

Parameters

Response

Status	Meaning	Schema
`200`	OK	RewardsParams

Examples: Python | TypeScript | Rust