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.

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:

Example Request:

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
    }
  }'

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:

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

List Agents

GET /api/v1/agents

List all agents owned by the authenticated account.

Authentication: JWT only

Query Parameters:

Example Request:

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

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:

{
  "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 https://api.tradeready.io/api/v1/agents/overview \
  -H "Authorization: Bearer eyJhbGci..."

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:

Example Request:

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

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):

Example Request:

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"]}'

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:

Example Request:

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..."

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 -X POST \
  https://api.tradeready.io/api/v1/agents/a1b2c3d4-e5f6-7890-abcd-ef1234567890/reset \
  -H "Authorization: Bearer eyJhbGci..."

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 -X POST \
  https://api.tradeready.io/api/v1/agents/a1b2c3d4-e5f6-7890-abcd-ef1234567890/archive \
  -H "Authorization: Bearer eyJhbGci..."

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.

Authentication: JWT only

Returns HTTP 204 No Content on success.

Example Request:

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

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 https://api.tradeready.io/api/v1/agents/a1b2c3d4-e5f6-7890-abcd-ef1234567890/api-key \
  -H "Authorization: Bearer eyJhbGci..."

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:

{
  "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 -X POST \
  https://api.tradeready.io/api/v1/agents/a1b2c3d4-e5f6-7890-abcd-ef1234567890/regenerate-key \
  -H "Authorization: Bearer eyJhbGci..."

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 https://api.tradeready.io/api/v1/agents/a1b2c3d4-e5f6-7890-abcd-ef1234567890/risk-profile \
  -H "Authorization: Bearer eyJhbGci..."

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:

{
  "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:

Example Request:

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
  }'

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 https://api.tradeready.io/api/v1/agents/a1b2c3d4-e5f6-7890-abcd-ef1234567890/skill.md \
  -H "Authorization: Bearer eyJhbGci..." \
  -o my-agent-skill.md

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:

# 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.