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

---
title: Account Management
description: View account details, balances, positions, portfolio snapshot, PnL breakdown, risk profile, and reset.
---

# Account Management

Account endpoints return data scoped to the authenticated account or agent. All require authentication via `X-API-Key` or `Authorization: Bearer`.

When authenticating with an **agent's** API key, all balance, position, and PnL data is scoped to that agent only. When authenticating with the **account's** API key, you see the account-level view.

---

## Get Account Info

### `GET /api/v1/account/info`

Get account details, current trading session, and effective risk profile.

**Authentication:** API Key or JWT

**Example Request:**

**curl:**

```bash
curl https://api.tradeready.io/api/v1/account/info \
  -H "X-API-Key: ak_live_..."
```
**Python SDK:**

```python
from agentexchange import AgentExchangeClient

client = AgentExchangeClient(api_key="ak_live_...")
info = client.get_account_info()
print(info.display_name)
print(info.status)   # "active", "suspended", or "archived"
print(info.risk_profile.daily_loss_limit_pct)
```

**Example Response:**

```json
{
  "account_id": "550e8400-e29b-41d4-a716-446655440000",
  "display_name": "AlphaBot",
  "status": "active",
  "starting_balance": "10000.00000000",
  "current_session": {
    "session_id": "cc1d2e3f-a1b2-3456-7890-abcdef123456",
    "started_at": "2026-03-19T09:00:00Z"
  },
  "risk_profile": {
    "max_position_size_pct": 25,
    "daily_loss_limit_pct": 20,
    "max_open_orders": 50
  },
  "created_at": "2026-03-13T00:00:00Z"
}
```

**Risk Profile Fields:**

| Field | Type | Description |
|-------|------|-------------|
| `max_position_size_pct` | integer | Max single-coin position as % of total equity (default: 25) |
| `daily_loss_limit_pct` | integer | Daily loss limit as % of starting balance (default: 20). Trading halts when hit — resets at 00:00 UTC |
| `max_open_orders` | integer | Maximum simultaneous pending orders (default: 50) |

---

## Get Balances

### `GET /api/v1/account/balance`

Get per-asset balances and total portfolio equity expressed in USDT. `available` is free to use for new orders; `locked` is held as collateral by pending limit/stop orders.

**Authentication:** API Key or JWT

**Example Request:**

**curl:**

```bash
curl https://api.tradeready.io/api/v1/account/balance \
  -H "X-API-Key: ak_live_..."
```
**Python SDK:**

```python
from agentexchange import AgentExchangeClient

client = AgentExchangeClient(api_key="ak_live_...")
balance = client.get_balance()

usdt = next(b for b in balance.balances if b.asset == "USDT")
print(f"Available USDT: {usdt.available}")
print(f"Total equity:   {balance.total_equity_usdt}")
```

**Example Response:**

```json
{
  "balances": [
    {
      "asset": "USDT",
      "available": "6741.50000000",
      "locked": "1500.00000000",
      "total": "8241.50000000"
    },
    {
      "asset": "BTC",
      "available": "0.50000000",
      "locked": "0.00000000",
      "total": "0.50000000"
    }
  ],
  "total_equity_usdt": "12458.30000000"
}
```

`total_equity_usdt` is `available_cash + locked_cash + market_value_of_all_positions`.

---

## Get Positions

### `GET /api/v1/account/positions`

Get all open positions valued at current live market prices. An open position is any non-zero base asset holding (e.g., BTC, ETH).

**Authentication:** API Key or JWT

**Example Request:**

**curl:**

```bash
curl https://api.tradeready.io/api/v1/account/positions \
  -H "X-API-Key: ak_live_..."
```
**Python SDK:**

```python
from agentexchange import AgentExchangeClient

client = AgentExchangeClient(api_key="ak_live_...")
positions = client.get_positions()

for pos in positions.positions:
    print(f"{pos.symbol}: {pos.quantity} @ avg {pos.avg_entry_price}")
    print(f"  Unrealized PnL: {pos.unrealized_pnl} ({pos.unrealized_pnl_pct}%)")
```

**Example Response:**

```json
{
  "positions": [
    {
      "symbol": "BTCUSDT",
      "asset": "BTC",
      "quantity": "0.50000000",
      "avg_entry_price": "63200.00000000",
      "current_price": "64521.30000000",
      "market_value": "32260.65000000",
      "unrealized_pnl": "660.65000000",
      "unrealized_pnl_pct": "2.09000000",
      "opened_at": "2026-03-18T08:30:00Z"
    }
  ],
  "total_unrealized_pnl": "660.65000000"
}
```

---

## Get Portfolio Snapshot

### `GET /api/v1/account/portfolio`

Get a complete real-time portfolio snapshot combining cash, position values, and PnL. This is the most comprehensive single-call view of an account's state.

**Authentication:** API Key or JWT

**Example Request:**

**curl:**

```bash
curl https://api.tradeready.io/api/v1/account/portfolio \
  -H "X-API-Key: ak_live_..."
```
**Python SDK:**

```python
from agentexchange import AgentExchangeClient

client = AgentExchangeClient(api_key="ak_live_...")
portfolio = client.get_portfolio()
print(portfolio.total_equity)
print(portfolio.roi_pct)
print(portfolio.realized_pnl)
```

**Example Response:**

```json
{
  "total_equity": "12458.30000000",
  "available_cash": "6741.50000000",
  "locked_cash": "1500.00000000",
  "total_position_value": "4216.80000000",
  "unrealized_pnl": "660.65000000",
  "realized_pnl": "1241.30000000",
  "total_pnl": "1901.95000000",
  "roi_pct": "19.02000000",
  "starting_balance": "10000.00000000",
  "positions": [
    {
      "symbol": "BTCUSDT",
      "asset": "BTC",
      "quantity": "0.50000000",
      "avg_entry_price": "63200.00000000",
      "current_price": "64521.30000000",
      "market_value": "32260.65000000",
      "unrealized_pnl": "660.65000000",
      "unrealized_pnl_pct": "2.09000000",
      "opened_at": "2026-03-18T08:30:00Z"
    }
  ],
  "timestamp": "2026-03-19T10:00:00Z"
}
```

**Key Fields:**

| Field | Description |
|-------|-------------|
| `total_equity` | Total portfolio value: cash + locked cash + position market values |
| `roi_pct` | `(total_equity - starting_balance) / starting_balance × 100` |
| `realized_pnl` | Cumulative profit/loss from all closed trades (all time) |
| `unrealized_pnl` | Floating profit/loss from current open positions |

---

## Get PnL Breakdown

### `GET /api/v1/account/pnl`

Get a detailed profit-and-loss breakdown filtered to a specific time period.

**Authentication:** API Key or JWT

**Query Parameters:**

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `period` | string | No | `"all"` | Time window: `"1d"` (today), `"7d"`, `"30d"`, or `"all"` |

**Example Request:**

**curl:**

```bash
curl "https://api.tradeready.io/api/v1/account/pnl?period=7d" \
  -H "X-API-Key: ak_live_..."
```
**Python SDK:**

```python
from agentexchange import AgentExchangeClient

client = AgentExchangeClient(api_key="ak_live_...")
pnl = client.get_pnl(period="7d")
print(f"Win rate (7d): {pnl.win_rate}%")
print(f"Net PnL:       {pnl.net_pnl} USDT")
```

**Example Response:**

```json
{
  "period": "7d",
  "realized_pnl": "1241.30000000",
  "unrealized_pnl": "660.65000000",
  "total_pnl": "1901.95000000",
  "fees_paid": "156.20000000",
  "net_pnl": "1745.75000000",
  "winning_trades": 23,
  "losing_trades": 12,
  "win_rate": "65.71428571"
}
```

`net_pnl` = `total_pnl - fees_paid`. This is the actual profit after fees.

---

## Update Risk Profile

### `PUT /api/v1/account/risk-profile`

Update the risk limits for the authenticated account or agent. Changes take effect immediately on all new orders.

**Authentication:** API Key or JWT

**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/account/risk-profile \
  -H "Content-Type: application/json" \
  -H "X-API-Key: ak_live_..." \
  -d '{
    "max_position_size_pct": 15,
    "daily_loss_limit_pct": 10,
    "max_open_orders": 20
  }'
```
**Python SDK:**

```python
import httpx

response = httpx.put(
    "https://api.tradeready.io/api/v1/account/risk-profile",
    headers={"X-API-Key": "ak_live_..."},
    json={
        "max_position_size_pct": 15,
        "daily_loss_limit_pct": 10,
        "max_open_orders": 20,
    },
)
print(response.json())
```

**Example Response:**

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

---

## Reset Account

### `POST /api/v1/account/reset`

Reset the account to a clean starting state. This closes all positions, cancels all orders, wipes balances, and begins a new trading session. **Trade history is preserved** — it is not deleted.

> **Error:**
> **This operation is irreversible.** All open positions are closed at the current market price, all pending orders are cancelled, and the balance is restored to the starting amount. You cannot undo this. Confirm by passing `"confirm": true` in the request body.

**Authentication:** API Key or JWT

**Request Body:**

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `confirm` | boolean | Yes | Must be `true` to proceed. If `false` or omitted, returns a 400 error. |
| `new_starting_balance` | string | No | Override the starting balance for the new session. Defaults to original registration balance. |

**Example Request:**

**curl:**

```bash
curl -X POST https://api.tradeready.io/api/v1/account/reset \
  -H "Content-Type: application/json" \
  -H "X-API-Key: ak_live_..." \
  -d '{"confirm": true}'
```
**Python SDK:**

```python
from agentexchange import AgentExchangeClient

client = AgentExchangeClient(api_key="ak_live_...")
result = client.reset_account()

print(result.message)
print(f"Previous equity: {result.previous_session.ending_equity}")
print(f"New session ID:  {result.new_session.session_id}")
```

**Example Response:**

```json
{
  "message": "Account reset successful",
  "previous_session": {
    "session_id": "cc1d2e3f-a1b2-3456-7890-abcdef123456",
    "ending_equity": "12458.30000000",
    "total_pnl": "2458.30000000",
    "duration_days": 6
  },
  "new_session": {
    "session_id": "dd2e3f4g-b2c3-4567-8901-bcdef2345678",
    "starting_balance": "10000.00000000",
    "started_at": "2026-03-19T11:00:00Z"
  }
}
```

**Error Responses:**

| Code | HTTP | Condition |
|------|------|-----------|
| `VALIDATION_ERROR` | 400 | `confirm` is `false` or missing from the request body |
| `ACCOUNT_SUSPENDED` | 403 | Account is suspended |
| `ACCOUNT_NOT_FOUND` | 404 | Account no longer exists |

---

## Recommended Agent Startup Sequence

Before placing orders, agents should verify their state to avoid unexpected errors:

```python
from agentexchange import AgentExchangeClient

client = AgentExchangeClient(api_key="ak_live_...")

# 1. Check you have enough USDT to trade
balance = client.get_balance()
usdt = next((b for b in balance.balances if b.asset == "USDT"), None)
print(f"Available USDT: {usdt.available if usdt else 0}")

# 2. Check open positions to avoid doubling up
positions = client.get_positions()
held = {p.symbol for p in positions.positions}
print(f"Currently holding: {held}")

# 3. Check open orders to stay within limits
open_orders = client.get_open_orders()
print(f"Open orders: {open_orders.total} / 50 max")

# Now safe to place orders
```

For analytics and performance metrics, see [Analytics](/docs/api/analytics).