Broker integration specification

1. Purpose and scope

This specification lets a broker ("the Broker") deploy Lantern as its own algo strategy marketplace and connect it to its order management system (OMS) so that Lantern can act on behalf of the Broker's customers. It is written for three readers: the Broker's technology team or OMS vendor (what to expose and how), its operations team (what happens every day) and its compliance team (how the arrangement meets the SEBI framework for algorithmic trading by retail investors).

Chosen product scope. Treat the sections below as a menu. A broker picks the product scope at onboarding, and that choice decides which features, flows and adapter endpoints are implemented. Typical scopes and what they need:

Integration models

1. Native adapter. The Broker or its OMS vendor exposes the endpoints in section 8 and Lantern calls them directly. This is the preferred model and the one this document assumes.
2. Vendor adapter. The Broker already runs a vendor API (for example Symphony XTS, Omnesys NEST, Greeksoft) and Lantern uses its adapter for that vendor, mapped onto the same contract. Only field mappings differ; flows, limits and compliance are the same.

2. Roles and responsibilities

Data ownership. Customer identity, KYC and account data belong to the Broker and stay in its systems; Lantern stores the minimum it needs (section 5). Strategy logic belongs to the provider and never leaves the provider's systems; Lantern receives signals only. Subscription, order and performance records are shared for reconciliation and audit.

Contact points. Each party names a technical owner, an operations owner and a compliance owner in the onboarding sheet. Market-hours incidents go to both technical owners at once.

3. Architecture

Lantern sits between strategy providers and the Broker's OMS. Providers send signals to Lantern; Lantern sizes and places orders for each subscriber through the broker adapter; the Broker's OMS applies its risk checks and routes to the exchange; order updates flow back to Lantern, which reconciles and reports. Customers use the white-labelled web app on the Broker's domain and log in through the Broker's own authentication.

Sequence of a subscribed signal

1. 1Provider→LanternPOST /v1/signals with legs, risk limits and valid_till
2. 2Lantern↻Validate the signal, load live subscribers, size each by multiplier and lot size
3. 3Lantern→Broker OMSPOST /margin/check for the subscriber
4. 4Broker OMS→LanternAvailable margin and any shortfall
5. 5Lantern→Broker OMSPOST /orders/basket with correlation_id, algo_id and LIMIT prices
6. 6Broker OMS→ExchangeRMS checks, then route the orders
7. 7Exchange→Broker OMSFills and rejections
8. 8Broker OMS→Lanternorders.updated events; Lantern reconciles fills per subscriber
9. 9Lantern→ProviderAggregate fill status only: count, average price, slippage
10. 10Lantern→Broker OMSOn subscribe or cancel: POST or DELETE /subscriptions with charges, start and end time
11. 11Lantern→Broker OMSEnd of day: order log; GET /subscriptions to confirm the register
12. 12Broker OMS→LanternEnd of day: trade and charges file for net profit and billing

Steps 3 to 8 repeat for every live subscriber of the strategy, paced to the Broker's order-rate limit.

Deployment view. The static web app is served from the Broker's domain (Broker-hosted nginx or Lantern hosting). Lantern's platform services (signal intake, fan-out, reconciliation, billing) run in Fintrens's cloud in India from fixed outbound addresses. The broker adapter is the only path between the two systems, over TLS with partner credentials and per-customer tokens.

4. Step 1: Customer login and consent

Customers never type their Broker password into Lantern. Lantern uses a partner-consent flow in which the Broker's own login page authenticates the customer and returns a token scoped to Lantern. The shape follows what Indian brokers already expose to third-party platforms, so OMS vendors can map it directly.

Entry points

• Direct landing. A customer arrives at the Lantern marketplace (search, a shared strategy link, the Broker's website) without being logged in. Every public page is readable; when they click Log in, or Subscribe, Lantern sends them to the Broker's login page, the Broker authenticates them, and they land back on the Lantern page they started from with the session established. No separate Lantern registration or password exists.
• From the Broker's app. The Broker's web or mobile app links to Lantern with a one-time token_id for the already-authenticated customer, so Lantern opens signed in without showing a login page.

Credentials issued to Lantern (once per broker)

• partner_id and partner_secret, used server to server only
• A registered redirect URL on the deployment's domain, for example https://algos.broker.example/auth/callback

Flow (direct landing)

1. The customer clicks Log in on any Lantern page. Lantern remembers that page as the return destination and calls POST /partner/consent with its partner credentials and receives a consent_id valid for a few minutes.
2. Lantern redirects the browser to the Broker's hosted login page with that consent_id. The customer enters their Broker client ID and password and completes the Broker's second factor (TOTP, OTP or app approval).
3. The Broker redirects back to Lantern's callback with a one-time token_id.
4. Lantern's server calls GET /partner/token?token_id=… and receives an access_token, its expires_at, the Broker client_id and a refresh_token where supported.
5. Lantern creates or links the account to that client_id, stores the token encrypted and returns the customer to the page they started from, now signed in. The browser session is Lantern's own; the Broker token never reaches the browser.

The whole round trip is three redirects and takes a few seconds; the customer sees only the Broker's familiar login screen in between.

Token rules

• Access tokens are per customer, scoped to Lantern, and expire at the end of the trading day unless the Broker supports longer validity or refresh. Lantern refreshes before market open; without refresh the customer is asked to log in again and no orders are placed until they do.
• A customer can revoke Lantern's access from the Broker's app at any time. The Broker calls POST /broker/revocation so Lantern pauses the customer's strategies immediately.
• One active token per customer per platform; a new login invalidates the old one.
• TLS 1.2 or later everywhere; partner credentials rotated at least yearly and on request.

Errors. Login failures, cancelled consent and expired tokens return the Broker's error code and message, shown verbatim to the customer with a retry. Lantern logs the error class, never the credentials.

5. Step 2: Customer details

After login Lantern reads what it needs to decide what the customer may subscribe to and how much. Everything is read through the adapter with the customer's token.

What Lantern stores. The client_id, name, email and mobile, the segment and algo-enablement flags, and the encrypted token. Funds, positions and holdings are read on demand and cached for at most a few minutes during market hours. PAN, bank details and KYC documents are never requested.

What the customer sees. The same facts in plain language in their account: which segments are enabled, whether algo trading is enabled, and available margin against each subscription. If algo trading is not enabled, the account shows the Broker's steps to enable it instead of a subscribe button.

6. Step 3: Subscribing to a strategy

A subscription is the customer's standing instruction to run one strategy in their account at a chosen size. It is created in Lantern, confirmed by the customer and recorded with the Broker.

Multiplier and allocation. Every strategy publishes a minimum allocation and the order quantities for that minimum (1x). The customer picks a multiplier N; orders and capital scale by N up to floor(maxAllocation / minAllocation). The subscription fee is flat; profit share scales with profit.

Checks before activation

1. Account active, the strategy's segment enabled, algo trading enabled for the customer.
2. Available margin covers the allocation at the chosen multiplier, using POST /margin/check on the strategy's representative basket.
3. Capital across all active subscriptions stays within the customer's own capital cap.
4. The strategy has open slots.

Consent to automated execution. Before the first live subscription the customer accepts, inside Lantern, a consent text supplied by the Broker's compliance team: orders will be placed automatically on the strategy's signals, they can pause or stop at any time, the fee and profit-share terms, and the risk disclosure. Lantern records the consent version, timestamp and IP.

The Broker is the system of record for subscriptions

Every subscription lives in the Broker's systems, so the Broker can bill it, show it in its own app and answer for it to the exchange. Lantern intimates the Broker at each step and reads back what the Broker holds:

1. Subscribe. When the customer confirms, Lantern calls POST /subscriptions with the strategy, its exchange algo ID, the provider, the multiplier and allocation, the charges (subscription fee, billing cycle, profit-share percentage, taxes), the start time, the end time or renewal rule, the state and the consent record. The Broker returns its subscription_id, which Lantern uses from then on.
2. Read. At every login, and before placing orders, Lantern calls GET /subscriptions?client_id=… and treats the Broker's list as the truth: the customer's account in Lantern shows exactly what the Broker holds, including subscriptions the Broker created or ended elsewhere.
3. Change. Pause, resume and multiplier changes are sent with PUT /subscriptions/{id} where the Broker supports it.
4. Cancel. When the customer stops a strategy, Lantern calls DELETE /subscriptions/{id} with the reason and the effective time; open positions are squared off at the next session and no further orders are placed for that subscription. The Broker may also cancel from its side, which Lantern picks up on the next read or through the revocation webhook.

States. paper (signals simulated), live, paused (no new entries; open positions managed to exit), stopped (square-off at the next session). Transitions come from the customer, the provider, Lantern's risk rules (portfolio stop-loss, divergence alerts, missed heartbeats) or the Broker (RMS block, revocation, kill switch), and every transition is intimated to the Broker as above.

Conflicts. Lantern warns at subscription time when an active subscription already trades the same underlying, and never nets across strategies.

7. Step 4: Signal intake and fan-out

A provider sends one signal; Lantern turns it into one order set per subscriber and places them through the Broker. The provider never sees subscriber identities, and the Broker never needs the provider's logic.

Signal intake. Providers push signals to the Provider API: an action (ENTRY, EXIT, MODIFY), legs with side, instrument, order type, limit price, quantity per lot and lots per lakh, a valid_till, and risk fields. Signals are signed, idempotent on client_ref, validated against the strategy's registered instruments and risk limits, and rejected if they exceed the listed stop-loss.

Fan-out

1. Load the active live subscriptions; for each, compute quantities from lots per lakh × allocation, rounded down to lot size and split at the exchange freeze limit.
2. Pre-trade check per subscriber: token valid, segment enabled, margin via POST /margin/check, no RMS block, strategy not paused.
3. Place through POST /orders or POST /orders/basket with a correlation_id of the form L-<signal>-<subscriber>-<leg>, the Broker's exchange algo ID for the strategy, and LIMIT orders as exchange rules require. Multi-leg signals go as a basket where the OMS supports it; with the minimum API set they go leg by leg, hedge legs first, and a failed leg cancels or squares off that subscriber's other legs.
4. Placement is paced to the Broker's per-second limit, largest allocations first so fills are proportionate.
5. Order updates arrive on the order-update stream; Lantern reconciles fills, partial fills and rejections, retries rejected limit orders within valid_till at a refreshed price, and marks each subscriber's signal filled, partially filled or failed.
6. Subscribers are notified; providers receive aggregate fill status only (count, average price, slippage).

Exits and risk. Exit signals reference the entry via parent_signal_id and use the actual filled quantity per subscriber. Lantern's platform stop-loss monitors each position; on missed heartbeats or a paused strategy, Lantern exits open positions itself. The Broker's RMS remains the final check on every order.

Failure handling

8. Broker adapter contract

The table lists every capability Lantern can use. A deployment implements only those its chosen scope requires; Required below means required for a marketplace with live execution.

Minimum set for go-live

Lantern can run a live deployment with nine capabilities from the Broker. Everything else in the table is optional and improves resilience or automation but is not needed to launch.

1. Login and consent: create consent and exchange token (section 4)
2. Profile and balance: customer details, segments, algo enablement, and available funds or margin
3. Instrument list: the daily instrument master with lot size, tick size, freeze quantity and expiries
4. Order placement: LIMIT orders with a correlation id and the algo id
5. Order cancel
6. Order status: by order id, and the order book for the day
7. Positions
8. Holdings
9. Subscriptions: create with charges and start and end time, list the customer's subscriptions, cancel

With only these, Lantern places one order per leg, polls order status, and reads the trade details from the order book. Order modification, basket orders, margin pre-check, the order-update stream and the kill switch are added as the Broker's OMS supports them.

The capabilities in full. Names are Lantern's canonical contract; a native adapter exposes them as REST over HTTPS with JSON, a vendor adapter maps them onto the vendor's calls. Customer-scoped calls carry the customer's access_token; partner-scoped calls carry partner_id and partner_secret.

Conventions

• Idempotency: correlation_id is unique per order and repeated on retries; the OMS returns the existing order for a repeated id instead of placing a second one.
• Statuses: PENDING, OPEN, PART_FILLED, FILLED, CANCELLED, REJECTED, EXPIRED; rejections carry OMS and exchange reason codes.
• Rate limits are stated in the onboarding sheet; Lantern defaults to 10 orders per second and 200 per minute per partner and paces traffic accordingly.
• Formats: IST in ISO 8601 with offset; rupees with two decimals; quantities in units with lot size from the instrument master.
• Errors: { code, message, details }; 4xx not retried except 429; 5xx retried with backoff until valid_till.
• Without an order-update stream, Lantern polls order status every two seconds for open orders until filled, cancelled or expired, and reads fills from the order book; the stream is preferred once available.
• The machine-readable contract is published as an OpenAPI 3.1 document with this page; the conformance suite (section 11) exercises every row above in UAT.

9. Compliance: broker-enabled algo trading

Under the SEBI framework for algorithmic trading by retail investors (circular of February 2025 and the exchange implementation standards that followed), algo orders from retail customers flow through the broker, carry an exchange-registered algo identifier and are subject to the broker's controls. Lantern is deployed as the Broker's own algo platform, so the arrangement is the broker-enabled model, not the retail-API model.

• Algo registration. The Broker registers each strategy offered on its deployment with the exchange(s) and obtains an algo ID per strategy. Lantern keeps the mapping and sends the algo ID on every order. White-box strategies are registered with their logic disclosed; black-box strategies are registered through a SEBI-registered Research Analyst, which is why Lantern allows public black-box listings only from approved providers.
• No static IP for customers. Static-IP whitelisting applies to customers sending orders from their own systems through a retail API. Here orders originate from the Broker's enabled platform, so customers need no static IP. Lantern's order-placing servers run from fixed addresses registered with the Broker, and the Broker may restrict partner credentials to them.
• Order-rate thresholds. The per-second threshold that distinguishes algo from non-algo activity is immaterial because every order is already tagged as algo; Lantern still paces to the Broker's limits and keeps a per-customer rate log.
• Broker controls. The Broker's RMS validates every order, can block a customer or an algo ID, and has a kill switch that stops all Lantern order flow for a scope within seconds. Lantern honours it before any retry logic.
• Provider empanelment. Providers are onboarded with identity checks; public black-box publishers supply their SEBI RA registration and documents. The Broker receives the provider register and may veto a provider or strategy for its deployment.
• Consent and disclosure. Consent to automated execution, the risk disclosure and fee terms are presented in the Broker's approved wording and recorded. Performance figures carry the backtest or live label, the verification date and the standard disclaimer.
• Audit trail. Every signal, every order per subscriber with its correlation and algo IDs, every state change and every consent is logged with timestamps, retained for the Broker's required period (default eight years) and exported daily. Exchange or SEBI queries are answered from this trail jointly.
• Claims. Neither party publishes return claims outside the verified figures shown on the platform.

The Broker's compliance team confirms the registration route and the approved consent and disclaimer text in the onboarding sheet; this specification does not replace the Broker's own legal review.

10. Reporting, reconciliation and billing

Daily reconciliation. After market close Lantern pulls each subscriber's trade book and matches every trade to a Lantern order by correlation_id. Breaks are listed in a reconciliation report sent to the Broker's operations owner by 19:00 IST and cleared before the next session. Positions are compared the same way.

Statements. Each subscriber sees per-strategy realised and unrealised P&L, fees and the combined portfolio in their account; a monthly statement is emailed and available to the Broker.

Billing and profit share. On the first business day of each month Lantern computes, per subscriber and strategy, the flat subscription fee and the profit share on net realised profit above that subscription's high-water mark, net of the Broker's charges from the trade file. Collection is by the Broker from the customer's ledger (preferred; the Broker remits to Fintrens) or by Lantern through its payment processor, as chosen at onboarding. Providers receive their share monthly with a statement; any Broker revenue share on platform fees settles in the same cycle. Amounts are in rupees; GST is applied as invoiced by the collecting party.

11. Minimum system requirements

Lantern's platform services run in Fintrens's cloud for a hosted deployment. A broker that prefers to host the platform inside its own environment needs the following; the static web application has no server requirement beyond a web server such as nginx.

Platform stack

Sizing for a single broker deployment

Network and environment

• Outbound HTTPS (TLS 1.2+) from the services to the Broker's OMS endpoints from fixed egress IP addresses; inbound HTTPS for the web application, the Provider API and the Broker's webhooks.
• Clock synchronised by NTP; timestamps stored in UTC and shown in IST.
• Container runtime (Docker 24+ or Kubernetes 1.28+) or a Linux host (Ubuntu 22.04 LTS or RHEL 9) for JAR deployment.
• Browser support for customers: current Chrome, Edge, Safari and Firefox, and Android and iOS browsers from the last two major versions; no plug-ins.
• Broker side: the adapter endpoints in section 8, a UAT environment, and allow-listing of Lantern's egress addresses if the Broker restricts partner credentials by IP.

12. Service levels, environments and onboarding

Environments. The Broker provides a UAT environment with test client accounts, simulated or delayed market data and the same API surface as production, available during market hours. Lantern runs a matching staging deployment. Production credentials follow a passing conformance run in UAT.

Security. TLS 1.2 or later; partner credentials in a secrets store, rotated yearly or on request; customer tokens encrypted at rest with per-tenant keys; fixed outbound addresses the Broker may allow-list; signed webhooks (HMAC-SHA256 over timestamp and body, rejected after five minutes); role-based access with logs; a penetration test before go-live and annually. No customer credentials are ever stored by Lantern.

Monitoring. Both parties receive alerts for adapter errors above threshold, order latency, missed heartbeats, reconciliation breaks and kill-switch activation, on a shared market-hours channel.

Conformance suite. An automated suite exercises every adapter capability in UAT: consent, refresh and revocation, profile and funds, margin check, single and basket orders, modify and cancel, order-update delivery, trade book, subscription record, revocation and kill-switch webhooks, rate-limit behaviour. Passing it is the entry condition for production.

Onboarding plan

13. White-label deployment

Lantern is a static web application plus the platform services behind it. A broker deployment changes only configuration.

14. Onboarding questions for the Broker

Answered before integration starts and recorded in the per-broker onboarding sheet, the only broker-specific document.

15. Appendix: sample payloads and glossary

Each sample shows the request body, a ready-to-run curl command and the response. Hostnames are placeholders: api.broker.example is the Broker's adapter, fintrens.com/lantern is Lantern. Use the Copy button on any pane.

{
  "redirect_url": "https://algos.broker.example/auth/callback"
}

curl -X POST "https://api.broker.example/partner/consent" \
  -H "Content-Type: application/json" \
  -H "partner_id: ptn_lantern" \
  -H "partner_secret: <secret>" \
  -d '{"redirect_url":"https://algos.broker.example/auth/callback"}'

{
  "consent_id": "c_8f31",
  "login_url": "https://login.broker.example/consent?c=c_8f31",
  "expires_in": 300
}

(no body)

curl -X GET "https://api.broker.example/partner/token?token_id=t_41ac" \
  -H "Content-Type: application/json" \
  -H "partner_id: ptn_lantern" \
  -H "partner_secret: <secret>"

{
  "access_token": "eyJhbGciOi…",
  "refresh_token": "r_9d2c…",
  "expires_at": "2026-11-10T15:45:00+05:30",
  "client_id": "AB1234"
}

(no body)

curl -X GET "https://api.broker.example/profile" \
  -H "Content-Type: application/json" \
  -H "access_token: <customer token>"

{
  "client_id": "AB1234",
  "name": "A. Customer",
  "email": "a@example.com",
  "mobile": "9xxxxxxxxx",
  "kyc_status": "verified",
  "account_status": "active",
  "segments": [
    "NSE_EQ",
    "NSE_FO",
    "MCX_FO"
  ],
  "algo_enabled": true,
  "risk_category": "B",
  "ddpi": true
}

(no body)

curl -X GET "https://api.broker.example/funds" \
  -H "Content-Type: application/json" \
  -H "access_token: <customer token>"

{
  "segments": {
    "NSE_FO": {
      "available_margin": 412500,
      "used_margin": 87500,
      "cash": 300000,
      "collateral": 200000
    },
    "NSE_EQ": {
      "available_margin": 150000,
      "used_margin": 0,
      "cash": 150000,
      "collateral": 0
    }
  },
  "as_of": "2026-11-10T09:14:58+05:30"
}

(no body)

curl -X GET "https://api.broker.example/instruments?exchange=NSE&segment=FO&date=2026-11-10" \
  -H "Content-Type: application/json" \
  -H "partner_id: ptn_lantern" \
  -H "partner_secret: <secret>"

{
  "instruments": [
    {
      "instrument_id": "58921",
      "symbol": "NIFTY26N1324600PE",
      "exchange": "NSE",
      "segment": "FO",
      "lot_size": 25,
      "tick_size": 0.05,
      "freeze_qty": 1800,
      "expiry": "2026-11-13",
      "strike": 24600,
      "option_type": "PE"
    }
  ],
  "count": 1,
  "as_of": "2026-11-10"
}

{
  "algo_id": "alg_7Qp2",
  "client_ref": "sig-2026-11-10-01",
  "action": "ENTRY",
  "ts": "2026-11-10T13:13:00+05:30",
  "valid_till": "2026-11-10T13:20:00+05:30",
  "legs": [
    {
      "side": "SELL",
      "symbol": "NIFTY26N1324600PE",
      "exchange": "NFO",
      "qty_per_lot": 25,
      "lots_per_lakh": 0.4,
      "order_type": "LIMIT",
      "price": 176.9
    },
    {
      "side": "BUY",
      "symbol": "NIFTY26N1324200PE",
      "exchange": "NFO",
      "qty_per_lot": 25,
      "lots_per_lakh": 0.4,
      "order_type": "LIMIT",
      "price": 45.5
    }
  ],
  "risk": {
    "stop_loss_pct": 8,
    "target_pct": 65,
    "max_slippage_bps": 25
  }
}

curl -X POST "https://fintrens.com/lantern/api/v1/signals" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer lk_live_<key>" \
  -H "X-Lantern-Signature: sha256=<hmac>" \
  -d '{"algo_id":"alg_7Qp2","client_ref":"sig-2026-11-10-01","action":"ENTRY","ts":"2026-11-10T13:13:00+05:30","valid_till":"2026-11-10T13:20:00+05:30","legs":[{"side":"SELL","symbol":"NIFTY26N1324600PE","exchange":"NFO","qty_per_lot":25,"lots_per_lakh":0.4,"order_type":"LIMIT","price":176.9},{"side":"BUY","symbol":"NIFTY26N1324200PE","exchange":"NFO","qty_per_lot":25,"lots_per_lakh":0.4,"order_type":"LIMIT","price":45.5}],"risk":{"stop_loss_pct":8,"target_pct":65,"max_slippage_bps":25}}'

{
  "signal_id": "sig_K1m9",
  "status": "queued",
  "subscribers": 158
}

{
  "correlation_id": "L-sigK1m9-AB1234-1",
  "algo_id": "NSE-ALGO-00123",
  "instrument_id": "58921",
  "side": "SELL",
  "quantity": 50,
  "order_type": "LIMIT",
  "price": 176.9,
  "product": "MARGIN",
  "validity": "DAY"
}

curl -X POST "https://api.broker.example/orders" \
  -H "Content-Type: application/json" \
  -H "access_token: <customer token>" \
  -d '{"correlation_id":"L-sigK1m9-AB1234-1","algo_id":"NSE-ALGO-00123","instrument_id":"58921","side":"SELL","quantity":50,"order_type":"LIMIT","price":176.9,"product":"MARGIN","validity":"DAY"}'

{
  "order_id": "1126001",
  "status": "OPEN"
}

(no body)

curl -X GET "https://api.broker.example/orders/1126001" \
  -H "Content-Type: application/json" \
  -H "access_token: <customer token>"

{
  "order_id": "1126001",
  "correlation_id": "L-sigK1m9-AB1234-1",
  "algo_id": "NSE-ALGO-00123",
  "status": "FILLED",
  "quantity": 50,
  "filled_qty": 50,
  "average_price": 176.55,
  "exchange_order_id": "1100000012345678",
  "reject_reason": null,
  "updated_at": "2026-11-10T13:13:02+05:30"
}

(no body)

curl -X DELETE "https://api.broker.example/orders/1126002" \
  -H "Content-Type: application/json" \
  -H "access_token: <customer token>"

{
  "order_id": "1126002",
  "status": "CANCELLED"
}

(no body)

curl -X GET "https://api.broker.example/positions" \
  -H "Content-Type: application/json" \
  -H "access_token: <customer token>"

{
  "positions": [
    {
      "instrument_id": "58921",
      "symbol": "NIFTY26N1324600PE",
      "product": "MARGIN",
      "quantity": -50,
      "average_price": 176.55,
      "ltp": 171.2,
      "pnl": 267.5
    }
  ]
}

(no body)

curl -X GET "https://api.broker.example/holdings" \
  -H "Content-Type: application/json" \
  -H "access_token: <customer token>"

{
  "holdings": [
    {
      "instrument_id": "1333",
      "symbol": "HDFCBANK",
      "quantity": 60,
      "average_price": 1650,
      "ltp": 1712.4,
      "value": 102744
    }
  ]
}

{
  "event": "orders.updated",
  "order_id": "1126001",
  "correlation_id": "L-sigK1m9-AB1234-1",
  "client_id": "AB1234",
  "status": "FILLED",
  "filled_qty": 50,
  "average_price": 176.55,
  "exchange_order_id": "1100000012345678",
  "timestamp": "2026-11-10T13:13:02+05:30"
}

curl -X POST "https://fintrens.com/lantern/api/v1/broker/orders" \
  -H "Content-Type: application/json" \
  -H "X-Broker-Signature: sha256=<hmac>" \
  -d '{"event":"orders.updated","order_id":"1126001","correlation_id":"L-sigK1m9-AB1234-1","client_id":"AB1234","status":"FILLED","filled_qty":50,"average_price":176.55,"exchange_order_id":"1100000012345678","timestamp":"2026-11-10T13:13:02+05:30"}'

{
  "ok": true
}

{
  "client_id": "AB1234",
  "strategy": {
    "slug": "convex-credit-spread-overnight",
    "name": "Convex Credit Spread Overnight",
    "provider": "Quantfold Labs"
  },
  "algo_id": "NSE-ALGO-00123",
  "multiplier": 2,
  "allocation": 200000,
  "charges": {
    "subscription_fee": 1499,
    "billing_cycle": "monthly",
    "profit_share_pct": 20,
    "tax": "GST 18% extra",
    "currency": "INR"
  },
  "start_at": "2026-11-11T09:15:00+05:30",
  "end_at": null,
  "renewal": "monthly_auto",
  "state": "live",
  "consent": {
    "version": "2026-10",
    "at": "2026-11-10T10:02:11+05:30",
    "ip": "203.0.113.7"
  }
}

curl -X POST "https://api.broker.example/subscriptions" \
  -H "Content-Type: application/json" \
  -H "partner_id: ptn_lantern" \
  -H "partner_secret: <secret>" \
  -d '{"client_id":"AB1234","strategy":{"slug":"convex-credit-spread-overnight","name":"Convex Credit Spread Overnight","provider":"Quantfold Labs"},"algo_id":"NSE-ALGO-00123","multiplier":2,"allocation":200000,"charges":{"subscription_fee":1499,"billing_cycle":"monthly","profit_share_pct":20,"tax":"GST 18% extra","currency":"INR"},"start_at":"2026-11-11T09:15:00+05:30","end_at":null,"renewal":"monthly_auto","state":"live","consent":{"version":"2026-10","at":"2026-11-10T10:02:11+05:30","ip":"203.0.113.7"}}'

{
  "subscription_id": "sub_5c0d",
  "status": "active"
}

(no body)

curl -X GET "https://api.broker.example/subscriptions?client_id=AB1234" \
  -H "Content-Type: application/json" \
  -H "partner_id: ptn_lantern" \
  -H "partner_secret: <secret>"

{
  "subscriptions": [
    {
      "subscription_id": "sub_5c0d",
      "strategy": {
        "slug": "convex-credit-spread-overnight"
      },
      "algo_id": "NSE-ALGO-00123",
      "multiplier": 2,
      "allocation": 200000,
      "charges": {
        "subscription_fee": 1499,
        "billing_cycle": "monthly",
        "profit_share_pct": 20
      },
      "start_at": "2026-11-11T09:15:00+05:30",
      "end_at": null,
      "state": "live",
      "updated_at": "2026-11-11T09:15:02+05:30"
    },
    {
      "subscription_id": "sub_2a19",
      "strategy": {
        "slug": "gold-carry-mcx"
      },
      "algo_id": "MCX-ALGO-00077",
      "multiplier": 1,
      "allocation": 100000,
      "charges": {
        "subscription_fee": 699,
        "billing_cycle": "monthly",
        "profit_share_pct": 15
      },
      "start_at": "2026-08-12T09:15:00+05:30",
      "end_at": "2026-12-31T15:30:00+05:30",
      "state": "paused",
      "updated_at": "2026-11-03T11:40:00+05:30"
    }
  ]
}

{
  "reason": "customer_stopped",
  "effective_at": "2026-11-12T09:15:00+05:30",
  "square_off": "next_session"
}

curl -X DELETE "https://api.broker.example/subscriptions/sub_5c0d" \
  -H "Content-Type: application/json" \
  -H "partner_id: ptn_lantern" \
  -H "partner_secret: <secret>" \
  -d '{"reason":"customer_stopped","effective_at":"2026-11-12T09:15:00+05:30","square_off":"next_session"}'

{
  "subscription_id": "sub_5c0d",
  "status": "cancelled",
  "end_at": "2026-11-12T09:15:00+05:30"
}

Glossary

Algo ID

The identifier an exchange assigns to a registered algorithm; sent on every algo order

Black box / white box

A strategy whose rules are confidential / disclosed to subscribers

Correlation ID

Lantern's unique key per order, used for idempotency and reconciliation

Fan-out

Turning one provider signal into orders for every subscriber

High-water mark

The previous peak of a subscription's equity; profit share applies only above it

Kill switch

The Broker's control that stops all Lantern order flow for a scope immediately

Multiplier

The subscriber's size relative to the strategy's minimum (1x)

OMS / RMS

The Broker's order management and risk management systems

Partner consent flow

Login on the Broker's page that returns a token scoped to Lantern

Signal

A provider's instruction (entry, exit, modify) with legs and risk limits

Related: Provider API · OpenAPI document · For providers · Risk disclosure · Terms.