TradingAgents/docs/api-reference.md

API Reference — Execution Engine

Base Types

TradeOrder

@dataclass
class TradeOrder:
    action: str          # "buy" or "sell"
    token_in: str        # Input token address
    token_out: str       # Output token address
    amount: float        # Amount of token_in to spend
    slippage_bps: int    # Slippage tolerance in basis points (50 = 0.5%)
    chain: str           # "solana", "ethereum", "base", etc.
    priority_fee: float | None = None  # Optional gas/priority fee override

TradeResult

@dataclass
class TradeResult:
    success: bool
    tx_hash: str
    amount_in: float
    amount_out: float
    price_impact: float   # Percentage
    gas_cost: float       # In native token
    timestamp: str

---

JupiterExecutor (Solana)

from tradingagents.execution import JupiterExecutor

executor = JupiterExecutor(
    rpc_url="https://api.mainnet-beta.solana.com",
    private_key="<base58_private_key>",  # From SOLANA_PRIVATE_KEY
)

Methods

async get_quote(order: TradeOrder) -> dict

Fetches a swap route from the Jupiter Aggregator V6 API.

quote = await executor.get_quote(order)
# Returns raw Jupiter quote dict with fields like:
# { "inputMint": ..., "outputMint": ..., "outAmount": ... }

Quota: 1 HTTP GET to https://quote-api.jup.ag/v6/quote

async execute_swap(order: TradeOrder) -> TradeResult

Full swap execution:

1. Gets quote
2. POSTs to /v6/swap to get serialized transaction
3. Signs with solders.Keypair
4. Sends via Solana RPC

async get_wallet_balance(token_address: str) -> float

Returns the token balance for the configured wallet. (Stub — implement for Scenario 3)

---

OneInchExecutor (EVM)

from tradingagents.execution import OneInchExecutor

executor = OneInchExecutor(
    rpc_url="https://eth-mainnet.g.alchemy.com/v2/YOUR_KEY",
    private_key="0x<hex_private_key>",  # From ETH_PRIVATE_KEY
    chain_id=1,  # 1=Ethereum, 8453=Base, 42161=Arbitrum
)

Methods

async get_quote(order: TradeOrder) -> dict

Fetches price estimate from 1inch V6 API.

quote = await executor.get_quote(order)
# Returns: { "dstAmount": "50000000000000000", ... }

async execute_swap(order: TradeOrder) -> TradeResult

Full EVM swap:

1. Calls /swap/v6.0/{chainId}/swap to get calldata
2. Builds EIP-155 transaction with nonce + gas
3. Signs with web3.eth.account
4. Broadcasts via eth_sendRawTransaction

---

OrderManager

Converts LLM agent signals ("BUY", "SELL", "HOLD") into executable TradeOrder objects.

from tradingagents.execution import OrderManager

manager = OrderManager(
    risk_params={
        "max_position_size": 1000.0,  # USD
        "default_buy_amount": 100.0,  # USD per buy
    }
)

async process_signal(signal, token_address, portfolio, chain) -> TradeOrder | None

Signal	Behaviour
"BUY"	Spends default_buy_amount USDC → target token (capped by max_position_size)
"SELL"	Sells entire position of target token → USDC
"HOLD"	Returns None — no trade

---

GoogleSearchClient + QuotaManager

import os
from tradingagents.dataflows.google_search_tools import GoogleSearchClient, QuotaExceededError

client = GoogleSearchClient(
    api_key=os.environ["GOOGLE_SEARCH_API_KEY"],
    cx=os.environ["GOOGLE_SEARCH_ENGINE_ID"],
    daily_limit=95,       # Hard cap — raises QuotaExceededError when reached
    warn_threshold=0.8,   # Logs warning at 80% usage
)

results = await client.search("solana DeFi TVL", num=5)
# Returns: list[SearchResult(title, link, snippet)]

print(client.quota_status)
# { "usage_today": 3, "daily_limit": 95, "remaining": 92, "is_near_limit": False }

---

WebResearchAnalyst

from tradingagents.agents.analysts.web_research_analyst import WebResearchAnalyst

analyst = WebResearchAnalyst()  # Reads GOOGLE_SEARCH_* from env

report = await analyst.research_token(
    token_name="Solana",
    token_address="So11111111111111111111111111111111111111112",
)

print(report.to_text())  # LLM-ready markdown report

Report Categories

Attribute	Description
security_findings	Results from honeypot.is, tokensniffer
news_findings	Results from coindesk, theblock, bloomberg
analytics_findings	Results from defillama, dune, dexscreener
sentiment_findings	Results from lunarcrush
quota_status	Current daily usage stats

Quota cost: 4 queries per research_token() call (one per category).

---

PortfolioTracker

from tradingagents.portfolio import PortfolioTracker

tracker = PortfolioTracker(rpc_url="https://api.mainnet-beta.solana.com")
portfolio = await tracker.get_portfolio_state(wallet="<address>", chain="solana")

print(portfolio.total_value_usd)         # e.g. 5420.75
print(portfolio.positions["So1111..."])  # PositionInfo object

Stubs _fetch_token_balances and _fetch_token_prices — implement for Scenario 3 with real RPC/price oracle calls.