Tradeboard API Documentation
This directory documents the registered Tradeboard v1 REST API and the separate WebSocket protocol. The source of truth for REST registration is restx_api/__init__.py; request validation is defined in restx_api/schemas.py, restx_api/data_schemas.py, restx_api/account_schema.py, and restx_api/strategy_schema.py.
Base URLs
REST API: http://127.0.0.1:5000/api/v1
WebSocket: ws://127.0.0.1:8765Replace the local host with the configured HTTPS/WSS domain in a remote deployment.
Authentication
Most POST endpoints accept the Tradeboard API key as apikey in a JSON object. GET endpoints accept it as the apikey query parameter. Telegram and WhatsApp management endpoints may also accept X-API-KEY; the Telegram webhook authenticates with X-Telegram-Bot-Api-Secret-Token instead of an Tradeboard key.
{
"apikey": "<your_app_apikey>"
}Never put broker credentials or broker access tokens in these requests. The Tradeboard API key resolves the active broker session server-side.
Strict Request Validation
POST bodies are deserialized by marshmallow schemas that do not set Meta.unknown, so marshmallow's default of RAISE applies: a field the schema does not declare makes the whole request fail with HTTP 400, even when every other field is valid. Treat each endpoint page's request-body table as the exact allowed field set rather than a summary. The GTT place and modify schemas set unknown = EXCLUDE and silently drop extras instead; chart preferences sets unknown = INCLUDE because arbitrary preference keys are the point of that resource.
GET resources (/instruments, /ticker/<symbol>, /chart, /telegram/*) read query parameters directly and ignore unrecognized ones.
Registered REST Inventory
The current v1 surface contains 71 method/path pairs. A resource with both GET and POST counts as two endpoints.
Order Management
| Method | Path | Documentation |
|---|---|---|
| POST | /placeorder | Place order |
| POST | /placesmartorder | Place smart order |
| POST | /optionsorder | Options order |
| POST | /optionsmultiorder | Options multi-order |
| POST | /basketorder | Basket order |
| POST | /splitorder | Split order |
| POST | /modifyorder | Modify order |
| POST | /cancelorder | Cancel order |
| POST | /cancelallorder | Cancel all orders |
| POST | /closeposition | Close positions |
| POST | /placegttorder | Place GTT |
| POST | /modifygttorder | Modify GTT |
| POST | /cancelgttorder | Cancel GTT |
| POST | /gttorderbook | GTT order book |
Order And Account Information
| Method | Path | Documentation |
|---|---|---|
| POST | /orderstatus | Order status |
| POST | /openposition | Open position |
| POST | /funds | Funds |
| POST | /margin | Margin |
| POST | /orderbook | Order book |
| POST | /tradebook | Trade book |
| POST | /positionbook | Position book |
| POST | /holdings | Holdings |
Market Data And Symbols
| Method | Path | Documentation |
|---|---|---|
| POST | /quotes | Quote |
| POST | /multiquotes | Multiple quotes |
| POST | /depth | Market depth |
| POST | /history | Historical candles |
| POST | /intervals | Supported intervals |
| GET | /ticker/<string:symbol> | Ticker-compatible history |
| POST | /symbol | Symbol information |
| POST | /search | Symbol search |
| POST | /expiry | Expiry dates |
| GET | /instruments | Instrument master |
Options Analytics
| Method | Path | Documentation |
|---|---|---|
| POST | /optionsymbol | Resolve option symbol |
| POST | /optionchain | Option chain |
| POST | /syntheticfuture | Synthetic future |
| POST | /optiongreeks | Option Greeks |
| POST | /multioptiongreeks | Batch option Greeks |
Calendar, Analyzer, And Preferences
| Method | Path | Documentation |
|---|---|---|
| POST | /market/holidays | Market holidays |
| POST | /market/timings | Market timings |
| POST | /analyzer | Analyzer status |
| POST | /analyzer/toggle | Toggle analyzer mode |
| POST | /pnl/symbols | Sandbox P&L by symbol |
| GET | /chart | Read chart preferences |
| POST | /chart | Update chart preferences |
| POST | /ping | Authenticated ping |
There is no public /api/v1/checkholiday endpoint. Use /market/timings for a date; its response identifies holiday/closed sessions through the returned market schedule.
Portfolio Analytics
| Method | Path | Documentation |
|---|---|---|
| GET | /portfolio/benchmarks | Portfolio API |
| POST | /portfolio/backtest | Portfolio API |
| POST | /portfolio/tearsheet | Portfolio API |
| POST | /portfolio/holdings | Portfolio API |
Portfolio endpoints are authenticated and read-only. The holdings resource reads the active broker account, but none of these resources places, modifies, or cancels an order.
Strategy RMS Engine
The Strategy RMS Engine lifecycle and audit surface is under /strategy. It contains nine authenticated RESTX routes; strategy creation, editing, live enablement, token rotation, and deletion remain browser/session operations.
| Method | Path | Documentation |
|---|---|---|
| POST | /strategy/list | List strategies |
| POST | /strategy/status | Strategy status |
| POST | /strategy/start | Start run |
| POST | /strategy/stop | Stop run |
| POST | /strategy/close_all | Close all legs |
| POST | /strategy/close_leg | Close one leg |
| POST | /strategy/runs | Run history |
| POST | /strategy/orders | Order history |
| POST | /strategy/events | Risk event audit trail |
The public alert endpoint is POST /strategy/webhook/<token>. It is deliberately outside /api/v1, uses the URL token rather than apikey, and is documented separately in Public Strategy Webhook. It is not included in the 71 RESTX route count above.
SIP Analytics
| Method | Path | Documentation |
|---|---|---|
| GET | /sip/frequencies | SIP Backtest |
| POST | /sip/backtest | SIP Backtest |
/sip/backtest validates against SipBacktestSchema and requires a valid API key; source: "api" additionally requires a broker session. /sip/frequencies returns the frequency list the engine supports and is the one v1 resource that does not verify the API key. Both use SIP_API_RATE_LIMIT, default 10 per minute.
Messaging
| Method | Path | Documentation |
|---|---|---|
| GET, POST | /telegram/config | Telegram REST surface |
| POST | /telegram/start | Telegram REST surface |
| POST | /telegram/stop | Telegram REST surface |
| POST | /telegram/webhook | Telegram REST surface |
| GET | /telegram/users | Telegram REST surface |
| POST | /telegram/broadcast | Telegram REST surface |
| POST | /telegram/notify | Telegram REST surface |
| GET | /telegram/stats | Telegram REST surface |
| GET, POST | /telegram/preferences | Telegram REST surface |
| POST | /whatsapp/notify | WhatsApp notification |
The Telegram resource contributes 11 method/path pairs. Its webhook acknowledges validated updates but does not yet dispatch them, and the REST broadcast handler currently returns zero delivery counts. Those limitations are documented on the Telegram page.
WebSocket Protocol
WebSocket streaming is not mounted below /api/v1. Clients connect to the proxy on port 8765, authenticate, and send action messages.
| Mode | Documentation |
|---|---|
| LTP | LTP subscription |
| Quote | Quote subscription |
| Depth | Depth subscription |
Supported actions are authenticate, subscribe, unsubscribe, unsubscribe_all, subscribe_orders, unsubscribe_orders, get_broker_info, get_supported_brokers, and ping.
Order Constants
Exchanges
NSE, BSE, NFO, BFO, CDS, BCD, MCX, NCDEX, NCO, NSE_INDEX, BSE_INDEX, MCX_INDEX, GLOBAL_INDEX, and CRYPTO are recognized by the shared validation constants. Broker capability metadata determines which subset is usable for the active broker.
Products And Price Types
| Kind | Values |
|---|---|
| Product | MIS, CNC, NRML |
| Price type | MARKET, LIMIT, SL, SL-M |
| Action | BUY, SELL (lowercase is normalized by order schemas) |
Regular order, smart-order, basket, split, and modify schemas accept numeric quantities. Fractional quantities are allowed only for CRYPTO; non-crypto quantities must be whole numbers. Options order quantities remain positive integers.
Response And Status Conventions
Most JSON resources return status: "success" or status: "error", but broker payloads are normalized only at the wrapper level and some resources intentionally return CSV, plain text, or an empty webhook acknowledgement. Treat each endpoint page as authoritative for its payload.
Common status codes are:
| Code | Meaning |
|---|---|
| 200 | Request handled successfully |
| 400 | Invalid JSON, schema validation failure, unsupported mode, or invalid request state |
| 401 | Missing or invalid authentication on endpoints that use 401 |
| 403 | Invalid API key or operation blocked by mode/policy |
| 404 | Broker module, symbol, order, or linked messaging user not found |
| 429 | Flask-Limiter rejected the request |
| 500 | Unhandled internal or broker error |
Rate Limits
Defaults from .sample.env are API_RATE_LIMIT="50 per second", ORDER_RATE_LIMIT="10 per second", and SMART_ORDER_RATE_LIMIT="10 per second". Option Greeks, portfolio, SIP, Telegram, and WhatsApp resources each read their own variable, none of which appears in .sample.env, so their in-code fallbacks apply on a stock install. All values are deployment configuration and may contain compound semicolon-separated limits. See rate limiting.
Client Libraries
The Python client is available as tradeboard and is pinned by this application at 2.0.3. Go and Node.js examples in examples/ demonstrate direct REST integration; they are not declared here as separately versioned official SDK releases.