Broker Integration

Integrating a broker into OpenAlgo

Golden rule: OpenAlgo has a common symbol format, common API, and common WebSocket format. Your only job per file is to translate the broker's specific shapes into those common contracts (and back). Copy the closest reference broker, then adapt the broker-specific bits.

36 broker plugins already exist. Almost every problem you will hit has been solved in one of them — the skill is knowing which one to copy, and which details are genuinely broker-specific.

Where broker code sits in the stack

restx_api/<endpoint>.py     Marshmallow schema validation + per-IP rate limit. Thin.
  services/<x>_service.py   Auth resolution, analyze-mode branch, event emission.
                            Returns (success: bool, response_data: dict, status_code: int)
    broker/<name>/api/*     <- YOU ARE HERE. The only place broker specifics live.

Two consequences worth internalizing:

• You never emit events. events/ and utils/event_bus.py are a services-layer concern (order placed, cancelled, GTT triggered). Broker modules do not import them. The one exception in the tree (broker/iiflcapital/streaming/iiflcapital_order_adapter.py) is an order-update stream, not the REST path — do not copy that pattern by default.
• Analyze mode never reaches you. get_analyze_mode() in the service short-circuits to sandbox_service before any broker call. So "it works in analyzer" proves nothing about your integration.

Step 1 — identify the broker's family, then copy that broker

This is the highest-leverage decision. Indian brokers cluster into four auth families, and picking the right template saves days:

Special cases: broker/fyers/ if the broker offers depth beyond 5 levels (dual WebSocket, 50-level TBT socket). broker/deltaexchange/ is the only broker_type: "crypto" plugin and the only one with leverage_config: true — ignore it for Indian equity brokers.

If the broker is a white-label of one of the above (very common — many Indian brokers resell Noren or XTS), the family template is often 90% correct as-is. Check the API docs for tell-tale endpoint paths (/NorenWClientTP/, /interactive/user/session) before assuming it is bespoke.

Step 2 — read the common contracts before writing anything

These define the format you must conform to. Do not infer them from a reference broker's code — read the specs:

Inspect the LIVE db/openalgo.db symtoken table of a working broker (e.g. connect zerodha once). This is the single most useful reference — it shows the exact column values your master contract must reproduce. Do this BEFORE wiping symtoken with your new broker's data — the old broker's rows are your ground truth for NCO symbol format, MCX_INDEX names, expiry formatting and the index symbol set. Once you overwrite the table, that reference is gone.

Calibrate against the plugins that already exist

Before deciding what is normal for a broker — batch caps, rate limits, depth levels, which capabilities OpenAlgo even has a contract for — read references/cross-broker-reference.md. It records how all 35 existing plugins actually behave, measured from the tree, so you are not guessing at defaults or reinventing a decision someone already made.

If you have no reachable documentation for your broker, read its family sibling in the tree — a Noren white-label behaves essentially like broker/flattrade/, an XTS white-label like broker/fivepaisaxts/.

The broker's official SDK is your second source of truth

When the broker's docs omit literal details (JSON field names, binary byte offsets, enum codes, endpoint routes), download their official Python SDK from PyPI and read its source — it encodes what the server actually accepts:

pip download <broker-sdk-package> --no-deps -d /tmp/sdk && cd /tmp/sdk && unzip -o *.whl
# then read: routes/constants (endpoint paths, enum codes), the request
# plumbing (json vs form body), and any _parse_*_packet binary parsers

For Arrow this single trick resolved: the websocket binary offsets (docs don't publish them), the margin request field names + product enum (C/I/M), the basket-margin endpoint shape, and the quote modes/exchange enum. Reading the SDK is minutes; guessing wrong costs hours of cryptic 400s.

Step 3 — the module contract

Services do importlib.import_module(f"broker.{broker}.api.<module>") and call fixed names — these ARE the contract. Verified against services/*.py:

auth is always the decrypted broker token string (last positional arg).

There is one more optional surface: an order-update stream (real-time fills, rejections, cancellations pushed to the client). 17 of 36 brokers implement it. It is registered separately in services/order_update_service.py, not in the table above — see references/order-updates.md.

NUANCE — BrokerData.__init__ arity is introspected, not fixed

services/quotes_service.py inspects BrokerData.__init__.__code__.co_argcount and passes (auth_token, feed_token) when the constructor takes two args, otherwise (auth_token). So a broker whose market-data API needs a separate feed token simply declares def __init__(self, auth_token, feed_token) and the service adapts. All the common templates (zerodha/dhan/fyers/flattrade/ angel/arrow) are single-arg — only add the second parameter if the broker truly has a distinct feed credential.

NUANCE — get_multiquotes is optional and silently degrades

The service does hasattr(data_handler, "get_multiquotes") and falls back to looping get_quotes per symbol if absent. That fallback works but is brutally slow for the options tools, which request 180+ symbols at once. Implement get_multiquotes for any broker with a batch quote endpoint.

NUANCE — margin: never sum legs when a basket endpoint exists

Copy broker/dhan/api/margin_api.py — it is the reference pattern: route ONE position to the broker's single-order calculator (detailed charge breakdown) and 2+ positions to the basket/multi calculator so the broker nets spread/hedge benefits (an Arrow NIFTY short straddle priced at ~207k via basket vs ~337k as a naive per-leg sum). Include Dhan's two guards: a JSON-decode guard (non-JSON broker reply -> 502) and _normalise_success_response (broker sends an error payload with HTTP 200 -> convert to a 400 response object, because margin_service trusts HTTP 200).