V1

This directory documents the registered OpenAlgo 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:8765

Replace the local host with the configured HTTPS/WSS domain in a remote deployment.

Authentication

Most POST endpoints accept the OpenAlgo 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 OpenAlgo key.

{
  "apikey": "<your_app_apikey>"
}

Never put broker credentials or broker access tokens in these requests. The OpenAlgo 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 openalgo 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.