dxsp.handler.zerox.ZeroxHandler#

class dxsp.handler.zerox.ZeroxHandler(**kwargs)[source]#

Bases: DexClient

A DexClient class using 0x protocol Implementation of 0x swap protocol https://0x.org/docs/0x-swap-api/introduction

Initialize the client

Methods

`calculate_pnl`([period])	Calculates PnL by querying the Rotki reporting endpoint.
`get_account_balance`()	Fetches the native balance (e.g., ETH, BNB) of the client's wallet.
`get_account_margin`()	Fetches the account's margin details (Not Implemented in AccountUtils).
`get_account_open_positions`()	Fetches the account's open positions (Not Implemented in AccountUtils).
`get_account_pnl`([period])	Calculates Profit and Loss (PnL) for the account for a given period.
`get_account_position`()	Fetches the account's overall position (Not Implemented in AccountUtils).
`get_order_amount`(sell_token, wallet_address, ...)	Calculates the order amount in the sell token's base units.
`get_quote`([buy_address, buy_symbol, ...])	Retrieves a quote for a token swap using 0x API v2.
`get_swap`([sell_token, buy_token, quantity])	Executes a swap between two tokens using specified symbols.
`get_trading_asset_balance`()	Fetches the balance of the configured trading_asset_address.
`make_swap`(buy_address, sell_address, amount)	Asynchronously gets a swap order by calling the get_quote method with the specified buy_address, sell_address, and amount parameters.
`replace_instrument`(instrument)	Replaces an instrument symbol using the configured mapping.
`resolve_token`(identifier)	Resolves a token identifier (symbol or address) to token data.

async get_quote(buy_address=None, buy_symbol=None, sell_address=None, sell_symbol=None, amount=1)[source]#

Retrieves a quote for a token swap using 0x API v2.

Parameters:

buy_address (str) – The address of the token to be bought.
buy_symbol (str) – The symbol of the token to be bought.
sell_address (str) – The address of the token to be sold.
sell_symbol (str) – The symbol of the token to be sold.
amount (int, optional) – The amount of tokens to be sold. Defaults to 1.

Returns:

The guaranteed price for the token swap, or None/error message.

Return type:

float

async make_swap(buy_address, sell_address, amount)[source]#

Asynchronously gets a swap order by calling the get_quote method with the specified buy_address, sell_address, and amount parameters. Then, it calls the get_sign method of the account object, passing the swap_order as an argument, and returns the result.

Parameters:

buy_address – The buy address for the swap.
sell_address – The sell address for the swap.
amount – The amount for the swap.

Returns:

The result of calling the get_sign method

of the account object with the swap_order as an argument.

async calculate_pnl(period: str | None = None) → dict | int#

Calculates PnL by querying the Rotki reporting endpoint.

Sends a GET request to the configured rotki_report_endpoint with the optional period parameter. Parses the JSON response to extract and sum ‘free’ amounts from different categories.

Parameters:

period (str | None) – The period string to pass to the Rotki API. Defaults to None.

Returns:

A dictionary containing the sum of ‘free’ PnL values: per category (e.g., ‘trade’, ‘fee’) on success. Returns 0 if the endpoint is not configured, the request fails, or the response format is unexpected.

Return type:

dict | int

async get_account_balance() → str | None#

Fetches the native balance (e.g., ETH, BNB) of the client’s wallet.

Returns:: The native balance as a string, or None if unavailable.
Return type:: str | None

async get_account_margin()#

Fetches the account’s margin details (Not Implemented in AccountUtils).

Returns:: Depends on the implementation in AccountUtils.
Return type:: NotImplemented

async get_account_open_positions()#

Fetches the account’s open positions (Not Implemented in AccountUtils).

Returns:: Depends on the implementation in AccountUtils.
Return type:: NotImplemented

async get_account_pnl(period: str | None = None) → float | dict#

Calculates Profit and Loss (PnL) for the account for a given period.

Delegates the calculation to calculate_pnl if PnL tracking is active. Determines the start date based on the period identifier.

Parameters:

period (str | None) – The period identifier (‘W’ for week, ‘M’ for month, ‘Y’ for year, None for today). Defaults to None (today).

Returns:

The calculated PnL. Returns 0 if PnL is inactive.: The return type depends on calculate_pnl (expected dict or 0).

Return type:

float | dict

async get_account_position()#

Fetches the account’s overall position (Not Implemented in AccountUtils).

Returns:: Depends on the implementation in AccountUtils.
Return type:: NotImplemented

async get_order_amount(sell_token, wallet_address: str, quantity: float | Decimal, is_percentage: bool = True) → Decimal#

Calculates the order amount in the sell token’s base units.

Calculates the amount based on a percentage of the wallet’s balance of the sell_token or a fixed quantity.

Parameters:

sell_token – The ContractData object for the token being sold.
wallet_address (str) – The address of the wallet holding the token.
quantity (float | decimal.Decimal) – The percentage (e.g., 1 for 1%) or the fixed amount of the token to sell.
is_percentage (bool) – If True, quantity is treated as a percentage of the balance. If False, quantity is a fixed amount.

Returns:

The calculated order amount in the token’s base: units, or Decimal(0) if the balance is insufficient or zero.

Return type:

decimal.Decimal

async get_swap(sell_token: str | None = None, buy_token: str | None = None, quantity: float | Decimal = 1) → str#

Executes a swap between two tokens using specified symbols.

Resolves token symbols to addresses, calculates the order amount based on the configured risk settings (percentage or fixed amount), approves the router contract if necessary (e.g., for 0x protocol), constructs and executes the swap transaction, waits for the receipt, and returns a confirmation message or error.

Parameters:

sell_token (str | None) – Symbol of the token to sell (e.g., “WETH”).
buy_token (str | None) – Symbol of the token to buy (e.g., “USDC”).
quantity (float | decimal.Decimal) – The quantity or percentage to swap, interpreted based on trading_risk_percentage vs trading_risk_amount settings. Defaults to 1 (interpreted based on config).

Returns:

A confirmation message with the transaction hash on success,: or an error message string starting with “⚠️” on failure.

Return type:

str

async get_trading_asset_balance() → str | None#

Fetches the balance of the configured trading_asset_address.

Returns:

The trading asset balance as a string, or None if: unavailable or not configured.

Return type:

str | None

async replace_instrument(instrument: str) → str#

Replaces an instrument symbol using the configured mapping.

Checks if the self.mapping list contains an entry for the given instrument and returns the corresponding alternative symbol (alt) if found and enabled. Otherwise, returns the original instrument.

Parameters:

instrument (str) – The instrument symbol to potentially replace.

Returns:

The replaced instrument symbol or the original symbol if no: mapping is found or applicable.

Return type:

str

async resolve_token(identifier: str)#

Resolves a token identifier (symbol or address) to token data.

Uses ContractUtils to fetch token information based on whether the identifier is recognized as a contract address (starts with ‘0x’) or a token symbol. Applies instrument mapping if applicable.

Parameters:

identifier (str) – The token symbol (e.g., “WETH”) or contract address (e.g., “0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2”).

Returns:

An object containing token details (address, symbol,: decimals, ABI, etc.) from ContractUtils.

Return type:

ContractData

Raises:

ValueError – If the token identifier cannot be resolved.