dYdX Documentation

Accounts

Python

account = indexer_client.account()

Get Subaccounts

Retrieves a list of subaccounts associated with a given address. Subaccounts are related addresses that fall under the authority or ownership of the primary address.

Method Declaration

Python

async def get_subaccounts(
    self,
    address: str,
    limit: Optional[int] = None,
) -> Any

Unification Plan

Rust implementation doesn't have optional parameters.

Parameters

Parameter	Location	Type	Required	Description
`address`	path	Address	true	The primary address for which to retrieve associated subaccounts.
`limit`	query	u32	false	Maximum number of subaccounts in the response.

Response

Status	Meaning	Schema	Description
`200`	OK	AddressResponse	The subaccounts data.
`400`	Bad Request		The request was malformed or invalid.

API Example

Get Subaccount

Retrieves a specific subaccount associated with a given address and subaccount number.

Method Declaration

Python

async def get_subaccount(
    self,
    address: str,
    subaccount_number: int,
) -> Any

Unification Plan

Parameters

Parameter	Location	Type	Required	Description
`address`	query	Address	true	The primary address to which the subaccount belongs.
`subaccountNumber`	query	SubaccountNumber	true	The specific subaccount number to retrieve.

Response

Status	Meaning	Schema	Description
`200`	OK	SubaccountResponseObject ⛁	The subaccount data.
`400`	Bad Request		The request was malformed or invalid.
`404`	Not Found		The subaccount was not found.

API Example

List Positions

Retrieves perpetual positions for a specific subaccount. Both open and closed/historical positions can be queried.

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 account.
`subaccountNumber`	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.
`createdBeforeOrAtHeight`	query	Height	false	Restricts results to positions created at or before a specific blockchain height.
`createdBeforeOrAt`	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.
`400`	Bad Request		The request was malformed or invalid.
`404`	Not Found		The subaccount was not found.

API Example

Examples: Guide - List Positions

Get Asset Positions

Retrieves asset positions and respective details of a specific subaccount.

Method Declaration

Python

async def get_subaccount_asset_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

Rename all methods to get_asset_positions - shorter is better.
Add a Subaccount pair to Python and JavaScript, since it's always a pair
Add options to the Rust version
Rename created_before_or_at_time parameter to created_before_or_at
Rename PerpetualPositionStatus to PositionStatus

Parameters

Parameter	Location	Type	Required	Description
`address`	query	Address	true	The wallet address that owns the account.
`subaccountNumber`	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.
`createdBeforeOrAtHeight`	query	Height	false	Restricts results to positions created at or before a specific blockchain height.
`createdBeforeOrAt`	query	DateTime	false	Restricts results to positions created at or before a specific timestamp (ISO 8601 format).

Response

A data structure containing the requested asset positions. Typically includes details such as asset ID, size, side (buy/sell), entry price, realized PnL, and other position-specific information.

Status	Meaning	Schema	Description
`200`	OK	AssetPositionResponseObject ⛁	The asset positions data.

API Example

Get Transfers

Retrieves the transfer history for a specific subaccount.

Method Declaration

Python

async def get_subaccount_transfers(
    self,
    address: str,
    subaccount_number: int,
    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 account.
`subaccount_number`	query	SubaccountNumber	true	The identifier for the specific subaccount within the wallet address.
`limit`	query	u32	false	Maximum number of items in the response.
`createdBeforeOrAtHeight`	query	Height	false	Restricts results to positions created at or before a specific blockchain height.
`createdBeforeOrAt`	query	DateTime	false	Restricts results to positions created at or before a specific timestamp.
`page`	query	u32	false	The page number for paginated results.

Response

Status	Meaning	Schema	Description
`200`	OK	TransferResponseObject ⛁	The transfers data.
`400`	Bad Request		The request was malformed or invalid.
`404`	Not Found		The subaccount was not found.

API Example

Get Transfers Between

Fetch information regarding a transfer between two subaccounts.

Method Declaration

Python

async def get_transfer_between(
    self,
    source_address: str,
    source_subaccount_number: int,
    recipient_address: str,
    recipient_subaccount_number: int,
    created_before_or_at_height: Optional[int] = None,
    created_before_or_at: Optional[str] = None,
) -> Any

Unification Plan

Response object does not have defined structure in TypeScript client. Will have to work on it.

Parameters

Parameter	Location	Type	Required	Description
`sourceAddress`	query	string	true	Sender's wallet address
`sourceSubaccountNumber`	query	string	true	The identifier for the specific subaccount within the sender wallet address.
`recipientAddress`	query	string	true	Receiver wallet address
`recipientSubaccountNumber`	query	string	true	The identifier for the specific subaccount within the receiver wallet address.
`createdBeforeOrAtHeight`	query	number	false	Restricts results to positions created at or before a specific blockchain height.
`createdBeforeOrAt`	query	string	false	Restricts results to positions created at or before a specific timestamp (ISO 8601 format).

Response

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 account.
`subaccountNumber`	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.
`goodTilBlockBeforeOrAt`	query	Height	false	The block number filter for orders good until before or at.
`goodTilBlockTimeBeforeOrAt`	query	DateTime in UTC	false	The timestamp filter for orders good until before or at.
`returnLatestOrders`	query	bool	false	Whether to return only the latest orders.

Response

Status	Meaning	Schema	Description
`200`	OK	OrderResponseObject ⛁	The orders data.
`400`	Bad Request		The request was malformed or invalid.
`404`	Not Found		The subaccount was not found.

API Example

Examples: Guide - List Orders

Get Order

Retrieves detailed information about a specific order based on its unique identifier (the order ID). To get the order ID, see how to create it or fetch the order history.

Method Declaration

Python

async def get_order(
    self,
    order_id: str,
) -> Any

Unification Plan

Parameters

Parameter	Location	Type	Required	Description
`orderId`	path	OrderId	true	The order ID.

Response

Status	Meaning	Schema	Description
`200`	OK	OrderResponseObject ⛁	The order data.
`400`	Bad Request		The request was malformed or invalid.
`404`	Not Found		The order was not found.

API Example

Get Fills

Retrieves fill records for a specific subaccount on the exchange. A fill represents a trade that has been executed.

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 account.
`subaccountNumber`	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.
`tickerType`	query	MarketType	false	The type of market to filter by.
`limit`	query	u32	false	Maximum number of asset positions to return in the response.
`createdBeforeOrAtHeight`	query	Height	false	Filters results to positions created at or before a specific blockchain height.
`createdBeforeOrAt`	query	DateTime	false	Filters 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.

API Example

Examples: Guide - Get Fills

Get Historical PNL

Retrieves historical profit and loss (PNL) data for a specific subaccount on the exchange. These records provide insights into the trading performance over time.

Method Declaration

Python

async def get_subaccount_historical_pnls(
    self,
    address: str,
    subaccount_number: int,
    effective_before_or_at: Optional[str] = None,
    effective_at_or_after: Optional[str] = None,
) -> Any

Unification Plan

Parameter created_on_or_after_height is missing
Parameter created_on_or_after is missing

Parameters

Parameter	Location	Type	Required	Description
`address`	query	Address	true	The wallet address that owns the account.
`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.
`createdBeforeOrAtHeight`	query	Height	false	Filters results to positions created at or before a specific blockchain height.
`createdBeforeOrAt`	query	DateTime in UTC	false	Filters results to positions created at or before a specific timestamp (ISO 8601 format).
`createdOnOrAfterHeight`	query	Height	false	Filters results to positions created on or after a specific blockchain height.
`createdOnOrAfter`	query	DateTime in UTC	false	Filters results to positions created on or after a specific timestamp (ISO 8601 format).
`page`	query	u32	false	The page number for paginated results.

Response

Status	Meaning	Schema	Description
`200`	OK	PnlTicksResponseObject ⛁	The historical PnLs data.
`400`	Bad Request		The request was malformed or invalid.
`404`	Not Found		The subaccount was not found.

API Example

Get Rewards

Retrieves historical block trading rewards for the specified address.

Method Declaration

Python

async def get_historical_block_trading_rewards(
    self,
    address: str,
    limit: Optional[int] = None,
) -> Any

Unification Plan

Parameters

Parameter	Location	Type	Required	Description
`address`	path	Address	true	The wallet address that owns the account.
`limit`	query	u32	false	Maximum number of asset positions to return in the response.
`startingBeforeOrAtHeight`	query	Height	false	The timestamp filter for rewards starting before or at.
`startingBeforeOrAt`	query	DateTime in UTC	false	The block height filter for rewards starting before or at.

Response

Status	Meaning	Schema	Description
`200`	OK	HistoricalBlockTradingReward ⛁	The historical block trading rewards data.
`400`	Bad Request		The request was malformed or invalid.

API Example

Get Rewards Aggregated

Retrieves aggregated historical trading rewards for the specified address.

Method Declaration

Python

async def get_historical_trading_rewards_aggregated(
    self,
    address: str,
    period: TradingRewardAggregationPeriod = TradingRewardAggregationPeriod.DAILY,
    limit: Optional[int] = None,
    starting_before_or_at: Optional[str] = None,
    starting_before_or_at_height: Optional[int] = None,
) -> Any

Unification Plan

Parameters

Parameter	Location	Type	Required	Description
`address`	path	Address	true	The wallet address that owns the account.
`period`	query	TradingRewardAggregationPeriod	true	The aggregation period.
`limit`	query	u32	false	The maximum number of aggregated rewards to retrieve.
`startingBeforeOrAt`	query	DateTime	false	The timestamp filter for rewards starting before or at.
`startingBeforeOrAtHeight`	query	Height	false	The block height filter for rewards starting before or at.

Response

Status	Meaning	Schema	Description
`200`	OK	HistoricalTradingRewardAggregation ⛁	The aggregated historical trading rewards data.
`400`	Bad Request		The request was malformed or invalid.

API Example

Get Parent Subaccount

Query for the parent subaccount, its child subaccounts, equity, collateral and margin. See more information on parent subaccounts here.

Method Declaration

Python

async def get_parent_subaccount(
    self,
    address: str,
    subaccount_number: int,
) -> Any

Unification Plan

Parameters

Parameter	Location	Type	Required	Description
`address`	path	Address	true	The wallet address that owns the parent subaccount.
`number`	path	[SubaccountNumber]	true	The identifier for the specific subaccount within the wallet address.

Response

Status	Meaning	Schema	Description
`200`	OK	ParentSubaccountResponseObject ⛁	The parent subaccount data.
`400`	Bad Request		The request was malformed or invalid.
`404`	Not Found		The parent subaccount was not found.

API Example

List Parent Positions

List all positions of a parent subaccount.

Method Declaration

Python

async def list_parent_orders(
    self,
    address: str,
    subaccount_number: int,
    limit: Optional[int] = None,
    ticker: Optional[str] = None,
    side: Optional[OrderSide] = None,
    status: Optional[OrderStatus] = None,
    order_type: Optional[OrderType] = 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 account.
`parentSubaccountNumber`	query	SubaccountNumber	true	Subaccount number of the parent subaccount.
`limit`	query	u32	false	Maximum number of asset positions to return in the response.

Response

Status	Meaning	Schema	Description
`200`	OK	PerpetualPositionResponseObject ⛁	The perpetual positions data.
`400`	Bad Request		The request was malformed or invalid.
`404`	Not Found		The subaccount was not found.

API Example

Get Parent Asset Positions

Query for asset positions (size, buy/sell etc) for a parent subaccount.

Method Declaration

Python

async def get_parent_subaccount_asset_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 account.
`parentSubaccountNumber`	query	SubaccountNumber	true	The parent subaccount number of this wallet

Response

Status	Meaning	Schema	Description
`200`	OK	AssetPositionResponseObject ⛁	The asset positions data.
`400`	Bad Request		The request was malformed or invalid.
`404`	Not Found		The parent subaccount was not found.

API Example

Get Parent Transfers

Query for transfers between subaccounts associated with a parent subaccount.

Method Declaration

Python

async def get_parent_transfers(
    self,
    address: str,
    subaccount_number: int,
    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 parent subaccount.
`parentSubaccountNumber`	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.
`createdBeforeOrAtHeight`	query	Height	false	Restricts results to positions created at or before a specific blockchain height.
`createdBeforeOrAt`	query	DateTime in UTC	false	Restricts results to positions created at or before a specific timestamp (ISO 8601 format).

Response

Status	Meaning	Schema
`200`	OK	TransferResponseObject ⛁

API Example

List Parent Orders

Query for orders filtered by order params of a parent subaccount.

Method Declaration

Python

async def list_parent_orders(
    self,
    address: str,
    subaccount_number: int,
    limit: Optional[int] = None,
    ticker: Optional[str] = None,
    side: Optional[OrderSide] = None,
    status: Optional[OrderStatus] = None,
    order_type: Optional[OrderType] = 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 account.
`parentSubaccountNumber`	query	SubaccountNumber	true	Parent subaccount number
`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.
`goodTilBlockBeforeOrAt`	query	Height	false	The block number filter for orders good until before or at.
`goodTilBlockTimeBeforeOrAt`	query	DateTime in UTC	false	The timestamp filter for orders good until before or at.
`returnLatestOrders`	query	bool	false	Whether to return only the latest orders.

Response

Status	Meaning	Schema	Description
`200`	OK	ListOrdersResponse	The orders data.
`400`	Bad Request		The request was malformed or invalid.
`404`	Not Found		The subaccount was not found.

API Example

Get Parent Fills

Query for fills (i.e. filled orders data) for a parent subaccount.

Method Declaration

Python

async def get_parent_fills(
    self,
    address: str,
    subaccount_number: int,
    limit: Optional[int] = None,
    market: Optional[str] = None,
    market_type: Optional[TickerType] = 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 parent subaccount.
`parentSubaccountNumber`	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.
`createdBeforeOrAtHeight`	query	Height	false	Filters results to positions created at or before a specific blockchain height.
`market`	query	Ticker	false	Market id like USD-BTC, ETH-USD
`marketType`	query	MarketType	false	Market type of filled order Data

Response

Status	Meaning	Schema	Description
`200`	OK	FillResponseObject ⛁	The fills data.
`400`	Bad Request		The request was malformed or invalid.
`404`	Not Found		The parent subaccount was not found.

API Example

Get Parent Historical Pnl

Query for profit and loss report for the specified time/block range of a parent subaccount.

Method Declaration

Python

async def get_parent_historical_pnls(
    self,
    address: str,
    subaccount_number: int,
    limit: Optional[int] = None,
    created_before_or_at_height: Optional[int] = None,
    created_before_or_at: Optional[str] = None,
    created_on_or_after_height: Optional[int] = None,
    created_on_or_after: Optional[str] = None,
) -> Any:

Unification Plan

Parameters

Parameter	Location	Type	Required	Description
`address`	query	Address	true	The wallet address that owns the parent subaccount.
`parentSubaccountNumber`	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.
`createdBeforeOrAtHeight`	query	Height	false	Restricts results to positions created at or before a specific blockchain height.
`createdBeforeOrAt`	query	DateTime in UTC	false	Restricts results to positions created at or before a specific timestamp (ISO 8601 format).
`createdOnOrAfterHeight`	query	Height	false	Restricts results to positions created on or after a specific blockchain height.
`createdOnOrAfter`	query	DateTime in UTC	false	Restricts results to positions created on or after a specific timestamp (ISO 8601 format).

Response

Status	Meaning	Schema	Description
`200`	OK	PnlTicksResponseObject ⛁	The historical PnLs data.
`400`	Bad Request		The request was malformed or invalid.
`404`	Not Found		The parent subaccount was not found.

API Example

Get Funding Payments

Retrieves funding payment history for a specific subaccount. Funding payments are periodic settlements that occur between long and short positions based on the funding rate.

Method Declaration

Python

async def get_funding_payments(
    self,
    address: str,
    subaccount_number: int,
    limit: Optional[int] = None,
    ticker: Optional[str] = None,
    after_or_at: Optional[str] = None,
    page: Optional[int] = None,
) -> Any

Unification Plan

Rename all methods to get_funding_payments - shorter is better.
Add a Subaccount pair to Python and JavaScript, since it's always a pair
page optional parameter is missing in Python
page optional parameter is missing in Rust

Parameters

Parameter	Location	Type	Required	Description
`address`	query	Address	true	The wallet address that owns the account.
`subaccountNumber`	query	SubaccountNumber	true	The identifier for the specific subaccount within the wallet address.
`limit`	query	u32	false	Maximum number of funding payments to return in the response.
`ticker`	query	Ticker	false	The market symbol to filter funding payments by (e.g., "BTC-USD"). If not provided, payments for all markets will be returned.
`afterOrAt`	query	DateTime	false	Filters results to funding payments created at or after a specific timestamp (ISO 8601 format).
`page`	query	u32	false	The page number for paginated results.

Response

A promise that resolves to funding payment data containing details such as payment amount, funding rate, position size, market ticker, and timestamp information.

Status	Meaning	Schema	Description
`200`	OK	FundingPaymentsResponseObject ⛁	The funding payments data.

API Example

Get Funding Payments for Parent Subaccount

Retrieves funding payment history for all subaccounts under a parent subaccount. This endpoint aggregates funding payments across all child subaccounts of a given parent subaccount.

Method Declaration

Python

async def get_funding_payments_for_parent_subaccount(
    self,
    address: str,
    parent_subaccount_number: int,
    limit: Optional[int] = None,
    after_or_at: Optional[str] = None,
    page: Optional[int] = None,
) -> Any

Unification Plan

Rename all methods to get_funding_payments_for_parent_subaccount - shorter is better.
Add a ParentSubaccount pair to Python and JavaScript, since it's always a pair
page optional parameter is missing in Python
page optional parameter is missing in Rust

Parameters

Parameter	Location	Type	Required	Description
`address`	query	Address	true	The wallet address that owns the account.
`parentSubaccountNumber`	query	SubaccountNumber	true	The identifier for the parent subaccount within the wallet address.
`limit`	query	u32	false	Maximum number of funding payments to return in the response.
`afterOrAt`	query	DateTime	false	Filters results to funding payments created at or after a specific timestamp (ISO 8601 format).
`page`	query	u32	false	The page number for paginated results.

Response

A promise that resolves to funding payment data containing details such as payment amount, funding rate, position size, market ticker, and timestamp information aggregated across all child subaccounts.

Status	Meaning	Schema	Description
`200`	OK	FundingPaymentsResponseObject ⛁	The funding payments data.

API Example