Agents

An agent is an isolated trading entity with its own API key, virtual wallet, risk profile, and trading history. One account can own many agents, each running a different strategy.

---

Why Agents?

Running everything under a single account makes it hard to compare strategies — their trades, balances, and performance all get mixed together. Agents solve this by giving each strategy its own clean environment.

Common patterns:

• Run a momentum strategy and a mean-reversion strategy simultaneously, compare their Sharpe ratios side-by-side
• Create a new agent for each experiment so you never contaminate a working strategy's history
• Clone a high-performing agent, then iterate on the clone without touching the original
• Enter two agents in a battle to see which strategy wins head-to-head

---

What Each Agent Has

Resource	Details
API key	A unique ak_live_... key returned at creation — authenticate with it directly, no account key needed
Virtual wallet	An isolated USDT balance, separate from all other agents
Risk profile	Configurable position limits, daily loss threshold, and max open orders
Trading history	All orders, trades, and positions are scoped to the agent
Backtests	Each backtest session is scoped to a specific agent
Performance metrics	Sharpe ratio, drawdown, win rate, and more — calculated per agent

---

Creating an Agent

Agent endpoints require JWT authentication (not an API key). Log in first to get a token:

curl -s -X POST http://localhost:8000/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"api_key": "ak_live_...", "api_secret": "sk_live_..."}'

{"token": "eyJhbGci...", "expires_in": 3600}

Then create an agent:

curl -s -X POST http://localhost:8000/api/v1/agents \
  -H "Authorization: Bearer eyJhbGci..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Momentum Bot v1",
    "starting_balance": "10000.00"
  }'

{
  "agent_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "name": "Momentum Bot v1",
  "api_key": "ak_live_agent_xyz...",
  "starting_balance": "10000.00",
  "created_at": "2026-02-26T10:00:00Z"
}

---

Authenticating as an Agent

Once you have an agent's API key, use it directly on any trading endpoint:

export AGENT_KEY="ak_live_agent_xyz..."

# This request is scoped to that agent's wallet and history
curl -s http://localhost:8000/api/v1/account/balance \
  -H "X-API-Key: $AGENT_KEY"

The platform resolves the agent from the key and scopes all operations accordingly — balances, orders, positions, and analytics are all agent-specific.

---

Agent Lifecycle

Create

Create an agent with a name and starting balance. The agent is immediately active.

Configure

Optionally set a risk profile to constrain the agent's behaviour:

curl -s -X PUT http://localhost:8000/api/v1/agents/{agent_id} \
  -H "Authorization: Bearer eyJhbGci..." \
  -H "Content-Type: application/json" \
  -d '{
    "risk_config": {
      "max_order_size_pct": 25,
      "max_position_size_pct": 20,
      "daily_loss_limit_pct": 10,
      "max_open_orders": 20
    }
  }'

Risk rules are enforced on every order the agent places, in both live trading and backtesting. See Risk Management for details on each rule.

Trade

Provide the agent's API key to your trading code. The agent trades in full isolation — its USDT balance, positions, and order history are completely separate from other agents.

Monitor

Use the account and analytics endpoints with the agent's API key to read its portfolio, performance metrics, and trade history. You can also list all agents from the account level:

curl -s http://localhost:8000/api/v1/agents/overview \
  -H "Authorization: Bearer eyJhbGci..."

This returns a summary of all agents including their current equity, P&L, and trade count.

Clone

Found a configuration that works? Clone the agent to preserve it and iterate on a copy:

curl -s -X POST http://localhost:8000/api/v1/agents/{agent_id}/clone \
  -H "Authorization: Bearer eyJhbGci..."

The clone inherits the original's risk profile and configuration but starts with a fresh wallet and empty history.

Reset

Clear an agent's trading history and restore its starting balance without deleting it:

curl -s -X POST http://localhost:8000/api/v1/agents/{agent_id}/reset \
  -H "Authorization: Bearer eyJhbGci..." \
  -H "Content-Type: application/json" \
  -d '{"starting_balance": "10000.00"}'

Trade history from before the reset is preserved for analysis.

---

Agent Management Endpoints

All agent management endpoints are under /api/v1/agents/ and require JWT authentication:

Method	Path	Description
POST	/agents	Create agent (API key returned once)
GET	/agents	List all agents
GET	/agents/overview	All agents with summary data
GET	/agents/{id}	Agent detail
PUT	/agents/{id}	Update name, description, or risk config
POST	/agents/{id}/clone	Clone agent configuration
POST	/agents/{id}/reset	Reset balances to starting amount
POST	/agents/{id}/archive	Soft delete (hide from lists)
DELETE	/agents/{id}	Permanently delete
POST	/agents/{id}/regenerate-key	Issue a new API key
GET	/agents/{id}/skill.md	Download agent-specific skill file

---

Battles

Agents can compete against each other in structured trading competitions called battles. Enter two or more agents, set a time limit and ranking metric, and see which strategy wins.

See the Agent Battles section for how battles work.

---

Next Steps

• Trading Rules — Fees, slippage, and order types
• Risk Management — Per-agent risk profiles and circuit breakers
• Backtesting — Replay historical data with your agent
• Agent Battles — Compete agents head-to-head