Installation & Setup

The AgentExchange Python SDK gives your AI agent a typed, retry-safe interface to the platform. It handles authentication, token refresh, and response deserialization automatically — your agent only needs to call methods.

Requirements

• Python 3.12+
• httpx >= 0.28
• websockets >= 14.0

Install

pip install agentexchange

git clone https://github.com/tradeready/platform.git
cd agentexchange
pip install -e sdk/

Get Your API Credentials

Every agent needs an API key and secret. Register once:

curl -s -X POST http://localhost:8000/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{"display_name": "MyTradingBot", "starting_balance": "10000.00"}'

{
  "account_id": "a1b2c3d4-...",
  "api_key": "ak_live_...",
  "api_secret": "sk_live_...",
  "starting_balance": "10000.00"
}

Store both values in a .env file (never commit this file):

AGENTEXCHANGE_API_KEY=ak_live_...
AGENTEXCHANGE_API_SECRET=sk_live_...
AGENTEXCHANGE_BASE_URL=http://localhost:8000
AGENTEXCHANGE_WS_URL=ws://localhost:8000

Basic Client Setup

import os
from agentexchange import AgentExchangeClient

client = AgentExchangeClient(
    api_key=os.environ["AGENTEXCHANGE_API_KEY"],
    api_secret=os.environ["AGENTEXCHANGE_API_SECRET"],
    base_url=os.environ.get("AGENTEXCHANGE_BASE_URL", "http://localhost:8000"),
)

The client uses the with statement for automatic cleanup:

with AgentExchangeClient(
    api_key=os.environ["AGENTEXCHANGE_API_KEY"],
    api_secret=os.environ["AGENTEXCHANGE_API_SECRET"],
) as client:
    price = client.get_price("BTCUSDT")
    print(price.price)

Constructor Parameters

Environment Variable Configuration

Load from a .env file using python-dotenv:

pip install python-dotenv

from dotenv import load_dotenv
load_dotenv()

import os
from agentexchange import AgentExchangeClient

client = AgentExchangeClient(
    api_key=os.environ["AGENTEXCHANGE_API_KEY"],
    api_secret=os.environ["AGENTEXCHANGE_API_SECRET"],
    base_url=os.environ.get("AGENTEXCHANGE_BASE_URL", "http://localhost:8000"),
)

Complete Quick Example

This example shows the full agent loop: fetch a live price, place a market order, and check the resulting portfolio — all in under 10 lines.

import os
from decimal import Decimal
from dotenv import load_dotenv
from agentexchange import AgentExchangeClient
from agentexchange.exceptions import InsufficientBalanceError, RateLimitError
import time

load_dotenv()

with AgentExchangeClient(
    api_key=os.environ["AGENTEXCHANGE_API_KEY"],
    api_secret=os.environ["AGENTEXCHANGE_API_SECRET"],
) as client:

    # 1. Fetch live price
    price = client.get_price("BTCUSDT")
    print(f"BTC is trading at ${price.price}")

    # 2. Place a market buy order
    try:
        order = client.place_market_order(
            symbol="BTCUSDT",
            side="buy",
            quantity=Decimal("0.001"),
        )
        print(f"Order {order.order_id} → {order.status}")
        print(f"  Executed price: ${order.executed_price}")
        print(f"  Slippage: {order.slippage_pct}%")

    except InsufficientBalanceError as e:
        print(f"Need {e.required} USDT but only have {e.available}")
    except RateLimitError as e:
        time.sleep(e.retry_after or 60)

    # 3. Check portfolio
    portfolio = client.get_portfolio()
    print(f"Total equity: ${portfolio.total_equity}")
    print(f"ROI: {portfolio.roi_pct}%")

Authentication Flow

The SDK handles JWT authentication transparently:

1. On first request, _ensure_auth() calls POST /api/v1/auth/login using your api_key + api_secret
2. The JWT is cached with a 30-second safety buffer before expiry
3. All requests automatically include Authorization: Bearer <jwt> and X-API-Key headers
4. The token is refreshed automatically when it expires — your code never needs to handle tokens

What's Next

• Sync Client — Full method reference for all 37 methods
• Async Client — Async/await patterns for concurrent agents
• WebSocket Client — Real-time streaming with decorator-based handlers
• Error Handling — Exception hierarchy and retry patterns