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 Gateway exposes REST and WebSocket on the same host and port (default http://localhost:8080). Every REST endpoint is versioned under the /v1/ prefix — for example GET http://localhost:8080/v1/orders.

The only unversioned paths are the Kubernetes-style health probes served at the host root:

• GET /health — overall health
• GET /livez — liveness probe
• GET /readyz — readiness probe

The same Base URL applies whether the Gateway is running in backtest, paper, or live mode — mode selection is a server-side GATEWAY_PROVIDER / GATEWAY_MODE concern, not a client URL change.

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 ApiError body:

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

code is the machine-readable discriminator (see the Error Codes and Retry Strategy section below), message is a human-readable description, and details carries per-code structured context (may be absent).

Common Status Codes

Error Codes and Retry Strategy

Every error response carries a machine-readable code field. Client libraries should branch on code, not on message.

Canonical ErrorCode enumeration

Rate Limiting (429)

The Gateway returns RATE_LIMITED when either its own ingress limits or the upstream provider's limits are hit. The details object carries retry hints:

{
  "code": "RATE_LIMITED",
  "message": "Rate limit exceeded",
  "details": {
    "retry_after_seconds": 30,
    "reset_at": "2025-01-15T10:31:00Z"
  }
}

• retry_after_seconds — how long to wait before the next request (integer seconds, may be absent if the provider didn't supply a hint).
• reset_at — absolute UTC timestamp when the window resets (ISO-8601, may be absent).

Prefer retry_after_seconds when both are present; fall back to computing the delay from reset_at otherwise. Where neither is present, fall back to the exponential backoff schedule below. Add jitter to whichever value you pick to avoid thundering herds.

Note: the Gateway does not currently set an HTTP Retry-After header — this is a deliberate deviation from RFC 6585 / 7231. Clients that rely on library-level header-based retry logic should be configured to read the JSON body instead.

Retryable codes are RATE_LIMITED, PROVIDER_UNAVAILABLE, and PROVIDER_ERROR. ORDER_REJECTED is only retryable when the rejection is explicitly transient — case-insensitive self-trade or wash in the message field (or in a passthrough details.reject_code) are the two the Gateway classifies as retryable. Everything else is terminal — surface the error to the caller, do not retry blindly.

Retry Schedule

For retryable errors (including 429 with no explicit hint and 503 PROVIDER_UNAVAILABLE), use exponential backoff with full jitter:

After the max-attempts budget is exhausted, surface the error to the strategy — do not keep retrying indefinitely.

Idempotent retries for POST endpoints

POST /v1/orders is not idempotent by default. If the original request reached the Gateway and an upstream timeout or connection drop happened after the order was placed but before the response landed, a naive retry creates a duplicate order.

Always supply a stable client_order_id when retrying a POST /v1/orders call:

1. Generate the client_order_id before the first attempt (e.g. a UUID).
2. Reuse the same client_order_id on every retry of the same logical order.
3. On an ambiguous failure, query GET /v1/orders?client_order_id=<id> before retrying — if the order already exists, reconcile rather than re-submit.

DELETE and PATCH endpoints are naturally idempotent by target id; the same retry schedule applies to them without extra safeguards.

ORDER_REJECTED details

422 responses carry the broker's rejection reason in details.reject_code. The Gateway normalises a small set of canonical values; broker-specific strings (for example OANDA's INSUFFICIENT_MARGIN, MARKET_HALTED) pass through unchanged for codes that aren't in the canonical list.

Canonical reject_code values:

{
  "code": "ORDER_REJECTED",
  "message": "Order rejected: insufficient funds for order",
  "details": {
    "reject_code": "INSUFFICIENT_FUNDS"
  }
}

Orders

POST /v1/orders

Submit a new order.

Request Body (OrderRequest)

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

GET /v1/orders

List open orders.

Query Parameters

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 /v1/orders/{order_id}

Get a specific order by ID.

Path Parameters

Response (200 OK)

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

Error Responses

PATCH /v1/orders/{order_id}

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

Path Parameters

Request Body (ModifyOrderRequest)

Example Request

{
  "limit_price": "151.00"
}

Response (200 OK) — ModifyOrderResult

Example

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

Error Responses

DELETE /v1/orders/{order_id}

Cancel a specific order.

Path Parameters

Response (200 OK)

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

Error Responses

DELETE /v1/orders

Cancel all open orders.

Query Parameters

Response (200 OK)

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

GET /v1/orders/history

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

Query Parameters

Same as GET /v1/orders.

Response (200 OK)

Returns an array of Order objects.

Positions

GET /v1/positions

Get all open positions.

Query Parameters

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 /v1/positions/{position_id}

Get a specific position by ID.

Path Parameters

Response (200 OK)

Returns the full Position object.

Error Responses

• 404 - Position not found
• 503 - Provider unavailable

DELETE /v1/positions/{position_id}

Close a specific position.

Path Parameters

Request Body (optional)

Response (200 OK)

Returns an OrderHandle for the close order.

Error Responses

• 404 - Position not found
• 503 - Provider unavailable

DELETE /v1/positions

Close all open positions.

Query Parameters

Response (200 OK)

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

Trades

GET /v1/trades

Get trade/fill history.

Query Parameters

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 /v1/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 /v1/quotes/{symbol}

Get the current quote for a symbol.

Path Parameters

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 /v1/bars/{symbol}

Get historical OHLCV bars for a symbol.

Path Parameters

Query Parameters

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 /v1/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 /v1/status

Get connection status to the trading provider.

Response (200 OK)

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

GET /v1/circuit-breakers

Inspect the state of the Gateway's two internal circuit breakers. Useful for diagnosing a Gateway that is refusing traffic because an upstream breaker has tripped.

The Gateway runs two breakers:

• adapter — trips when the upstream broker adapter (Alpaca, Binance, etc.) produces repeated failures. Prevents hammering a provider that is already failing.
• exit_order — trips when stop-loss / take-profit placement repeatedly fails. Prevents opening unprotected positions when SL/TP submission is unreliable.

Response (200 OK) — CircuitBreakerStatusResponse

CircuitBreakerSnapshot schema

Example

{
  "adapter": { "state": "closed", "failure_count": 0 },
  "exit_order": { "state": "open", "failure_count": 5 }
}

POST /v1/circuit-breakers/reset

Atomically reset both circuit breakers to the closed state. Intended for operator use after the upstream condition has been resolved.

Request Body — none. The endpoint resets both breakers in a single call; it does not accept a per-breaker selector.

Response (200 OK) — CircuitBreakerStatusResponse

Returns the post-reset snapshot, using the same schema as GET /v1/circuit-breakers. Both state fields will be "closed" and both failure_count fields will be 0 on a successful reset.

Response (409 Conflict) — ApiError with code: RESET_COOLDOWN

Returned when either breaker re-trips within 60 seconds of the last successful reset. The 60-second cooldown prevents reset loops while the upstream condition is still unstable. Clients should back off and retry once the underlying provider or SL/TP placement issue is resolved.

Health probes

The Gateway exposes three unversioned probes at the host root. These are intended for Kubernetes-style liveness and readiness checks and do not carry a /v1/ prefix.

GET /health

Overall health check. Returns 200 OK if the service is running.

Response (200 OK)

{
  "status": "ok"
}

GET /livez

Liveness probe. Returns 200 OK whenever the Gateway process is responsive, independent of provider state. Use this for Kubernetes livenessProbe.

GET /readyz

Readiness probe. Returns 200 OK only when at least one provider is configured and ready to serve traffic. Use this for Kubernetes readinessProbe.

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

Related Documentation

• WebSocket Messages - Real-time event streaming
• Order Types - Full order schema reference
• Position Types - Full position schema reference
• Connection Guide - How to connect to the Trading API