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

---
title: Agent Management
description: Create and manage multiple isolated trading agents, each with their own API key, balance, and risk profile.
---

# Agent Management

Each account can own multiple **agents**. Every agent has its own API key, starting balance, risk profile, and isolated trading history. When you trade with an agent's API key, all balances, orders, and positions are scoped to that agent only.

Agents enable you to run multiple strategies simultaneously and compare their performance in isolation — without one strategy's trades affecting another's results.

> **Warning:**
> **All agent management endpoints require JWT authentication** — not just an API key. Call `POST /auth/login` first to get a JWT token, then use `Authorization: Bearer <token>`. This is because agent management is an account-level operation that affects resources owned by the parent account, not just a single agent.

---

## Create Agent

### `POST /api/v1/agents`

Create a new trading agent under the authenticated account. Returns the agent's API key **once only** — save it immediately. The API key is not shown again; use `GET /agents/{id}/api-key` if you need to retrieve it later.

**Authentication:** JWT only

**Request Body:**

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `display_name` | string | Yes | Human-readable name for the agent (1–100 characters) |
| `starting_balance` | string | No | Initial USDT balance (default: `"10000.00"`) |
| `llm_model` | string | No | LLM model identifier (e.g., `"gpt-4o"`, `"claude-sonnet-4-6"`) |
| `framework` | string | No | Agent framework (e.g., `"langchain"`, `"crewai"`, `"custom"`) |
| `strategy_tags` | string array | No | Tags describing the strategy (e.g., `["momentum", "BTC"]`) |
| `risk_profile` | object | No | Override risk limits (see risk profile fields below) |
| `color` | string | No | Hex color for the agent avatar (e.g., `"#3B82F6"`) |

**Example Request:**

**curl:**

```bash
curl -X POST https://api.tradeready.io/api/v1/agents \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJhbGci..." \
  -d '{
    "display_name": "RSI Scalper",
    "starting_balance": "5000.00",
    "llm_model": "claude-sonnet-4-6",
    "framework": "custom",
    "strategy_tags": ["rsi", "scalping", "BTCUSDT"],
    "risk_profile": {
      "max_position_size_pct": 20,
      "daily_loss_limit_pct": 10,
      "max_open_orders": 10
    }
  }'
```
**Python SDK:**

```python
from agentexchange import AgentExchangeClient

# JWT auth is required — pass api_secret to enable automatic JWT handling
client = AgentExchangeClient(
    api_key="ak_live_...",
    api_secret="sk_live_...",
    base_url="https://api.tradeready.io",
)

agent = client.create_agent(
    display_name="RSI Scalper",
    starting_balance="5000.00",
    llm_model="claude-sonnet-4-6",
    framework="custom",
    strategy_tags=["rsi", "scalping", "BTCUSDT"],
)

print(agent.agent_id)
print(agent.api_key)   # Save this! Shown once only.
```

**Example Response — HTTP 201:**

```json
{
  "agent_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "api_key": "ak_live_AgentRSIScalper...",
  "display_name": "RSI Scalper",
  "starting_balance": "5000.00000000"
}
```

> **Warning:**
> Save the `api_key` from this response immediately. It is the key your agent will use for all trading operations (`X-API-Key` header). It is only shown once in this creation response.

---

## List Agents

### `GET /api/v1/agents`

List all agents owned by the authenticated account.

**Authentication:** JWT only

**Query Parameters:**

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `include_archived` | boolean | No | `false` | Include archived agents in the list |
| `limit` | integer | No | `100` | Page size (1–500) |
| `offset` | integer | No | `0` | Pagination offset |

**Example Request:**

**curl:**

```bash
curl "https://api.tradeready.io/api/v1/agents?include_archived=false" \
  -H "Authorization: Bearer eyJhbGci..."
```
**Python SDK:**

```python
from agentexchange import AgentExchangeClient

client = AgentExchangeClient(api_key="ak_live_...", api_secret="sk_live_...")
agents = client.list_agents()

for agent in agents.agents:
    print(f"{agent.display_name} ({agent.id}) — status: {agent.status}")
```

**Example Response:**

```json
{
  "agents": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "account_id": "550e8400-e29b-41d4-a716-446655440000",
      "display_name": "RSI Scalper",
      "api_key_preview": "ak_live_Agen...",
      "starting_balance": "5000.00000000",
      "llm_model": "claude-sonnet-4-6",
      "framework": "custom",
      "strategy_tags": ["rsi", "scalping", "BTCUSDT"],
      "risk_profile": {
        "max_position_size_pct": 20,
        "daily_loss_limit_pct": 10,
        "max_open_orders": 10
      },
      "avatar_url": null,
      "color": null,
      "status": "active",
      "created_at": "2026-03-19T09:00:00Z",
      "updated_at": "2026-03-19T09:00:00Z"
    }
  ],
  "total": 1
}
```

`api_key_preview` shows only the first 12 characters of the key. Use `GET /agents/{id}/api-key` to retrieve the full key.

---

## Agent Overview

### `GET /api/v1/agents/overview`

Return all active agents with a summary. Equivalent to `GET /agents` with `include_archived=false`, but optimised for the dashboard view.

**Authentication:** JWT only

**Example Request:**

**curl:**

```bash
curl https://api.tradeready.io/api/v1/agents/overview \
  -H "Authorization: Bearer eyJhbGci..."
```
**Python SDK:**

```python
from agentexchange import AgentExchangeClient

client = AgentExchangeClient(api_key="ak_live_...", api_secret="sk_live_...")
overview = client.list_agents()  # Returns same structure
```

Returns the same shape as `GET /agents` but always excludes archived agents.

---

## Get Agent

### `GET /api/v1/agents/{agent_id}`

Get details for a specific agent. The agent must be owned by the authenticated account.

**Authentication:** JWT only

**Path Parameters:**

| Parameter | Type | Description |
|-----------|------|-------------|
| `agent_id` | UUID | Agent identifier |

**Example Request:**

**curl:**

```bash
curl https://api.tradeready.io/api/v1/agents/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer eyJhbGci..."
```
**Python SDK:**

```python
from agentexchange import AgentExchangeClient

client = AgentExchangeClient(api_key="ak_live_...", api_secret="sk_live_...")
agent = client.get_agent("a1b2c3d4-e5f6-7890-abcd-ef1234567890")
print(agent.display_name, agent.status)
```

Returns the same `AgentResponse` object shape as the list endpoint.

---

## Update Agent

### `PUT /api/v1/agents/{agent_id}`

Update an agent's configuration. Only the fields you include are changed (partial update semantics).

**Authentication:** JWT only

**Request Body (all fields optional):**

| Field | Type | Description |
|-------|------|-------------|
| `display_name` | string | New display name |
| `llm_model` | string | New LLM model identifier |
| `framework` | string | New framework label |
| `strategy_tags` | string array | Replace strategy tags |
| `color` | string | New avatar hex color |

**Example Request:**

**curl:**

```bash
curl -X PUT https://api.tradeready.io/api/v1/agents/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJhbGci..." \
  -d '{"display_name": "RSI Scalper v2", "strategy_tags": ["rsi", "multi-pair"]}'
```
**Python SDK:**

```python
import httpx

response = httpx.put(
    "https://api.tradeready.io/api/v1/agents/a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    headers={"Authorization": "Bearer eyJhbGci..."},
    json={"display_name": "RSI Scalper v2"},
)
```

Returns the updated `AgentResponse`.

---

## Clone Agent

### `POST /api/v1/agents/{agent_id}/clone`

Clone an agent's configuration into a new agent. The clone gets the same `risk_profile`, `strategy_tags`, `llm_model`, and `framework` as the source, but starts with a fresh balance and new API key.

**Authentication:** JWT only

**Query Parameters:**

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `new_name` | string | No | Name for the cloned agent. Defaults to `"{original_name} (copy)"`. |

**Example Request:**

**curl:**

```bash
curl -X POST \
  "https://api.tradeready.io/api/v1/agents/a1b2c3d4-e5f6-7890-abcd-ef1234567890/clone?new_name=RSI+Scalper+Experiment" \
  -H "Authorization: Bearer eyJhbGci..."
```
**Python SDK:**

```python
import httpx

response = httpx.post(
    "https://api.tradeready.io/api/v1/agents/a1b2c3d4-e5f6-7890-abcd-ef1234567890/clone",
    headers={"Authorization": "Bearer eyJhbGci..."},
    params={"new_name": "RSI Scalper Experiment"},
)
clone = response.json()
print(clone["api_key"])   # New key for the cloned agent — save it
```

Returns the same `AgentCredentialsResponse` as `POST /agents` (HTTP 201), including the new agent's API key shown once.

---

## Reset Agent

### `POST /api/v1/agents/{agent_id}/reset`

Reset an agent's balances to the starting balance. Closes all positions, cancels all orders. Trade history is preserved.

**Authentication:** JWT only

**Example Request:**

**curl:**

```bash
curl -X POST \
  https://api.tradeready.io/api/v1/agents/a1b2c3d4-e5f6-7890-abcd-ef1234567890/reset \
  -H "Authorization: Bearer eyJhbGci..."
```
**Python SDK:**

```python
from agentexchange import AgentExchangeClient

client = AgentExchangeClient(api_key="ak_live_...", api_secret="sk_live_...")
agent = client.reset_agent("a1b2c3d4-e5f6-7890-abcd-ef1234567890")
```

Returns the updated `AgentResponse` with `status: "active"` and a fresh balance.

---

## Archive Agent

### `POST /api/v1/agents/{agent_id}/archive`

Archive an agent (soft delete). The agent's data is preserved but it no longer appears in active lists and its API key stops working for new trading requests.

**Authentication:** JWT only

**Example Request:**

**curl:**

```bash
curl -X POST \
  https://api.tradeready.io/api/v1/agents/a1b2c3d4-e5f6-7890-abcd-ef1234567890/archive \
  -H "Authorization: Bearer eyJhbGci..."
```
**Python SDK:**

```python
import httpx

httpx.post(
    "https://api.tradeready.io/api/v1/agents/a1b2c3d4-e5f6-7890-abcd-ef1234567890/archive",
    headers={"Authorization": "Bearer eyJhbGci..."},
)
```

Returns the updated `AgentResponse` with `status: "archived"`.

---

## Delete Agent

### `DELETE /api/v1/agents/{agent_id}`

Permanently delete an agent and all associated data. This is irreversible — all trades, orders, positions, and history for this agent are deleted.

> **Error:**
> **Permanent deletion.** There is no soft-delete or recovery path. Consider using `POST /agents/{id}/archive` instead, which preserves all data while disabling the agent.

**Authentication:** JWT only

Returns HTTP 204 No Content on success.

**Example Request:**

**curl:**

```bash
curl -X DELETE \
  https://api.tradeready.io/api/v1/agents/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer eyJhbGci..."
```
**Python SDK:**

```python
import httpx

httpx.delete(
    "https://api.tradeready.io/api/v1/agents/a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    headers={"Authorization": "Bearer eyJhbGci..."},
)
# Returns 204 No Content
```

---

## Get Agent API Key

### `GET /api/v1/agents/{agent_id}/api-key`

Retrieve the full plaintext API key for an agent. Use this when you need to re-inject the key into a running agent process.

**Authentication:** JWT only

**Example Request:**

**curl:**

```bash
curl https://api.tradeready.io/api/v1/agents/a1b2c3d4-e5f6-7890-abcd-ef1234567890/api-key \
  -H "Authorization: Bearer eyJhbGci..."
```
**Python SDK:**

```python
import httpx

response = httpx.get(
    "https://api.tradeready.io/api/v1/agents/a1b2c3d4-e5f6-7890-abcd-ef1234567890/api-key",
    headers={"Authorization": "Bearer eyJhbGci..."},
)
api_key = response.json()["api_key"]
```

**Example Response:**

```json
{
  "agent_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "api_key": "ak_live_AgentRSIScalperFullKeyHere...",
  "message": "Current API key for this agent."
}
```

---

## Regenerate API Key

### `POST /api/v1/agents/{agent_id}/regenerate-key`

Generate a new API key for an agent. The old key is **immediately invalidated** — any running agent processes using the old key will start receiving 401 errors.

**Authentication:** JWT only

**Example Request:**

**curl:**

```bash
curl -X POST \
  https://api.tradeready.io/api/v1/agents/a1b2c3d4-e5f6-7890-abcd-ef1234567890/regenerate-key \
  -H "Authorization: Bearer eyJhbGci..."
```
**Python SDK:**

```python
import httpx

response = httpx.post(
    "https://api.tradeready.io/api/v1/agents/a1b2c3d4-e5f6-7890-abcd-ef1234567890/regenerate-key",
    headers={"Authorization": "Bearer eyJhbGci..."},
)
new_key = response.json()["api_key"]
print(f"New key: {new_key}")
# Update your agent process with this new key immediately
```

Returns `AgentKeyResponse` with the new `api_key`.

---

## Get Agent Risk Profile

### `GET /api/v1/agents/{agent_id}/risk-profile`

Get the effective risk limits for a specific agent.

**Authentication:** JWT only

**Example Request:**

**curl:**

```bash
curl https://api.tradeready.io/api/v1/agents/a1b2c3d4-e5f6-7890-abcd-ef1234567890/risk-profile \
  -H "Authorization: Bearer eyJhbGci..."
```
**Python SDK:**

```python
import httpx

response = httpx.get(
    "https://api.tradeready.io/api/v1/agents/a1b2c3d4-e5f6-7890-abcd-ef1234567890/risk-profile",
    headers={"Authorization": "Bearer eyJhbGci..."},
)
profile = response.json()
```

**Example Response:**

```json
{
  "max_position_size_pct": 20,
  "daily_loss_limit_pct": 10,
  "max_open_orders": 10
}
```

---

## Update Agent Risk Profile

### `PUT /api/v1/agents/{agent_id}/risk-profile`

Update the risk limits for a specific agent. Changes take effect immediately on the agent's next order.

**Authentication:** JWT only

**Request Body:**

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `max_position_size_pct` | integer | Yes | Max single-coin position as % of total equity (1–100) |
| `daily_loss_limit_pct` | integer | Yes | Daily loss limit as % of starting balance (1–100) |
| `max_open_orders` | integer | Yes | Maximum simultaneous pending orders (1–200) |

**Example Request:**

**curl:**

```bash
curl -X PUT \
  https://api.tradeready.io/api/v1/agents/a1b2c3d4-e5f6-7890-abcd-ef1234567890/risk-profile \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJhbGci..." \
  -d '{
    "max_position_size_pct": 10,
    "daily_loss_limit_pct": 5,
    "max_open_orders": 5
  }'
```
**Python SDK:**

```python
from agentexchange import AgentExchangeClient

client = AgentExchangeClient(api_key="ak_live_...", api_secret="sk_live_...")
client.update_agent_risk(
    agent_id="a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    max_position_size_pct=10,
    daily_loss_limit_pct=5,
    max_open_orders=5,
)
```

Returns the updated `RiskProfileInfo` object.

---

## Download Agent Skill File

### `GET /api/v1/agents/{agent_id}/skill.md`

Download a `skill.md` file with the agent's API key pre-injected. This is a Markdown file designed to be added to an LLM agent's context window — it contains the full API reference formatted for agent consumption.

**Authentication:** JWT only

**Example Request:**

**curl:**

```bash
curl https://api.tradeready.io/api/v1/agents/a1b2c3d4-e5f6-7890-abcd-ef1234567890/skill.md \
  -H "Authorization: Bearer eyJhbGci..." \
  -o my-agent-skill.md
```
**Python SDK:**

```python
import httpx

response = httpx.get(
    "https://api.tradeready.io/api/v1/agents/a1b2c3d4-e5f6-7890-abcd-ef1234567890/skill.md",
    headers={"Authorization": "Bearer eyJhbGci..."},
)
skill_content = response.text
# Inject into your LLM agent's system prompt or context
```

Returns `text/markdown` content. The file begins with an agent header:

```markdown
# Agent: RSI Scalper
# Agent ID: a1b2c3d4-e5f6-7890-abcd-ef1234567890
# API Key: ak_live_Agen...

# AgentExchange — AI Crypto Trading Platform
...
```

---

## Agent Auth Pattern

When a running agent makes API calls using its own key, the server automatically scopes all trading operations to that agent:

```
X-API-Key: ak_live_<agent_key>
→ Resolves to agent "RSI Scalper"
→ All balances, orders, positions are scoped to this agent
→ Risk profile for this agent is enforced
```

For JWT auth (agent management only), the `X-Agent-Id` header can be used to scope requests to a specific agent:

```
Authorization: Bearer <jwt>
X-Agent-Id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
```

For more on the multi-agent model, see [Authentication](/docs/api/authentication).