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 https://api.tradeready.io/api/v1/account/info \
  -H "X-API-Key: ak_live_..."

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:

{
  "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 https://api.tradeready.io/api/v1/account/balance \
  -H "X-API-Key: ak_live_..."

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:

{
  "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 https://api.tradeready.io/api/v1/account/positions \
  -H "X-API-Key: ak_live_..."

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:

{
  "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 https://api.tradeready.io/api/v1/account/portfolio \
  -H "X-API-Key: ak_live_..."

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:

{
  "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 "https://api.tradeready.io/api/v1/account/pnl?period=7d" \
  -H "X-API-Key: ak_live_..."

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:

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

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:

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

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 -X POST https://api.tradeready.io/api/v1/account/reset \
  -H "Content-Type: application/json" \
  -H "X-API-Key: ak_live_..." \
  -d '{"confirm": true}'

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:

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

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.

Account Management

Account Management

Get Account Info

GET /api/v1/account/info

Get Balances

GET /api/v1/account/balance

Get Positions

GET /api/v1/account/positions

Get Portfolio Snapshot

GET /api/v1/account/portfolio

Get PnL Breakdown

GET /api/v1/account/pnl

Update Risk Profile

PUT /api/v1/account/risk-profile

Reset Account

POST /api/v1/account/reset

Recommended Agent Startup Sequence

On this page

`GET /api/v1/account/info`

`GET /api/v1/account/balance`

`GET /api/v1/account/positions`

`GET /api/v1/account/portfolio`

`GET /api/v1/account/pnl`

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

`POST /api/v1/account/reset`