REST Endpoints

The Trading API provides REST endpoints for order management, position tracking, trade history, account information, and market data. All endpoints return JSON responses.

Base URL

The REST API is available at the same host as the WebSocket connection:

Backtest mode: http://localhost:8080
Live trading: http://localhost:8080 (proxy)

Authentication

Include your API credentials in the request headers as configured during connection setup. See the Connection Guide for details.

Response Format

All successful responses return JSON. Error responses use a standard format:

{
  "code": "ORDER_NOT_FOUND",
  "message": "Order not found: abc123",
  "details": { "resource": "order", "id": "abc123" }
}

Common Status Codes

Status	Description
200	Success
201	Created (for POST /orders)
400	Invalid request parameters
404	Resource not found
409	Conflict (e.g., order not modifiable)
422	Order rejected
503	Provider unavailable

Orders

POST /orders

Submit a new order.

Request Body (OrderRequest)

Field	Type	Required	Description
`symbol`	string	Yes	Trading symbol (e.g., "AAPL", "EUR/USD")
`side`	string	Yes	`BUY` or `SELL`
`quantity`	string	Yes	Order quantity (decimal string)
`order_type`	string	Yes	`MARKET`, `LIMIT`, `STOP`, `STOP_LIMIT`, `TRAILING_STOP`
`limit_price`	string	No	Required for LIMIT and STOP_LIMIT orders
`stop_price`	string	No	Required for STOP and STOP_LIMIT orders
`time_in_force`	string	No	`GTC` (default), `DAY`, `IOC`, `FOK`
`client_order_id`	string	No	Client-provided ID for idempotency
`stop_loss`	string	No	Stop loss price for bracket order
`take_profit`	string	No	Take profit price for bracket order
`reduce_only`	boolean	No	If true, can only reduce position
`post_only`	boolean	No	If true, reject if would immediately fill
`oco_group_id`	string	No	Link orders for one-cancels-other
`hidden`	boolean	No	If true, order not visible in order book
`display_quantity`	string	No	Visible quantity for iceberg orders
`leverage`	string	No	Leverage multiplier
`margin_mode`	string	No	`CROSS` or `ISOLATED` margin mode
`position_id`	string	No	Target position ID (for hedging accounts)
`trailing_distance`	string	No	Distance for TRAILING_STOP orders
`trailing_type`	string	No	`ABSOLUTE` or `PERCENT` trailing type

Example Request

{
  "symbol": "AAPL",
  "side": "BUY",
  "quantity": "100",
  "order_type": "LIMIT",
  "limit_price": "150.00",
  "time_in_force": "GTC"
}

Response (201 Created)

Returns an OrderHandle with the assigned order ID:

{
  "id": "ord_abc123",
  "status": "PENDING",
  "client_order_id": null
}

Error Responses

400 - Invalid request (missing required fields, invalid values)
422 - Order rejected (insufficient margin, invalid price, etc.)
503 - Provider unavailable

GET /orders

List open orders.

Query Parameters

Parameter	Type	Description
`symbol`	string	Filter by symbol
`status`	string[]	Filter by status (multiple allowed)
`side`	string	Filter by side (`BUY` or `SELL`)
`client_order_id`	string	Filter by client order ID
`oco_group_id`	string	Filter by OCO group ID
`since`	datetime	Filter orders created after this time
`until`	datetime	Filter orders created before this time
`limit`	integer	Maximum number of orders to return

Response (200 OK)

[
  {
    "id": "ord_abc123",
    "symbol": "AAPL",
    "side": "BUY",
    "order_type": "LIMIT",
    "quantity": "100",
    "filled_quantity": "0",
    "remaining_quantity": "100",
    "limit_price": "150.00",
    "status": "OPEN",
    "time_in_force": "GTC",
    "created_at": "2025-01-15T10:30:00Z",
    "updated_at": "2025-01-15T10:30:00Z"
  }
]

GET /orders/{order_id}

Get a specific order by ID.

Path Parameters

Parameter	Type	Description
`order_id`	string	The order ID

Response (200 OK)

Returns the full Order object (same schema as list response items).

Error Responses

404 - Order not found
503 - Provider unavailable

PATCH /orders/{order_id}

Modify an existing order. Only non-null fields will be updated.

Path Parameters

Parameter	Type	Description
`order_id`	string	The order ID

Request Body (ModifyOrderRequest)

Field	Type	Description
`quantity`	string	New total quantity (must be >= filled_quantity)
`limit_price`	string	New limit price
`stop_price`	string	New stop price
`stop_loss`	string	New stop loss price
`take_profit`	string	New take profit price
`trailing_distance`	string	New trailing distance

Example Request

{
  "limit_price": "151.00"
}

Response (200 OK)

Returns the updated Order object.

Error Responses

400 - Invalid request
404 - Order not found
409 - Order not modifiable (already filled, cancelled, etc.)
503 - Provider unavailable

DELETE /orders/{order_id}

Cancel a specific order.

Path Parameters

Parameter	Type	Description
`order_id`	string	The order ID

Response (200 OK)

{
  "success": true,
  "order": {
    "id": "ord_abc123",
    "status": "CANCELLED",
    ...
  }
}

Error Responses

404 - Order not found
503 - Provider unavailable

DELETE /orders

Cancel all open orders.

Query Parameters

Parameter	Type	Description
`symbol`	string	Filter by symbol (optional, omit to cancel all)

Response (200 OK)

{
  "cancelled_count": 5,
  "failed_count": 0,
  "failed_order_ids": null
}

GET /orders/history

Get historical orders (filled, cancelled, rejected, expired).

Query Parameters

Same as GET /orders.

Response (200 OK)

Returns an array of Order objects.

Positions

GET /positions

Get all open positions.

Query Parameters

Parameter	Type	Description
`symbol`	string	Filter by symbol (optional)

Response (200 OK)

[
  {
    "id": "pos_xyz789",
    "symbol": "AAPL",
    "side": "LONG",
    "quantity": "100",
    "average_entry_price": "150.25",
    "current_price": "151.50",
    "unrealized_pnl": "125.00",
    "realized_pnl": "0",
    "opened_at": "2025-01-15T10:30:01Z",
    "updated_at": "2025-01-15T11:00:00Z"
  }
]

GET /positions/{position_id}

Get a specific position by ID.

Path Parameters

Parameter	Type	Description
`position_id`	string	The position ID

Response (200 OK)

Returns the full Position object.

Error Responses

404 - Position not found
503 - Provider unavailable

DELETE /positions/{position_id}

Close a specific position.

Path Parameters

Parameter	Type	Description
`position_id`	string	The position ID

Request Body (optional)

Field	Type	Description
`quantity`	string	Quantity to close (omit for full close)
`order_type`	string	`MARKET` (default) or `LIMIT`
`limit_price`	string	Required if order_type is LIMIT
`cancel_associated_orders`	boolean	Cancel SL/TP orders (default: true)

Response (200 OK)

Returns an OrderHandle for the close order.

Error Responses

404 - Position not found
503 - Provider unavailable

DELETE /positions

Close all open positions.

Query Parameters

Parameter	Type	Description
`symbol`	string	Filter by symbol (optional, omit to close all)

Response (200 OK)

Returns an array of OrderHandle objects for each close order created.

Trades

GET /trades

Get trade/fill history.

Query Parameters

Parameter	Type	Description
`symbol`	string	Filter by symbol
`order_id`	string	Filter by order ID
`since`	datetime	Return trades after this time (inclusive)
`until`	datetime	Return trades before this time (exclusive)
`limit`	integer	Maximum number of trades to return

Response (200 OK)

[
  {
    "id": "trd_def456",
    "order_id": "ord_abc123",
    "symbol": "AAPL",
    "side": "BUY",
    "quantity": "100",
    "price": "150.25",
    "commission": "0.50",
    "commission_currency": "USD",
    "is_maker": false,
    "timestamp": "2025-01-15T10:30:01Z"
  }
]

Account

GET /account

Get account information including balances and margin.

Response (200 OK)

{
  "balance": "10000.00",
  "equity": "10500.00",
  "margin_used": "2000.00",
  "margin_available": "8500.00",
  "unrealized_pnl": "500.00",
  "currency": "USD"
}

Error Responses

400 - Invalid request
503 - Provider unavailable

Market Data

GET /quotes/{symbol}

Get the current quote for a symbol.

Path Parameters

Parameter	Type	Description
`symbol`	string	Symbol (e.g., "AAPL", "BTC/USD")

Response (200 OK)

{
  "symbol": "AAPL",
  "provider": "alpaca",
  "bid": "150.20",
  "bid_size": "100",
  "ask": "150.25",
  "ask_size": "200",
  "last": "150.22",
  "timestamp": "2025-01-15T10:30:00.123Z"
}

Error Responses

404 - Symbol not found
503 - Provider unavailable

GET /bars/{symbol}

Get historical OHLCV bars for a symbol.

Path Parameters

Parameter	Type	Description
`symbol`	string	Symbol (e.g., "S:AAPL", "C:BTCUSD")

Query Parameters

Parameter	Type	Required	Description
`timeframe`	string	Yes	Bar interval: `1m`, `5m`, `15m`, `30m`, `1h`, `4h`, `1d`, `1w`
`start`	datetime	No	Start of date range (inclusive)
`end`	datetime	No	End of date range (inclusive)
`limit`	integer	No	Maximum number of bars to return

Response (200 OK)

[
  {
    "symbol": "AAPL",
    "provider": "polygon",
    "timeframe": "1h",
    "timestamp": "2025-01-15T10:00:00Z",
    "open": "150.00",
    "high": "151.50",
    "low": "149.75",
    "close": "151.25",
    "volume": "1234567"
  }
]

Error Responses

400 - Invalid request (bad timeframe or symbol)
404 - Symbol not found
503 - Provider unavailable

System

GET /capabilities

Get provider capabilities describing supported features.

Response (200 OK)

{
  "supported_asset_classes": ["STOCK", "CRYPTO"],
  "supported_order_types": ["MARKET", "LIMIT", "STOP", "STOP_LIMIT"],
  "position_mode": "NETTING",
  "features": ["trailing_stop", "oco", "bracket_orders"],
  "max_leverage": "20"
}

GET /status

Get connection status to the trading provider.

Response (200 OK)

{
  "connected": true,
  "latency_ms": 15,
  "last_heartbeat": "2025-01-15T10:30:00Z"
}

GET /health

Health check endpoint for liveness probes. Returns 200 OK if the service is running.

Response (200 OK)

{
  "status": "ok"
}

Use this endpoint for Kubernetes liveness probes. It does not check provider connections.

GET /ready

Readiness check endpoint for readiness probes. Returns 200 OK if providers are configured.

Response (200 OK)

{
  "ready": true,
  "providers": ["alpaca-paper"],
  "provider_count": 1
}

Response (503 Service Unavailable)

Returned when no providers are configured:

{
  "ready": false,
  "providers": [],
  "provider_count": 0,
  "message": "No providers configured"
}

Use this endpoint for Kubernetes readiness probes.

REST Endpoints

Base URL

Authentication

Response Format

Common Status Codes

Orders

POST /orders

GET /orders

GET /orders/{order_id}

PATCH /orders/{order_id}

DELETE /orders/{order_id}

DELETE /orders

GET /orders/history

Positions

GET /positions

GET /positions/{position_id}

DELETE /positions/{position_id}

DELETE /positions

Trades

GET /trades

Account

GET /account

Market Data

GET /quotes/{symbol}

GET /bars/{symbol}

System

GET /capabilities

GET /status

GET /health

GET /ready

Related Documentation