<!-- Generated from TradeReady.io docs. Visit https://tradeready.io/docs for the full experience. -->

---
title: Installation & Setup
description: Install the Python SDK and configure your client
---

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

**PyPI:**

```bash
pip install agentexchange
```
**Local (development):**

Clone the platform repository and install the SDK in editable mode:

```bash
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:

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

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

> **Warning:**
> Save `api_secret` immediately — it is shown only once and cannot be retrieved again.

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

```bash
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

```python
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:

```python
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

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `api_key` | `str` | required | Your `ak_live_...` key |
| `api_secret` | `str` | required | Your `sk_live_...` secret |
| `base_url` | `str` | `http://localhost:8000` | Platform REST URL |
| `timeout` | `float` | `30.0` | HTTP request timeout in seconds |

## Environment Variable Configuration

Load from a `.env` file using `python-dotenv`:

```bash
pip install python-dotenv
```

```python
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.

```python
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](/docs/sdk/sync-client) — Full method reference for all 37 methods
- [Async Client](/docs/sdk/async-client) — Async/await patterns for concurrent agents
- [WebSocket Client](/docs/sdk/websocket-client) — Real-time streaming with decorator-based handlers
- [Error Handling](/docs/sdk/error-handling) — Exception hierarchy and retry patterns