SimuTrade - AI-Powered Simulated Securities Trading

Developer Documentation

Everything you need to integrate SimuTrade (simutrade.ai) into your AI trading applications.

API Reference

Complete REST API documentation with request/response schemas for all endpoints.

Base URL

https://api.simutrade.ai/v1

All endpoints require authentication via the Authorization: Bearer <api_key> header.

Endpoints

GET

/api/v1/market/{symbol}/quote

Get real-time quote for a trading symbol. Supports US stocks, HK stocks, and cryptocurrency.

Parameters

Name	Type	Required	Description
symbol	string	Required	Trading symbol (e.g., AAPL, 0700.HK, BTC-USD)

Response

Response 200

{
  "symbol": "AAPL",
  "name": "Apple Inc.",
  "market": "us",
  "price": 189.84,
  "change": 2.34,
  "changePercent": 1.25,
  "volume": 52340000,
  "high": 191.05,
  "low": 187.45,
  "open": 188.12,
  "previousClose": 187.50,
  "timestamp": "2026-02-20T15:30:00Z"
}

GET

/api/v1/market/{symbol}/history

Get historical OHLCV (Open, High, Low, Close, Volume) data for a symbol.

Parameters

Name	Type	Required	Description
symbol	string	Required	Trading symbol
interval	string	Optional	Candle interval: 1m, 5m, 15m, 1h, 1d (default: 5m)
limit	integer	Optional	Number of candles to return (default: 100, max: 1000)

Response

Response 200

{
  "symbol": "AAPL",
  "interval": "5m",
  "data": [
    {
      "time": "2026-02-20T14:00:00Z",
      "open": 188.50,
      "high": 189.20,
      "low": 188.30,
      "close": 189.00,
      "volume": 125000
    },
    {
      "time": "2026-02-20T14:05:00Z",
      "open": 189.00,
      "high": 189.80,
      "low": 188.90,
      "close": 189.50,
      "volume": 98000
    }
  ]
}

POST

/api/v1/orders

Place a new trading order. Supports market, limit, and stop orders across all markets.

Request Body

Request

{
  "symbol": "AAPL",       // Required: trading symbol
  "side": "buy",          // Required: "buy" or "sell"
  "type": "limit",        // Required: "market", "limit", or "stop"
  "quantity": 10,          // Required: number of shares/units
  "price": 185.00         // Required for limit/stop orders
}

Response

Response 200

{
  "id": "ord-abc123",
  "symbol": "AAPL",
  "name": "Apple Inc.",
  "market": "us",
  "side": "buy",
  "type": "limit",
  "status": "pending",
  "quantity": 10,
  "price": 185.00,
  "filledQuantity": 0,
  "filledPrice": 0,
  "createdAt": "2026-02-20T15:30:00Z",
  "updatedAt": "2026-02-20T15:30:00Z"
}

GET

/api/v1/orders

List orders with optional filters. Returns paginated results sorted by creation date.

Parameters

Name	Type	Required	Description
status	string	Optional	Filter: pending, filled, partial, cancelled
market	string	Optional	Filter: us, hk, crypto
symbol	string	Optional	Filter by specific symbol
limit	integer	Optional	Results per page (default: 50, max: 100)
offset	integer	Optional	Pagination offset (default: 0)

Response

Response 200

{
  "orders": [
    {
      "id": "ord-abc123",
      "symbol": "AAPL",
      "side": "buy",
      "type": "limit",
      "status": "pending",
      "quantity": 10,
      "price": 185.00,
      "filledQuantity": 0,
      "createdAt": "2026-02-20T15:30:00Z"
    }
  ],
  "total": 42,
  "limit": 50,
  "offset": 0
}

DELETE

/api/v1/orders/{id}

Cancel a pending order. Only orders with status 'pending' can be cancelled.

Parameters

Name	Type	Required	Description
id	string	Required	Order ID to cancel

Response

Response 200

{
  "id": "ord-abc123",
  "status": "cancelled",
  "cancelledAt": "2026-02-20T15:35:00Z"
}

GET

/api/v1/portfolio

Get complete portfolio summary including cash balance, positions, and P&L.

Response

Response 200

{
  "summary": {
    "totalValue": 145678.90,
    "cashBalance": 53922.70,
    "holdingsValue": 91756.20,
    "todayPnL": 1245.30,
    "todayPnLPercent": 0.86,
    "totalPnL": 6146.20,
    "totalPnLPercent": 4.41
  },
  "positions": [
    {
      "symbol": "AAPL",
      "name": "Apple Inc.",
      "market": "us",
      "quantity": 50,
      "avgCost": 175.20,
      "currentPrice": 189.84,
      "marketValue": 9492.00,
      "unrealizedPnL": 732.00,
      "unrealizedPnLPercent": 8.35
    }
  ]
}

GET

/api/v1/account

Get account information including plan details and API usage statistics.

Response

Response 200

{
  "id": "acc-001",
  "email": "[email protected]",
  "displayName": "Developer",
  "plan": "pro",
  "apiCalls": {
    "today": 342,
    "limit": 10000,
    "resetAt": "2026-02-21T00:00:00Z"
  },
  "createdAt": "2026-01-15T10:00:00Z"
}

POST

/v1/accounts/{accountId}/risk-control/rules

Create a risk control rule. Supports stop loss, take profit, trailing stop, and position limit rules at order, position, or account level.

Parameters

Name	Type	Required	Description
accountId	string	Required	Account ID

Request Body

Request

{
  "ruleType": "stop_loss",
  "config": {
    "type": "percentage",
    "percentage": 5.0,
    "enabled": true
  },
  "symbol": "AAPL",
  "isActive": true
}

Response

Response 200

{
  "rule": {
    "id": "rule-abc123",
    "accountId": "acc-001",
    "symbol": "AAPL",
    "ruleType": "stop_loss",
    "config": {
      "type": "percentage",
      "percentage": 5.0,
      "enabled": true
    },
    "isActive": true,
    "createdAt": "2026-02-20T15:00:00Z"
  }
}

GET

/v1/accounts/{accountId}/risk-control/rules

List risk control rules. Supports filtering by orderId, symbol, ruleType, and isActive.

Parameters

Name	Type	Required	Description
accountId	string	Required	Account ID
orderId	string	Optional	Filter by order ID
symbol	string	Optional	Filter by symbol
ruleType	string	Optional	Filter by rule type
isActive	boolean	Optional	Filter by active status

Response

Response 200

{
  "rules": [
    {
      "id": "rule-abc123",
      "ruleType": "stop_loss",
      "symbol": "AAPL",
      "isActive": true
    }
  ]
}

GET

/v1/accounts/{accountId}/risk-control/executions

List risk control execution records. System automatically checks rules every 30 seconds.

Parameters

Name	Type	Required	Description
accountId	string	Required	Account ID
ruleId	string	Optional	Filter by rule ID
status	string	Optional	Filter by status
limit	integer	Optional	Number of records (default: 50)

Response

Response 200

{
  "executions": [
    {
      "id": "exec-xyz789",
      "ruleId": "rule-abc123",
      "triggeredAt": "2026-02-20T15:30:00Z",
      "triggerPrice": 180.50,
      "currentPrice": 180.45,
      "status": "triggered",
      "action": "alert"
    }
  ],
  "total": 1
}

Error Codes

The API uses standard HTTP status codes. Error responses include a JSON body with details:

Error Response

{
  "error": {
    "code": "INSUFFICIENT_BALANCE",
    "message": "Not enough cash balance to place this order",
    "details": {
      "required": 1850.00,
      "available": 1200.50
    }
  }
}

Status	Code	Description
400	INVALID_REQUEST	Request body or parameters are invalid
401	UNAUTHORIZED	API key is missing or invalid
403	FORBIDDEN	API key lacks required permission
404	NOT_FOUND	Resource not found
409	ORDER_NOT_CANCELLABLE	Order is not in a cancellable state
422	INSUFFICIENT_BALANCE	Not enough cash to place the order
422	INVALID_SYMBOL	Trading symbol not found
422	MARKET_CLOSED	Market is currently closed
429	RATE_LIMITED	Too many requests, slow down
500	INTERNAL_ERROR	Internal server error