Broker

GET /v1/broker/supported

List all supported brokers. No authentication required.

curl https://agents.systemr.ai/v1/broker/supported

Response (200):

{
  "brokers": [
    {"id": "ibkr", "description": "Interactive Brokers. Official API. Equities, options, futures, forex."},
    {"id": "schwab", "description": "Charles Schwab. Official API. Equities, options."},
    {"id": "alpaca", "description": "Alpaca Markets. API-first broker. US equities, options, crypto."},
    {"id": "binance", "description": "Binance. Official REST API. Spot and USDT-M futures."},
    {"id": "demo", "description": "Paper trading. No real orders. Safe for testing."}
  ],
  "count": 25
}

POST /v1/broker/connect

Connect the agent to a broker.

Sandbox agents can only connect to demo. Live agents can connect to any supported broker.

curl -X POST https://agents.systemr.ai/v1/broker/connect \
  -H "X-API-Key: sr_agent_..." \
  -H "Content-Type: application/json" \
  -d '{
    "broker_type": "alpaca",
    "connection_params": {
      "api_key": "PKXXXXXXXXXX",
      "api_secret": "XXXXXXXXXXXXXXXX",
      "paper": "true"
    }
  }'

Field	Type	Required	Description
`broker_type`	string	Yes	Broker ID (see supported list).
`connection_params`	object	No	Broker-specific credentials. Not required for `demo`.

Response (200):

{
  "agent_id": "agt_a1b2c3d4",
  "broker_type": "alpaca",
  "connected": true,
  "account_id": "PA1234567",
  "equity": "100000.00",
  "buying_power": "200000.00",
  "message": "Connected to alpaca broker."
}

POST /v1/broker/disconnect

Disconnect the agent’s broker session.

curl -X POST https://agents.systemr.ai/v1/broker/disconnect \
  -H "X-API-Key: sr_agent_..."

Response (200):

{
  "agent_id": "agt_a1b2c3d4",
  "disconnected": true,
  "message": "Broker disconnected."
}

GET /v1/broker/account

Get broker account information.

curl https://agents.systemr.ai/v1/broker/account \
  -H "X-API-Key: sr_agent_..."

Response (200):

{
  "agent_id": "agt_a1b2c3d4",
  "account_id": "PA1234567",
  "broker": "alpaca",
  "equity": "100000.00",
  "cash": "50000.00",
  "buying_power": "200000.00",
  "margin_used": "50000.00",
  "margin_available": "150000.00",
  "day_trades_remaining": 3,
  "is_active": true
}

GET /v1/broker/positions

Get current broker positions.

curl https://agents.systemr.ai/v1/broker/positions \
  -H "X-API-Key: sr_agent_..."

Response (200):

{
  "agent_id": "agt_a1b2c3d4",
  "positions": [
    {
      "symbol": "AAPL",
      "quantity": "363",
      "avg_entry_price": "185.50",
      "current_price": "188.25",
      "market_value": "68334.75",
      "unrealized_pnl": "998.25",
      "unrealized_pnl_pct": "1.48"
    }
  ],
  "count": 1
}

POST /v1/broker/order

Place a broker order. Cost: $0.015. Runs risk validation before submission.

curl -X POST https://agents.systemr.ai/v1/broker/order \
  -H "X-API-Key: sr_agent_..." \
  -H "Content-Type: application/json" \
  -d '{
    "symbol": "AAPL",
    "side": "buy",
    "quantity": "100",
    "order_type": "limit",
    "limit_price": "185.50"
  }'

Field	Type	Required	Description
`symbol`	string	Yes	Instrument symbol.
`side`	string	Yes	`buy` or `sell`.
`quantity`	string	Yes	Number of shares/contracts.
`order_type`	string	Yes	`market`, `limit`, `stop`, or `stop_limit`.
`limit_price`	string	Conditional	Required for `limit` and `stop_limit`.
`stop_price`	string	Conditional	Required for `stop` and `stop_limit`.

Response (200):

{
  "order_id": "ord_abc123",
  "symbol": "AAPL",
  "direction": "long",
  "order_type": "limit",
  "quantity": "100",
  "status": "pending",
  "filled_quantity": "0",
  "limit_price": "185.50",
  "stop_price": null,
  "avg_fill_price": null,
  "broker_order_id": "broker-12345",
  "created_at": "2026-03-25T14:30:00Z"
}

POST /v1/broker/order/{order_id}/cancel

Cancel a pending order.

curl -X POST https://agents.systemr.ai/v1/broker/order/ord_abc123/cancel \
  -H "X-API-Key: sr_agent_..."

Response (200):

{
  "order_id": "ord_abc123",
  "cancelled": true,
  "message": "Order cancelled."
}

GET /v1/broker/orders

List all orders for the agent.

curl https://agents.systemr.ai/v1/broker/orders \
  -H "X-API-Key: sr_agent_..."

Response (200):

{
  "agent_id": "agt_a1b2c3d4",
  "orders": [
    {
      "order_id": "ord_abc123",
      "symbol": "AAPL",
      "direction": "long",
      "order_type": "limit",
      "quantity": "100",
      "status": "filled",
      "filled_quantity": "100",
      "limit_price": "185.50",
      "avg_fill_price": "185.48",
      "created_at": "2026-03-25T14:30:00Z"
    }
  ],
  "count": 1
}