Get Started — Overview

The Bridge Connector is a lightweight C-based communication layer that exposes two dedicated TCP sockets for client applications. One socket accepts inbound request strings (orders or commands) from clients; the other socket sends outbound responses (acknowledgements, execution reports, errors) back to the client. This interface is designed to be:

• Simple (plain string messages)
• Low-latency (suitable for trading/order flows)
• Language-agnostic (clients can be written in C, C++, Python, Java, Perl, etc.)
• Secure when used with the authentication options described below

High-level Architecture

Key points

• Request Socket: Client -> Bridge (orders/commands)
• Response Socket: Bridge -> Client (ack/status/error)
• Two independent TCP connections avoid head-of-line blocking and make it easier for client code to separate write/read logic.
• Messages are plain text (UTF-8 recommended) and terminated by a newline (\n) or null (\0) depending on your preference.

Features

• Low latency socket communication
• Request/response based order handling
• Market data broadcast
• RMS and margin validation

Connection Details

Protocol: TCP
Default ports (example):

• Request socket (client -> bridge): 9090
• Response socket (bridge -> client): 9091

Address: Bind to 0.0.0.0 on the server for production, or 127.0.0.1 for local testing.
Message encoding: UTF-8 (recommended)
Message termination: \n (newline). All messages MUST be terminated by newline to allow proper framing.
Max message length: 4096 bytes (configurable)

• Request code
2000 : New Order Request
2040 : Order Modify Request
2070 : Order Cancel Request

• Response code
2222 : Order Trade Confirmation
2073 : New Order Confirmation
2074 : Oder Modification Confirmation
2075 : Order Cancel Confirmation

• Exchange Numbers
NSE Stocks & Index Future(NFO) : 2
NSE Stocks & Index Option(NOP) : 5

• Token No
Token no which we get from contract master

• Echoback
This field is used for identifying response for corresponding request which is given by user, in response we will send same value of echoback which will be received in request

REQUEST New Order

REQUEST Modify Order

REQUEST Cancel Order

RESPONSE Order Confirmation

RESPONSE Modify Confirmation

RESPONSE Cancel Confirmation

TRADE Trade Confirmation

REJECT Rejection

Broadcast Format

Socket Authentication

You MUST protect production sockets. Below are recommended options from simple to most secure.

Shared Secret (Simple)

• Client sends a secret key as the first message after connecting.
• Server validates the secret; if invalid, server closes the connection.

Pros: Easy to implement.
Cons: Secret can be intercepted unless used with TLS.

Handshake example:
1. Server sends AUTH_REQUIRED\n
2. Client sends AUTH|<secret-key>\n
3. Server replies AUTH_OK\n or AUTH_FAIL\n

Heartbeat / Keepalive

• Implement periodic heartbeat messages such as PING\n / PONG\n to detect dead sockets and network issues.
• OS-level TCP keepalive should also be enabled.

Order Request/Response Client Example (Authenticated)

A complete, runnable client that builds an order request string, sends it on the request socket, and reads and validates the response on the response socket. It uses the same shared-secret handshake described in Socket Authentication on both sockets, and the same request/response field layouts documented in New Order and Order Confirmation. If your client runs on the same trusted machine/network as the Bridge and you don't need this handshake, see Order Request/Response Client Example (Trusted, No Auth) below instead.

Scenarios covered

• Local request validation - the request code is checked against the known codes before anything is sent, so a typo doesn't reach the server as a malformed message.
• Authentication on both sockets - request and response sockets are authenticated independently using the shared-secret handshake.
• Connection failures - server unreachable, connection refused, or timed out while connecting.
• Authentication failures - wrong secret, connection dropped mid-handshake, or an unexpected reply that doesn't match the documented protocol.
• Empty/closed response - the server closes the connection before sending a response.
• Unrecognized response code - a response code outside the documented set.
• Field display - every response field is printed using its documented name (see Order Confirmation), not just its raw position.

Configuration

request_client_auth.py

Run

Request/response flow

Expected output

Error-handling cases

Order Request/Response Client Example (Trusted, No Auth)

Same request/response flow as the authenticated example above, but with the Socket Authentication handshake removed entirely. Use this only when the client is running on a trusted machine or network - for example, on the same host as the Bridge, or inside a private network the Bridge is not exposed beyond.

Configuration

request_client_no_auth.py

Run

Request/response flow

Expected output

Error-handling cases

Subscription (CSV) Format

The broadcast component does not send all instruments by default - it only sends data for the instruments listed in a subscription list, provided as a pipe-delimited (|) file with a .csv extension. There is no way to subscribe/unsubscribe by sending a request over the socket at runtime.

Format

One instrument per line, five pipe-delimited fields, no header row required:

subscriptions.csv

Once the subscription file is in place and the broadcast component has been (re)started, connect to the broadcast socket as usual (see the examples below) - you'll only receive broadcasts for the instruments listed in the file. Unlisted instruments are never sent, so there's no need to filter them out on the client side. To add or change instruments later, edit the CSV and restart the broadcast component again.

Broadcast Reader - TCP (Primary Example)

This is the reference example for reading market data broadcasts: a single TCP connection to the broadcast socket, using plain Python with no external dependencies. It's intentionally the simplest thing that handles broadcast data correctly, including the error handling every production reader needs:

• Partial / split messages - a single recv() can return less than one full line, more than one line, or a line split across two calls. The reader buffers bytes and only processes complete, newline-terminated lines.
• Malformed messages - every line is checked against the expected 19-field format (see Broadcast Format). Bad lines are logged and skipped instead of crashing the reader.
• Falling behind ("can't keep up") - if the unprocessed buffer keeps growing, that means data is arriving faster than it's being read/processed. A warning is logged so you know to speed up processing or reduce your subscription list.
• Clear, timestamped error reporting for connect/read failures, with automatic reconnect.

Configuration

read_broadcast_tcp.py

Run

Expected output

Broadcast Reader - Multicast (UDP)

Use this instead of the TCP example when your deployment delivers market data over multicast rather than a TCP broadcast socket. Both mechanisms carry the same pipe-delimited message format described in Broadcast Format - only the transport differs.

Configuration

read_broadcast_multicast.py

Run

Expected output

Broadcast Reader - Multiple Connections (Advanced)

Once you're comfortable with the primary TCP example, this variant shows how to read from several TCP connections to the same broadcast instance at the same time - for example, multiple readers/strategies consuming the same feed, or redundant connections for resiliency. It's the same buffering, partial-message, and malformed-message handling as the primary example, just applied to each connection in turn, using plain sequential Python (no external libraries).

Each socket gets a short read timeout. The main loop checks connection 1, then 2, then 3, and so on, repeatedly; the timeout lets the loop move on instead of blocking on a connection with no data. If one connection drops, only that one reconnects - the others keep running untouched.

Configuration

read_broadcast_multi.py

Run

Expected output

Server-side (Bridge) Behavior

• Accept connections on both ports.
• Authenticate incoming request connections before reading order messages.
• Push responses / events on response socket (client should be listening).
• Handle partial reads/writes and message framing robustly.
• Implement logging for audit (timestamps, clientid, raw messages).
• Implement rate limiting and input validation to protect the backend.

Error Handling & Response Codes

Use consistent error responses. Example values:

• REJECTED: Order rejected due to validation
• ERROR: Internal processing error
• TIMEOUT: Processing timed out
• AUTH_FAIL: Authentication failed
• INVALID: Invalid message format

Example error reply:
1004|REJECTED|Requested order string is not as per requirement.\n

Performance & Best Practices

• Keep sockets long-lived avoid connect/disconnect per-order.
• Use non-blocking IO or separate threads for read/write to prevent head-of-line blocking.
• Implement buffering and incremental parsing for large messages.
• Avoid heavy logging on hot paths; use sampling or async logging.
• Measure latency (end-to-end) and set SLAs(Service Level Agreements)

For example:

• 99% of orders will be responded within 50 ms
• Maximum allowed latency: 100 ms
• System uptime: 99.9%

These give customers confidence that your system is reliable

RMS

Risk Management System is a control layer that ensures all trades follow predefined risk limits and regulatory rules before orders are sent to the exchange.

RMS ensures that only valid and permitted orders are placed in the market. It protects traders, brokers, and exchanges from financial, operational, and compliance risks.

Orders are validated against predefined RMS rules.

• Index band check
• Market Price Protection (Yesterday Close check)
• Exposure limit checks (Bot Limit)
• Security Filter & No of instance limit
• Blacklisting (BAN/FII/MWPL) of scrip
• Single Order Value and Quantity checks
• Total Order value and Quantity checks
• Total Turnover checks
• Cash In Hand check
• Cumulative Open Order Value (COOV) check
• Security wise quantity checks
• Net Quantity check
• DPR Check
• LTP Check

Margin

Margin checks are applied post order acceptance.

• SPAN Margin (Initial Margin)
• Exposure Margin

We show Total Margin.
API has facility to restrict order on margin breach.

Real-Time Trade Monitor

The Bridge API provides comprehensive real-time monitoring capabilities to track all your trading activities. Our monitoring interface gives you complete visibility into your trades, positions, and order execution status.

Live Trade View

Monitor all executed trades in real-time with detailed information including instance number, execution time, symbol, quantity, and price. The live trade view helps you track your trading activity as it happens, providing instant feedback on order executions.

Live Trade Monitor - Real-time view of all executed trades

Detailed Net Position View

Get comprehensive position tracking with our detailed net position monitor. This view provides in-depth analysis including quantity exposure, rupee exposure, threshold quantities, buy/sell values, profit/loss calculations, and real-time margin requirements. The square-off thresholds help you manage risk effectively.

Detailed Net Position Monitor - Comprehensive position tracking with P&L analysis

Key Features

• Real-Time Updates: All trade data and positions are updated in real-time as orders are executed
• Comprehensive Metrics: Track quantity, price, exposure, margins, and profit/loss for all positions
• Risk Management: Built-in square-off thresholds
• Export Capabilities: Generate CSV reports for detailed analysis and record-keeping

Troubleshooting & FAQ