dxsp.handler.kwenta.KwentaHandler

class dxsp.handler.kwenta.KwentaHandler(**kwargs)

Bases: DexClient

A DexClient using kwenta-python library

More info Kwenta/kwenta-python-sdk

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 given symbol.
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(sell_address, buy_address, amount)	Constructs the swap transaction data (Not Implemented).
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)

Retrieves a quote for a given symbol.

Parameters:

• buy_address (str, optional) – The buy address. Defaults to None.

• symbol (str, optional) – The symbol to retrieve the quote for.

• None. (Defaults to)

• amount (int, optional) – The amount of the asset to retrieve the quote for.

• 1. (Defaults to)

Returns:

The quote for the specified symbol.

Return type:

float

Raises:

Exception – If an error occurs during the retrieval process.

async make_swap(sell_address, buy_address, amount)

Constructs the swap transaction data (Not Implemented).

This method should interact with the specific DEX protocol’s API or contracts to prepare the transaction parameters for a swap.

Parameters:

• sell_address (str) – Contract address of the token to sell.

• buy_address (str) – Contract address of the token to buy.

• amount (int) – The amount of the sell token in Wei.

Returns:

This method is not yet implemented. Should return the transaction data (e.g., dict for web3 send_transaction).

Return type:

NotImplemented

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.