Avantis Trader SDK

https://sdk.avantisfi.com/
Admin
Avantis Trader SDK is a powerful toolkit for trading on the Avantis platform, providing...
Tokens:97,120
Snippets:740
Trust Score:8.7
Update:3 months ago
Show doc for...
Tokens:
Raw
### Full Trader Client Configuration Example

Source: https://sdk.avantisfi.com/_sources/configuration.rst.txt

A complete example demonstrating the setup of the TraderClient, including necessary imports and configuration for trading.

```python
from avantis_trader_sdk import TraderClient, FeedClient
from avantis_trader_sdk.types import TradeInput

import avantis_trader_sdk

# Trader client configuration (used for getting trade related parameters)
provider_url = "https://mainnet.base.org" # Replace with the provider URL for the Base Mainnet Chain
trader_client = TraderClient(provider_url)
```

--------------------------------

### Full Feed Client Configuration Example

Source: https://sdk.avantisfi.com/_sources/configuration.rst.txt

A comprehensive example showing the setup of the FeedClient, including WebSocket URL, error handlers, and price feed callbacks.

```python
from avantis_trader_sdk import TraderClient, FeedClient
from avantis_trader_sdk.types import TradeInput

import avantis_trader_sdk

# Trader client configuration (used for getting trade related parameters)
provider_url = "https://mainnet.base.org" # Replace with the provider URL for the Base Mainnet Chain
trader_client = TraderClient(provider_url)

# Real-time price feed configuration (used for getting real-time prices of the pairs)
# **This can be skipped if you don't need real-time price updates**
ws_url = "wss://<YOUR-WEBSOCKET-ENDPOINT>"

def ws_error_handler(e):
    print(f"Websocket error: {e}")

feed_client = FeedClient(
    ws_url, on_error=ws_error_handler, on_close=ws_error_handler
)

feed_client.register_price_feed_callback(
    "0xff61491a931112ddf1bd8147cd1b641375f79f5825126d665480874634fd0ace",
    lambda data: print(data),
)

feed_client.register_price_feed_callback("ETH/USD", lambda data: print(data))

await feed_client.listen_for_price_updates()

def ws_error_handler(e):
    print(f"Websocket error: {e}")
```

--------------------------------

### Install Avantis Trader SDK from GitHub

Source: https://sdk.avantisfi.com/_sources/getting_started.rst.txt

Install the SDK directly from its GitHub repository using pip. This is useful for getting the latest development version.

```bash
pip install git+https://github.com/Avantis-Labs/avantis_trader_sdk.git
```

--------------------------------

### Delegate Trading Workflow Example

Source: https://sdk.avantisfi.com/_sources/changelog.rst.txt

Demonstrates the full workflow for setting up and managing delegate trading. This includes getting the current delegate, building transactions to set or remove a delegate, and managing trades on behalf of another trader.

```python
from avantis_trader_sdk.sdk import AvantisTraderSDK
from avantis_trader_sdk.config import Config

# Initialize SDK
config = Config(core_api_base_url="https://api.avantisfi.com")

# Trader and delegate addresses
trader = "0x123...abc"
new_delegate = "0x456...def"

# Initialize SDK
# sdk = AvantisTraderSDK(config=config)

# Get current delegate
# current_delegate = sdk.get_delegate(trader=trader)
# print(f"Current delegate for {trader}: {current_delegate}")

# Build transaction to set a new delegate
# set_delegate_tx = sdk.build_set_delegate_tx(delegate=new_delegate, trader=trader)
# print(f"Set delegate transaction: {set_delegate_tx}")

# Build transaction to remove the delegate
# remove_delegate_tx = sdk.build_remove_delegate_tx(trader=trader)
# print(f"Remove delegate transaction: {remove_delegate_tx}")

```

--------------------------------

### Install Avantis Trader SDK using pip

Source: https://sdk.avantisfi.com/_sources/getting_started.rst.txt

Install the SDK package directly from PyPI using pip. Ensure Python 3.6+ is installed.

```bash
pip install avantis-trader-sdk
```

--------------------------------

### Install Avantis Trader SDK from Local Source

Source: https://sdk.avantisfi.com/_sources/getting_started.rst.txt

Install the SDK from a local clone of the repository. This method is useful for development or when contributing to the SDK.

```bash
git clone https://github.com/yourusername/avantis-trader-sdk.git
cd avantis-trader-sdk
pip install .
```

--------------------------------

### Get Latest Price Example (Feed-v3)

Source: https://sdk.avantisfi.com/_sources/changelog.rst.txt

Demonstrates using the feed-v3 API to get the latest price for a given pair index. This method is part of the simplified price sourcing updates.

```python
from avantis_trader_sdk.sdk import AvantisTraderSDK
from avantis_trader_sdk.config import Config

# Initialize SDK
config = Config(core_api_base_url="https://api.avantisfi.com")
# sdk = AvantisTraderSDK(config=config)

# Example pair index
pair_index = 0

# Get latest price using feed-v3
# latest_price = sdk.get_price_update_data(pair_index=pair_index)
# print(f"Latest price for pair {pair_index} (feed-v3): {latest_price}")

```

--------------------------------

### Verify Avantis Trader SDK Installation

Source: https://sdk.avantisfi.com/_sources/getting_started.rst.txt

Check if the Avantis Trader SDK is installed correctly by importing it and printing its version number. This confirms the installation was successful.

```python
import avantis_trader_sdk
print(avantis_trader_sdk.__version__)
```

--------------------------------

### Start Listening for Price Updates

Source: https://sdk.avantisfi.com/_sources/configuration.rst.txt

Initiate the process of listening for real-time price updates from the configured WebSocket endpoint.

```python
await feed_client.listen_for_price_updates()
```

--------------------------------

### Fetch Trading Pair Information

Source: https://sdk.avantisfi.com/_sources/getting_started.rst.txt

An asynchronous example demonstrating how to initialize the TraderClient and retrieve information about available trading pairs. Requires Python 3.6+ and asyncio.

```python
import asyncio
from avantis_trader_sdk import TraderClient, __version__

import avantis_trader_sdk

print(avantis_trader_sdk.__version__)


async def main():
   provider_url = "https://mainnet.base.org"
   trader_client = TraderClient(provider_url)

   print("----- GETTING PAIR INFO -----")
   result = await trader_client.pairs_cache.get_pairs_info()
   print(result)


if __name__ == "__main__":
   asyncio.run(main())
```

--------------------------------

### Get Delegate Example

Source: https://sdk.avantisfi.com/_sources/changelog.rst.txt

Retrieves the current delegate address assigned to a specific trader. This is useful for understanding who is authorized to trade on behalf of the trader.

```python
from avantis_trader_sdk.sdk import AvantisTraderSDK
from avantis_trader_sdk.config import Config

# Initialize SDK
config = Config(core_api_base_url="https://api.avantisfi.com")
# sdk = AvantisTraderSDK(config=config)

# Trader address
trader = "0x123...abc"

# Get the delegate for the trader
# delegate = sdk.get_delegate(trader=trader)
# print(f"Delegate for {trader}: {delegate}")

```

--------------------------------

### Get Price Update Data Example

Source: https://sdk.avantisfi.com/_sources/changelog.rst.txt

Fetches price update data from the feed-v3 API for a given pair index. This is used to retrieve current pricing information for trading pairs.

```python
from avantis_trader_sdk.sdk import AvantisTraderSDK
from avantis_trader_sdk.config import Config

# Initialize SDK
config = Config(core_api_base_url="https://api.avantisfi.com")
# sdk = AvantisTraderSDK(config=config)

# Example pair index
pair_index = 0

# Fetch price update data
# price_update_data = sdk.get_price_update_data(pair_index=pair_index)
# print(f"Price update data for pair {pair_index}: {price_update_data}")

```

--------------------------------

### Get Gas Price

Source: https://sdk.avantisfi.com/_modules/avantis_trader_sdk/client.html

Fetches the current recommended gas price from the network.

```python
async def get_gas_price(self):
        """
        Gets the gas price.

        Returns:
            The gas price.
        """
        return await self.async_web3.eth.gas_price
```

--------------------------------

### Get Opening Fees for All Pairs (Long)

Source: https://sdk.avantisfi.com/get_information_and_parameters.html

Fetch the opening fees for all available trading pairs for a long position. Omit the 'pair' parameter.

```python
opening_fee = await trader_client.fee_parameters.get_opening_fee(position_size=1000, is_long=True)
print("Opening Fee for all pairs (Long):", opening_fee.long)
```

--------------------------------

### Get Opening Fees for All Pairs (Long and Short)

Source: https://sdk.avantisfi.com/get_information_and_parameters.html

Obtain both long and short opening fees for all trading pairs. Omit both 'is_long' and 'pair' parameters.

```python
opening_fee = await trader_client.fee_parameters.get_opening_fee(position_size=1000)
print("Opening Fee for all pairs (Long):", opening_fee.long)
print("Opening Fee for all pairs (Short):", opening_fee.short)
```

--------------------------------

### listen_for_price_updates

Source: https://sdk.avantisfi.com/_sources/get_information_and_parameters.rst.txt

Starts listening for real-time price updates from the Pyth price feed websocket. All registered callbacks for received price feeds will be invoked.

```APIDOC
## listen_for_price_updates

### Description
Listens for real-time price updates from the Pyth price feed websocket. When a price update is received, all registered callbacks for that price feed are called with the updated price data.

### Method
listen_for_price_updates

### Raises
- **Exception**: If an error occurs while listening for price updates.

### Request Example
```python
async def price_update_callback(data):
    print("Price Update:", data)

feed_client.register_price_feed_callback("ETH/USD", price_update_callback)
await feed_client.listen_for_price_updates()
```

### Notes
- This method is an asynchronous coroutine and should be called using ``await`` in an asynchronous context.
- The registered callbacks will be called with an instance of :class:`~avantis_trader_sdk.types.PriceFeedResponse`, which contains the updated price data for the subscribed price feed.
- If the websocket connection is closed due to an error, the registered ``on_close`` callback will be called with the exception, if provided. Otherwise, the exception will be printed.
- If any other exception occurs during the listening process, the registered ``on_error`` callback will be called with the exception, if provided. Otherwise, the exception will be re-raised.
```

--------------------------------

### Get Open Fee Parameters

Source: https://sdk.avantisfi.com/_modules/avantis_trader_sdk/rpc/fee_parameters.html

Retrieves open fee parameters from the PriceAggregator contract. Ensure the client and contract are properly initialized.

```python
PriceAggregator = self.client.contracts.get("PriceAggregator")

response = await PriceAggregator.functions.openFeeP(
    trade_input.pairIndex, position_size, trade_input.buy
).call()

referral_rebate_percentage = (
    await self.client.trading_parameters.get_trade_referral_rebate_percentage(
        trade_input.trader
    )
)
referral_rebate_percentage = 1 - (referral_rebate_percentage / 100)
return round(
    response / 10**12 * position_size / 10**6 * referral_rebate_percentage,
    18,
)
```

--------------------------------

### Send Raw Transaction and Get Hash

Source: https://sdk.avantisfi.com/_modules/avantis_trader_sdk/client.html

Sends a pre-signed raw transaction to the network and returns its hash.

```python
async def send_and_get_transaction_hash(self, signed_txn):
        """
        Gets the transaction hash.

        Args:
            signed_txn: The signed transaction object.

        Returns:
            The transaction hash.
        """
        return await self.async_web3.eth.send_raw_transaction(signed_txn.rawTransaction)
```

--------------------------------

### Get Opening Fee for Specific Pair and Direction

Source: https://sdk.avantisfi.com/get_information_and_parameters.html

Calculate the opening fee for a specific trading pair and direction (long or short). Requires position size, direction, and pair.

```python
opening_fee = await trader_client.fee_parameters.get_opening_fee(position_size=1000, is_long=True, pair="ETH/USD")
print("Opening Fee for ETH/USD (Long):", opening_fee.long["ETH/USD"])
```

--------------------------------

### Get Opening Fees for Specific Pair (Long and Short)

Source: https://sdk.avantisfi.com/get_information_and_parameters.html

Retrieve both long and short opening fees for a specified trading pair. Omit the 'is_long' parameter.

```python
opening_fee = await trader_client.fee_parameters.get_opening_fee(position_size=1000, pair="ETH/USD")
print("Opening Fee for ETH/USD (Long):", opening_fee.long["ETH/USD"])
print("Opening Fee for ETH/USD (Short):", opening_fee.short["ETH/USD"])
```

--------------------------------

### Get Lazer Feed ID Example

Source: https://sdk.avantisfi.com/_sources/changelog.rst.txt

Retrieves the Pyth Lazer feed ID associated with a specific trading pair index. This ID is necessary for fetching Lazer prices for that pair.

```python
from avantis_trader_sdk.sdk import AvantisTraderSDK
from avantis_trader_sdk.config import Config

# Initialize SDK
config = Config(core_api_base_url="https://api.avantisfi.com")
# sdk = AvantisTraderSDK(config=config)

# Example pair index
pair_index = 0

# Get Lazer feed ID for the pair
# lazer_feed_id = sdk.get_lazer_feed_id(pair_index=pair_index)
# print(f"Lazer feed ID for pair {pair_index}: {lazer_feed_id}")

```

--------------------------------

### Get Latest Lazer Price Example

Source: https://sdk.avantisfi.com/_sources/changelog.rst.txt

Fetches the latest prices from the Pyth Lazer API using a list of feed IDs. This method is used for obtaining real-time price data for trading operations.

```python
from avantis_trader_sdk.sdk import AvantisTraderSDK
from avantis_trader_sdk.config import Config

# Initialize SDK
config = Config(core_api_base_url="https://api.avantisfi.com")
# sdk = AvantisTraderSDK(config=config)

# Example Lazer feed IDs
lazer_feed_ids = [
    "0x123...abc",
    "0x456...def",
]

# Fetch latest Lazer prices
# latest_lazer_prices = sdk.get_latest_lazer_price(lazer_feed_ids=lazer_feed_ids)
# print(f"Latest Lazer prices: {latest_lazer_prices}")

```

--------------------------------

### Listen for Lazer Price Updates Example

Source: https://sdk.avantisfi.com/_sources/changelog.rst.txt

Sets up a Server-Sent Events (SSE) stream to receive real-time Pyth Pro prices with low latency. A callback function is executed for each price update received.

```python
from avantis_trader_sdk.sdk import AvantisTraderSDK
from avantis_trader_sdk.config import Config

# Initialize SDK
config = Config(core_api_base_url="https://api.avantisfi.com")
# sdk = AvantisTraderSDK(config=config)

# Example Lazer feed IDs
lazer_feed_ids = [
    "0x123...abc",
    "0x456...def",
]

def price_update_callback(data):
    print(f"Received price update: {data}")

# Start listening for Lazer price updates
# sdk.listen_for_lazer_price_updates(lazer_feed_ids=lazer_feed_ids, callback=price_update_callback)

```

--------------------------------

### Get Trading Pair from Feed ID

Source: https://sdk.avantisfi.com/_sources/get_information_and_parameters.rst.txt

Retrieves the trading pair string for a given feed ID. The feed ID should be a hexadecimal string. If the feed ID does not start with "0x", it will be automatically prefixed.

```python
pair_string = feed_client.get_pair_from_feed_id("0x09f7c1d7dfbb7df2b8fe3d3d87ee94a2259d212da4f30c1f0540d066dfa44723")
print("Pair String:", pair_string)
```

--------------------------------

### Configure Feed Client

Source: https://sdk.avantisfi.com/configuration.html

Instantiate the FeedClient with a WebSocket URL for real-time price feeds. Optional callbacks for error and close events can be provided.

```python
ws_url = "wss://<YOUR-WEBSOCKET-ENDPOINT>"

feed_client = FeedClient(
    ws_url, on_error=ws_error_handler, on_close=ws_error_handler
)
```

--------------------------------

### LocalSigner Initialization

Source: https://sdk.avantisfi.com/_modules/avantis_trader_sdk/signers/local_signer.html

Initializes the LocalSigner with a private key and an asynchronous Web3 instance. This is used to set up the signer for transaction operations.

```python
from web3 import AsyncWeb3
from .base import BaseSigner




class LocalSigner(BaseSigner):
    def __init__(self, private_key, async_web3: AsyncWeb3):
        self.private_key = private_key
        self.async_web3 = async_web3

```

--------------------------------

### TraderClient Initialization

Source: https://sdk.avantisfi.com/_modules/avantis_trader_sdk/client.html

Initializes the `TraderClient` with necessary provider URLs and an optional signer or feed client. It sets up web3 instances, loads contracts, and initializes various RPC clients for interacting with different aspects of the Avantis protocol.

```APIDOC
## TraderClient

### Description
This class provides methods to interact with the Avantis smart contracts.

### Constructor
```python
def __init__(
    self,
    provider_url,
    l1_provider_url="https://eth.llamarpc.com",
    signer: BaseSigner = None,
    feed_client: FeedClient = None,
):
```

#### Arguments
* `provider_url` (string) - The URL of the Ethereum node provider.
* `l1_provider_url` (string, optional) - The URL of the L1 Ethereum node provider. Defaults to "https://eth.llamarpc.com". Note: This argument is deprecated.
* `signer` (BaseSigner, optional) - The signer to use for signing transactions.
* `feed_client` (FeedClient, optional) - The feed client to use for real-time data feeds.
```

--------------------------------

### Place Limit Order with TraderClient

Source: https://sdk.avantisfi.com/trade.html

Use this snippet to place a limit order. Ensure the TraderClient is initialized and the local signer is set. The order will only execute if the market reaches the specified open_price.

```python
import asyncio
from avantis_trader_sdk import TraderClient, TradeInput, TradeInputOrderType

private_key = "0xmyprivatekey"

async def main():
    # Initialize TraderClient
    provider_url = "https://mainnet.base.org"  # Find provider URL for Base Mainnet Chain from https://chainlist.org/chain/8453 or use a dedicated node (Alchemy, Infura, etc.)
    trader_client = TraderClient(provider_url)

    # Set local signer
    trader_client.set_local_signer(private_key) # Alternatively, you can use set_aws_kms_signer() to use a key from AWS KMS or create your own signer by inheriting BaseSigner class

    trader = trader_client.get_signer().get_ethereum_address()

    # Get trader's USDC balance
    balance = await trader_client.get_usdc_balance(trader)
    print(f"Balance of {trader} is {balance} USDC")

    # Check allowance of USDC
    allowance = await trader_client.get_usdc_allowance_for_trading(trader)
    print(f"Allowance of {trader} is {allowance} USDC")

    amount_of_collateral = 10

    if allowance < amount_of_collateral:
        print(f"Allowance of {trader} is less than {amount_of_collateral} USDC. Approving...")
        await trader_client.approve_usdc_for_trading(amount_of_collateral)
        allowance = await trader_client.get_usdc_allowance_for_trading(trader)
        print(f"New allowance of {trader} is {allowance} USDC")

    # Get pair index of the pair. For example, ETH/USD
    pair_index_of_eth_usd = await trader_client.pairs_cache.get_pair_index("ETH/USD")

    # Prepare trade input
    trade_input = TradeInput(
        trader=trader,  # Trader's wallet address
        open_price=1500,  # Open price of the trade (Desired execution price)
        pair_index=pair_index_of_eth_usd,  # Pair index
        collateral_in_trade=amount_of_collateral,  # Amount of collateral in trade (in USDC)
        is_long=True,  # True for long, False for short
        leverage=25,  # Leverage for the trade
        index=0,  # This is the index of the trade for a pair (0 for the first trade, 1 for the second, etc.)
        tp=4000.5,  # Take profit price. Max allowed is 500% of open price.
        sl=0,  # Stop loss price
        timestamp=0,  # Timestamp of the trade. 0 for now
    )

    # ---------------------------------------------
    # Get opening fee data
    opening_fee_usdc = await trader_client.fee_parameters.get_opening_fee(
        trade_input=trade_input
    )
    print(f"Opening fee for this trade: {opening_fee_usdc} USDC")

    # Get loss protection percentage
    loss_protection_info = (
        await trader_client.trading_parameters.get_loss_protection_for_trade_input(
            trade_input, opening_fee_usdc=opening_fee_usdc
        )
    )
    print(f"Loss protection percentage for this trade: {loss_protection_info.percentage}%")
    print(f"You'll receive up to ${loss_protection_info.amount} as a loss rebate if the trade goes against you.")
    # ---------------------------------------------

    # 1% slippage
    slippage_percentage = 1

    # Order type for the trade (LIMIT in this case)
    trade_input_order_type = TradeInputOrderType.LIMIT

    # Open trade as a limit order
    open_transaction = await trader_client.trade.build_trade_open_tx(
        trade_input, trade_input_order_type, slippage_percentage
    )

    receipt = await trader_client.sign_and_get_receipt(open_transaction)

    print(receipt)
    print("Order placed successfully!")

# Run the example
asyncio.run(main())

```

--------------------------------

### Get Trading Parameter Snapshot

Source: https://sdk.avantisfi.com/_sources/get_information_and_parameters.rst.txt

Retrieves the current snapshot of trading parameters, including open interest, asset utilization, and skew. Use this to get a comprehensive view of the current market state.

```python
snapshot = await trader_client.snapshot.get_snapshot()
print("Snapshot:", snapshot)
```

--------------------------------

### Open a Market Trade

Source: https://sdk.avantisfi.com/_sources/trade.rst.txt

Use this snippet to open a new market trade. It includes initializing the TraderClient, setting up trade parameters, calculating fees, and submitting the transaction. Ensure you have sufficient USDC allowance for the trade.

```python
import asyncio
from avantis_trader_sdk import TraderClient, TradeInput, TradeInputOrderType

private_key = "0xmyprivatekey"

async def main():
    # Initialize TraderClient
    provider_url = "https://mainnet.base.org"  # Find provider URL for Base Mainnet Chain from https://chainlist.org/chain/8453 or use a dedicated node (Alchemy, Infura, etc.)
    trader_client = TraderClient(provider_url)

    # Set local signer
    trader_client.set_local_signer(private_key) # Alternatively, you can use set_aws_kms_signer() to use a key from AWS KMS or create your own signer by inheriting BaseSigner class

    trader = trader_client.get_signer().get_ethereum_address()

    # Check allowance of USDC
    allowance = await trader_client.get_usdc_allowance_for_trading(trader)
    print(f"Allowance of {trader} is {allowance} USDC")
   
    amount_of_collateral = 10

    if allowance < amount_of_collateral:
     print(f"Allowance of {trader} is less than {amount_of_collateral} USDC. Approving...")
     await trader_client.approve_usdc_for_trading(amount_of_collateral)
     allowance = await trader_client.get_usdc_allowance_for_trading(trader)
     print(f"New allowance of {trader} is {allowance} USDC")

    # Get pair index of the pair. For example, ETH/USD
    pair_index_of_eth_usd = await trader_client.pairs_cache.get_pair_index("ETH/USD")

    # Prepare trade input
    trade_input = TradeInput(
        trader=trader,  # Trader's wallet address
        open_price=None,  # (Optional) Open price of the trade. Current price in case of Market orders. If None then it will default to the current price
        pair_index=pair_index_of_eth_usd,  # Pair index
        collateral_in_trade=amount_of_collateral,  # Amount of collateral in trade (in USDC)
        is_long=True,  # True for long, False for short
        leverage=25,  # Leverage for the trade
        index=0,  # This is the index of the trade for a pair (0 for the first trade, 1 for the second, etc.)
        tp=4000.5,  # Take profit price. Max allowed is 500% of open price.
        sl=0,  # Stop loss price
        timestamp=0,  # Timestamp of the trade. 0 for now
    )

    # ---------------------------------------------
    # Get opening fee data
    # Read more: https://docs.avantisfi.com/trading/trading-fees/crypto#dynamic-opening-fee-0.04-0.1-position-size
    opening_fee_usdc = await trader_client.fee_parameters.get_opening_fee(
        trade_input=trade_input
    )
    print(f"Opening fee for this trade: {opening_fee_usdc} USDC")

    # Get loss protection percentage
    # Read more: https://docs.avantisfi.com/rewards/loss-protection
    loss_protection_info = (
        await trader_client.trading_parameters.get_loss_protection_for_trade_input(
            trade_input, opening_fee_usdc=opening_fee_usdc
        )
    )
    print(
        f"Loss protection percentage for this trade: {loss_protection_info.percentage}%"
    )
    print(
        f"You'll receive up to ${loss_protection_info.amount} as a loss rebate if the trade goes against you."
    )
    # ---------------------------------------------

    # 1% slippage
    slippage_percentage = 1

    # Order type for the trade (MARKET or LIMIT or STOP_LIMIT or MARKET_ZERO_FEE)
    trade_input_order_type = TradeInputOrderType.MARKET

    # Open trade
    open_transaction = await trader_client.trade.build_trade_open_tx(
        trade_input, trade_input_order_type, slippage_percentage
    )

    receipt = await trader_client.sign_and_get_receipt(open_transaction)

    print(receipt)
    print("Trade opened successfully!")

# Run the example
asyncio.run(main())

```

--------------------------------

### Get Price Impact Spread for a Specific Pair and Direction

Source: https://sdk.avantisfi.com/get_information_and_parameters.html

Use this snippet to get the price impact spread for a specific trading pair and trade direction (long or short). Ensure `position_size`, `is_long`, and `pair` are provided.

```python
price_impact_spread = await trader_client.asset_parameters.get_price_impact_spread(position_size=1000, is_long=True, pair="ETH/USD")
print("Price Impact Spread for ETH/USD (Long):", price_impact_spread.long["ETH/USD"])
```

--------------------------------

### Initialize TraderClient

Source: https://sdk.avantisfi.com/_modules/avantis_trader_sdk/client.html

Constructor for the TraderClient class. Initializes web3 instances, loads contracts, and sets up RPC clients.

```python
from pathlib import Path
from web3 import Web3, AsyncWeb3
from .config import CONTRACT_ADDRESSES
from .rpc.pairs_cache import PairsCache
from .rpc.asset_parameters import AssetParametersRPC
from .rpc.category_parameters import CategoryParametersRPC
from .rpc.blended import BlendedRPC
from .rpc.fee_parameters import FeeParametersRPC
from .rpc.trading_parameters import TradingParametersRPC
from .rpc.snapshot import SnapshotRPC
from .rpc.trade import TradeRPC
from .utils import decoder
from .feed.feed_client import FeedClient

from .signers.base import BaseSigner
from .signers.local_signer import LocalSigner
from .signers.kms_signer import KMSSigner




class TraderClient:
    """
    This class provides methods to interact with the Avantis smart contracts.
    """

    def __init__(
        self,
        provider_url,
        l1_provider_url="https://eth.llamarpc.com",
        signer: BaseSigner = None,
        feed_client: FeedClient = None,
    ):
        """
        Constructor for the TraderClient class.

        Args:
            provider_url: The URL of the Ethereum node provider.
            l1_provider_url (optional): The URL of the L1 Ethereum node provider.
            signer (optional): The signer to use for signing transactions.
        """
        if l1_provider_url != "https://eth.llamarpc.com":
            print(
                " ⚠️ Warning: l1_provider_url is deprecated and will be removed in the future."
            )

        self.web3 = Web3(
            Web3.HTTPProvider(provider_url, request_kwargs={"timeout": 60})
        )
        self.async_web3 = AsyncWeb3(
            AsyncWeb3.AsyncHTTPProvider(provider_url, request_kwargs={"timeout": 60})
        )

        self.contracts = self.load_contracts()
        self.chain_id = self.web3.eth.chain_id

        self.utils = {
            "decoder": lambda *args, **kwargs: decoder(self.web3, *args, **kwargs)
        }

        self.pairs_cache = PairsCache(self)
        self.asset_parameters = AssetParametersRPC(self)
        self.category_parameters = CategoryParametersRPC(self)
        self.blended = BlendedRPC(self)
        self.fee_parameters = FeeParametersRPC(self)
        self.trading_parameters = TradingParametersRPC(self)
        self.snapshot = SnapshotRPC(self)
        self.feed_client = feed_client or FeedClient()
        self.trade = TradeRPC(self, self.feed_client)

        self.signer = signer

```

--------------------------------

### get_balance

Source: https://sdk.avantisfi.com/avantis_trader_sdk.html

Gets the balance for a given address. This method is asynchronous.

```APIDOC
## async get_balance(_address =None_)

Gets the balance.

Parameters:
    
**address** (_optional_) – The address.

Returns:
    
The balance.
```

--------------------------------

### get_usdc_allowance_for_trading

Source: https://sdk.avantisfi.com/_modules/avantis_trader_sdk/client.html

Gets the USDC allowance for the Trading Storage contract.

```APIDOC
## get_usdc_allowance_for_trading

### Description
Gets the USDC allowance for the Trading Storage contract.

### Method
`get_usdc_allowance_for_trading(address=None)`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response
- **allowance** (int) - The amount of USDC allowed to be spent by the Trading Storage contract.

#### Response Example
None
```

--------------------------------

### Initialize KMSSigner

Source: https://sdk.avantisfi.com/_modules/avantis_trader_sdk/signers/kms_signer.html

Initializes the KMSSigner with a Web3 instance, KMS key ID, and optional AWS region. It automatically retrieves the associated Ethereum address.

```python
def __init__(self, web3, kms_key_id, region_name="us-east-1"):
    self._web3 = web3
    self._key_id = kms_key_id
    self._kms_client = boto3.client("kms", region_name)
    self.address = self.get_public_key()
```

--------------------------------

### get_balance

Source: https://sdk.avantisfi.com/_modules/avantis_trader_sdk/client.html

Gets the native currency balance for a given address.

```APIDOC
## get_balance

### Description
Gets the native currency balance for a given address.

### Method
`get_balance(address=None)`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response
- **balance** (float) - The balance in ETH (or native currency).

#### Response Example
None
```

--------------------------------

### Calculate Opening Fee and Loss Protection

Source: https://sdk.avantisfi.com/_sources/trade.rst.txt

Use these methods to determine the opening fee in USDC and the loss protection percentage and amount for a trade before execution. The opening fee is optional when calculating loss protection as it can be computed internally.

```python
opening_fee_usdc = await trader_client.fee_parameters.get_opening_fee(
        trade_input=trade_input
    )
print(f"Opening fee for this trade: {opening_fee_usdc} USDC")

loss_protection_info = (
        await trader_client.trading_parameters.get_loss_protection_for_trade_input(
            trade_input, opening_fee_usdc=opening_fee_usdc # Opening fee is optional (it will be calculated if not provided)
        )
    )
print(f"Loss protection percentage for this trade: {loss_protection_info.percentage}%")
print(f"You'll receive up to ${loss_protection_info.amount} as a loss rebate if the trade goes against you.")
```

--------------------------------

### Get Chain ID

Source: https://sdk.avantisfi.com/_modules/avantis_trader_sdk/client.html

Retrieves the network's chain ID.

```python
async def get_chain_id(self):
        """
        Gets the chain id.

        Returns:
            The chain id.
        """
        return await self.async_web3.eth.chain_id
```

--------------------------------

### Open Market Trade

Source: https://sdk.avantisfi.com/trade.html

This snippet demonstrates how to open a market trade using the Avantis SDK. It includes initializing the client, setting up trade inputs, calculating fees, and submitting the transaction. Ensure you have the necessary private key and provider URL.

```python
import asyncio
from avantis_trader_sdk import TraderClient, TradeInput, TradeInputOrderType

private_key = "0xmyprivatekey"

async def main():
    # Initialize TraderClient
    provider_url = "https://mainnet.base.org"  # Find provider URL for Base Mainnet Chain from https://chainlist.org/chain/8453 or use a dedicated node (Alchemy, Infura, etc.)
    trader_client = TraderClient(provider_url)

    # Set local signer
    trader_client.set_local_signer(private_key) # Alternatively, you can use set_aws_kms_signer() to use a key from AWS KMS or create your own signer by inheriting BaseSigner class

    trader = trader_client.get_signer().get_ethereum_address()

    # Check allowance of USDC
    allowance = await trader_client.get_usdc_allowance_for_trading(trader)
    print(f"Allowance of {trader} is {allowance} USDC")

    amount_of_collateral = 10

    if allowance < amount_of_collateral:
     print(f"Allowance of {trader} is less than {amount_of_collateral} USDC. Approving...")
     await trader_client.approve_usdc_for_trading(amount_of_collateral)
     allowance = await trader_client.get_usdc_allowance_for_trading(trader)
     print(f"New allowance of {trader} is {allowance} USDC")

    # Get pair index of the pair. For example, ETH/USD
    pair_index_of_eth_usd = await trader_client.pairs_cache.get_pair_index("ETH/USD")

    # Prepare trade input
    trade_input = TradeInput(
        trader=trader,  # Trader's wallet address
        open_price=None,  # (Optional) Open price of the trade. Current price in case of Market orders. If None then it will default to the current price
        pair_index=pair_index_of_eth_usd,  # Pair index
        collateral_in_trade=amount_of_collateral,  # Amount of collateral in trade (in USDC)
        is_long=True,  # True for long, False for short
        leverage=25,  # Leverage for the trade
        index=0,  # This is the index of the trade for a pair (0 for the first trade, 1 for the second, etc.)
        tp=4000.5,  # Take profit price. Max allowed is 500% of open price.
        sl=0,  # Stop loss price
        timestamp=0,  # Timestamp of the trade. 0 for now
    )

    # ---------------------------------------------
    # Get opening fee data
    # Read more: https://docs.avantisfi.com/trading/trading-fees/crypto#dynamic-opening-fee-0.04-0.1-position-size
    opening_fee_usdc = await trader_client.fee_parameters.get_opening_fee(
        trade_input=trade_input
    )
    print(f"Opening fee for this trade: {opening_fee_usdc} USDC")

    # Get loss protection percentage
    # Read more: https://docs.avantisfi.com/rewards/loss-protection
    loss_protection_info = (
        await trader_client.trading_parameters.get_loss_protection_for_trade_input(
            trade_input, opening_fee_usdc=opening_fee_usdc
        )
    )
    print(
        f"Loss protection percentage for this trade: {loss_protection_info.percentage}%"
    )
    print(
        f"You'll receive up to ${loss_protection_info.amount} as a loss rebate if the trade goes against you."
    )
    # ---------------------------------------------

    # 1% slippage
    slippage_percentage = 1

    # Order type for the trade (MARKET or LIMIT or STOP_LIMIT or MARKET_ZERO_FEE)
    trade_input_order_type = TradeInputOrderType.MARKET

    # Open trade
    open_transaction = await trader_client.trade.build_trade_open_tx(
        trade_input, trade_input_order_type, slippage_percentage
    )

    receipt = await trader_client.sign_and_get_receipt(open_transaction)

    print(receipt)
    print("Trade opened successfully!")

# Run the example
asyncio.run(main())

```

--------------------------------

### Get Pair Index

Source: https://sdk.avantisfi.com/_sources/get_information_and_parameters.rst.txt

Retrieves the blockchain index for a specific trading pair.

```APIDOC
## Get Pair Index

### Description
The ``get_pair_index`` method retrieves the index of a trading pair from the blockchain. The index is used to identify the trading pair in the blockchain.

### Parameters
#### Path Parameters
- **pair** (str): The trading pair to retrieve the index for. Expects a string in the format "from/to".

### Returns
- The index of the pair as an integer (int).

### Raises
- ValueError: If the pair is not found in the pairs information.

### Example Usage
```python
pair_index = await trader_client.pairs_cache.get_pair_index("ETH/USD")
print("Pair Index:", pair_index)
```
```

--------------------------------

### Configure Trader Client

Source: https://sdk.avantisfi.com/_sources/configuration.rst.txt

Create an instance of the TraderClient for accessing trade-related parameters. Ensure you use the correct provider URL for the Base Mainnet Chain.

```python
provider_url = "https://mainnet.base.org"
trader_client = TraderClient(provider_url)
```

--------------------------------

### Get Pairs Info

Source: https://sdk.avantisfi.com/_sources/get_information_and_parameters.rst.txt

Retrieves cached or blockchain-sourced information about trading pairs.

```APIDOC
## Get Pairs Info

### Description
The ``get_pairs_info`` method retrieves the pairs information from the blockchain. The information is cached and will be returned from the cache if it is available and force_update is False. This is to avoid unnecessary calls to the blockchain. This method is called internally by the SDK when the user requests any data related to trading pairs.

### Parameters
#### Query Parameters
- **force_update** (bool, optional): If True, the cache will be ignored and the information will be retrieved from the blockchain. Defaults to False.

### Returns
- A dictionary containing the pairs information.

### Example Usage
```python
pairs_info = await trader_client.pairs_cache.get_pairs_info()
print("Pairs Info:", pairs_info)
```
```

--------------------------------

### KMSSigner

Source: https://sdk.avantisfi.com/_modules/avantis_trader_sdk/signers/kms_signer.html

Initializes the KMSSigner with a Web3 instance, KMS key ID, and optional region name.

```APIDOC
## KMSSigner

### Description
Initializes the KMSSigner with a Web3 instance, KMS key ID, and optional region name.

### Parameters
* **web3**: The Web3 instance to use for blockchain interactions.
* **kms_key_id**: The ID of the AWS KMS key to use for signing.
* **region_name** (optional): The AWS region name. Defaults to "us-east-1".
```

--------------------------------

### Get Pairs Count

Source: https://sdk.avantisfi.com/_sources/get_information_and_parameters.rst.txt

Retrieves the total number of trading pairs available on the blockchain.

```APIDOC
## Get Pairs Count

### Description
The ``get_pairs_count`` method retrieves the number of trading pairs available on the blockchain.

### Returns
- The number of trading pairs available on the blockchain. (int)

### Example Usage
```python
pairs_count = await trader_client.pairs_cache.get_pairs_count()
print("Pairs Count:", pairs_count)
```
```

--------------------------------

### Load All Contracts

Source: https://sdk.avantisfi.com/_modules/avantis_trader_sdk/client.html

Loads all contracts defined in the configuration from the local filesystem. Returns a dictionary of contract names to contract objects.

```python
def load_contracts(self):
    """
    Loads all the contracts mentioned in the config from the local filesystem.

    Returns:
        A dictionary containing the contract names as keys and the Contract objects as values.
    """
    return {name: self.load_contract(name) for name in CONTRACT_ADDRESSES.keys()}

```

--------------------------------

### Approve USDC for Trading and Open Trade

Source: https://sdk.avantisfi.com/_sources/trade.rst.txt

This snippet demonstrates approving USDC collateral, preparing trade inputs for a market order with zero fees, and opening a trade. Ensure the TraderClient is initialized and connected before execution.

```python
import asyncio

from src.clients.client import Client
from src.clients.trader.types import TradeInput, TradeInputOrderType

async def main():
    # Initialize the TraderClient
    trader_client = Client(provider_url="https://mainnet.base.org")
    trader = "0x..."  # Replace with actual trader address
    amount_of_collateral = 1000  # Example amount in USDC

    # Get current allowance
    allowance = await trader_client.get_usdc_allowance_for_trading(trader)

    # Approve if allowance is insufficient
    if allowance < amount_of_collateral:
        print(f"Allowance of {trader} is less than {amount_of_collateral} USDC. Approving...")
        await trader_client.approve_usdc_for_trading(amount_of_collateral)
        allowance = await trader_client.get_usdc_allowance_for_trading(trader)
        print(f"New allowance of {trader} is {allowance} USDC")

    # Get pair index of the pair. For example, ETH/USD
    pair_index_of_eth_usd = await trader_client.pairs_cache.get_pair_index("ETH/USD")

    # Prepare trade input
    trade_input = TradeInput(
        trader=trader,  # Trader's wallet address
        open_price=None,  # (Optional) Open price of the trade. Current price in case of Market orders. If None then it will default to the current price
        pair_index=pair_index_of_eth_usd,  # Pair index
        collateral_in_trade=amount_of_collateral,  # Amount of collateral in trade (in USDC)
        is_long=True,  # True for long, False for short
        leverage=25,  # Leverage for the trade
        index=0,  # This is the index of the trade for a pair (0 for the first trade, 1 for the second, etc.)
        tp=4000.5,  # Take profit price. Max allowed is 500% of open price.
        sl=0,  # Stop loss price
        timestamp=0,  # Timestamp of the trade. 0 for now
    )

    # 1% slippage
    slippage_percentage = 1

    # Order type for the trade (MARKET or LIMIT or STOP_LIMIT or MARKET_ZERO_FEE)
    trade_input_order_type = TradeInputOrderType.MARKET_ZERO_FEE
   
    # Notes:
    # - Limit orders are not supported for zero fee trades
    # - Withdrawing collateral is not supported for zero fee trades
    # - No referral discounts are applied for zero fee trades
    # - Loss protection is not applied for zero fee trades

    # Open trade
    open_transaction = await trader_client.trade.build_trade_open_tx(
        trade_input, trade_input_order_type, slippage_percentage
    )

    receipt = await trader_client.sign_and_get_receipt(open_transaction)

    print(receipt)
    print("Trade opened successfully!")

# Run the example
asyncio.run(main())
```

--------------------------------

### get_usdc_allowance_for_trading

Source: https://sdk.avantisfi.com/avantis_trader_sdk.html

Gets the USDC allowance for the Trading Storage contract for a given address. This method is asynchronous.

```APIDOC
## async get_usdc_allowance_for_trading(_address =None_)

Gets the USDC allowance for the Trading Storage contract.

Parameters:
    
**address** (_optional_) – The address.

Returns:
    
The USDC allowance.
```

--------------------------------

### Build and Sign Transaction with Nonce

Source: https://sdk.avantisfi.com/_modules/avantis_trader_sdk/client.html

Builds a transaction, automatically fetching a nonce if not provided, and returns the signed transaction or the raw transaction if no signer is set.

```python
if "nonce" not in kwargs:
            kwargs["nonce"] = await self.get_transaction_count(kwargs["from"])

        transaction = await contract.functions[function_name](*args).build_transaction(
            kwargs
        )

        if not self.has_signer():
            return transaction

        receipt = await self.sign_and_get_receipt(transaction)
        return receipt
```

--------------------------------

### Get OI Limits

Source: https://sdk.avantisfi.com/_sources/get_information_and_parameters.rst.txt

Retrieves the open interest limits for all trading pairs, used for risk management.

```APIDOC
## Get OI Limits

### Description
The ``get_oi_limits`` method retrieves the open interest limits for all trading pairs. Open interest limits are the maximum allowable open interest for each trading pair, which helps manage risk and liquidity in the market.

### Returns
- An instance of :class:`~avantis_trader_sdk.types.OpenInterestLimits` containing the open interest limits for each trading pair. Each entry in the ``limits`` dictionary maps a trading pair (e.g., "ETH/USD") to its corresponding open interest limit.

### Notes
- The open interest limits are returned in units of the quote currency of each trading pair.

### Example Usage
```python
oi_limits = await trader_client.asset_parameters.get_oi_limits()
print("Open Interest Limits:", oi_limits.limits)
```
```

--------------------------------

### Config

Source: https://sdk.avantisfi.com/avantis_trader_sdk.html

Configuration model for Avantis Trader SDK, including parameters like leverage, open price, and trade details.

```APIDOC
## _class _Config[source]

### Description
Configuration for the model.

### Parameters
* **collateral_in_trade** (Optional[float])
* **is_long** (bool)
* **leverage** (float)
* **open_collateral** (float)
* **open_price** (float)
* **pair_index** (int)
* **sl** (float)
* **timestamp** (int)
* **tp** (float)
* **trade_index** (int)
* **trader** (str)
```

--------------------------------

### Get Group Indexes

Source: https://sdk.avantisfi.com/_sources/get_information_and_parameters.rst.txt

Retrieves the group identifiers used to categorize trading pairs by their underlying asset.

```APIDOC
## Get Group Indexes

### Description
The ``get_group_indexes`` method retrieves the group ids from the blockchain. The group ids are used to categorize trading pairs based on their underlying asset. For example, all trading pairs with the same underlying asset will have the same group id. This method is called internally by the SDK when the user requests any data related to trading pairs.

Group id 0 and 1 are reserved for the crypto groups. Group id 2 is reserved for the forex group. Group id 3 is reserved for the commodities group.

Each pair in pair info, returned by :meth:`~avantis_trader_sdk.rpc.pairs_cache.PairsCache.get_pairs_info`, has a group index ``groupIndex`` property.

### Returns
- The group ids as a set.

### Example Usage
```python
group_indexes = await trader_client.pairs_cache.get_group_indexes()
print("Group Indexes:", group_indexes)
```
```

--------------------------------

### Retrieve Opening Fee for a Trade Input

Source: https://sdk.avantisfi.com/_modules/avantis_trader_sdk/rpc/fee_parameters.html

Retrieves the opening fee for a trade, considering referral rebates. The position size is calculated and scaled appropriately for the fee calculation.

```python
async def get_new_trade_opening_fee(
        self,
        trade_input: TradeInput,
    ):
        """
        Retrieves the opening fee for a trade with referral rebate in USDC.

        Args:
            trade_input: The trade input object.

        Returns:
            Final opening fee in USDC
        """
        position_size = (
            trade_input.positionSizeUSDC / 10**6 * trade_input.leverage / 10**10
        )

        position_size = int(position_size * 10**6)
```

--------------------------------

### Get Ethereum Address (Alias)

Source: https://sdk.avantisfi.com/_modules/avantis_trader_sdk/signers/kms_signer.html

Provides an alias for retrieving the Ethereum wallet address associated with the signer.

```python
def get_ethereum_address(self):
    """
    Derives the Ethereum wallet address from the public key.

    Returns:
        str: The Ethereum wallet address in checksum format.
    """
    return self.address
```
Tokens:
Raw