Authentication

Prerequisite for all endpoints. No changes from the v1 specification. Please confirm the items below before integration testing.

Items to confirm

Test Accounts

Three accounts required before integration testing begins. All must have Equity & F&O access on NSE and BSE with limited testing funds.

Order Management

Three endpoints for placing, modifying, and cancelling orders. All responses must include the broker order ID and a timestamp.

POST  1. Place Order

Submit a new order to the exchange.

Request fields

Response fields

PUT  2. Modify Order

Edit an open or pending order.

DELETE  3. Cancel Order

Cancel an open or pending order by broker order ID.

Positions & Order Book

Read endpoints for order history and live position data including P&L.

GET  4. Order History / Order Book

All orders for the session across every status.

Required statuses

Required response fields

GET  5. Positions

Intraday (MIS) and overnight (NRML) positions across all states.

Account & Funds

Margin and funds data for pre-order checks. Called before placing orders to validate sufficient margin.

GET  6. Funds / Limits

Must return values separately for Equity and F&O segments.

WebSocket Feeds

Two real-time feeds required for core platform functionality.

WS  7. Order Update Feed

Real-time push for every order status transition.

Required transitions

Required event fields

WS  8. LTP Feed

Token-based live price subscription for real-time P&L and watchlist prices.

Market Data

Instrument master, OHLC candles, and REST LTP fallback.

9. Instrument Master (CSV)

Daily downloadable CSV: token → symbol mapping for all subscriptions and order routing.

GET  10. OHLC / Historical Candles

Required fields per candle

GET  11. LTP REST Fallback

Fetch last traded price when the WebSocket LTP feed is unavailable or not yet connected.

Flutter WebView

Embed the Apt. web app inside your Flutter app with proper loading and error states.

Loading state

Show a spinner while content loads — prevents users seeing a blank screen.

controller = WebViewController()
  ..setJavaScriptMode(JavaScriptMode.unrestricted)
  ..setNavigationDelegate(NavigationDelegate(
    onPageStarted: (url) => setState(() => isLoading = true),
    onPageFinished: (url) => setState(() => isLoading = false),
  ))
  ..loadRequest(Uri.parse('https://webtest.atoms.trade'));

// In build():
Stack(children: [
  WebViewWidget(controller: controller),
  if (isLoading)
    Container(
      color: Colors.white,
      child: const Center(child: CircularProgressIndicator()),
    ),
])

Error handling

Show an error screen instead of a blank page on load failure.

Error events

Error screen must include

JS Channel Bridge

Communication between the Apt. web app and your Flutter host via a named JavaScript channel.

Channel spec

Flutter — register channel

controller = WebViewController()
  ..setJavaScriptMode(JavaScriptMode.unrestricted)
  ..addJavaScriptChannel(
    'FlutterChannel',
    onMessageReceived: (JavaScriptMessage message) {
      if (message.message == 'navigateToHome') {
        widget.onNavigateToHome();
      }
    },
  );

Web app — send a message

window.FlutterChannel.postMessage('navigateToHome');

File Downloads

Download files to the Android Downloads folder using Flutter's MethodChannel and Android's DownloadManager.

Flutter setup

pubspec.yaml

dependencies:
  url_launcher: ^6.2.0

Download function

final _downloadChannel = MethodChannel('YOUR_PACKAGE_NAME/download');

Future<void> triggerDownload(String url, {String? fileName}) async {
  final name = fileName ?? url.split('/').last.split('?').first;
  final safeName = name.isNotEmpty ? name : 'download';
  if (Platform.isAndroid) {
    try {
      final id = await _downloadChannel.invokeMethod<dynamic>(
        'downloadFile', {'url': url, 'fileName': safeName},
      );
      if (id != null) return;
    } catch (e) { debugPrint('Download failed: $e'); }
  }
  final uri = Uri.tryParse(url);
  if (uri != null && await canLaunchUrl(uri)) {
    await launchUrl(uri, mode: LaunchMode.externalApplication);
  }
}

Trigger from WebView

Option A — JS messaging (preferred)

window.FlutterChannel?.postMessage(
  JSON.stringify({ type: 'download', url: fileUrl })
);

Option B — Navigation interception (fallback)

onNavigationRequest: (NavigationRequest request) {
  if (request.url.contains('.xlsx') ||
      request.url.contains('amazonaws.com')) {
    triggerDownload(request.url);
    return NavigationDecision.prevent;
  }
  return NavigationDecision.navigate;
},

AndroidManifest.xml

<uses-permission android:name="android.permission.INTERNET" />

Integration Checklist

Track delivery against each item before go-live.

Backend API

• Place Order — returns broker_order_id + timestamp
• Modify Order — confirms updated order state
• Cancel Order — returns error for already-executed orders
• Order Book — all 6 statuses, both order IDs, timestamps, rejection reason
• Positions — MIS + NRML, all states, avg price, LTP, realised + unrealised P&L
• Funds — available cash, used margin, collateral, available margin per segment
• Order Update WebSocket — all transitions, both order IDs per event
• LTP WebSocket — 3k–10k token range, tick frequency confirmed
• Instrument Master CSV — all 7 columns, daily refresh confirmed
• OHLC Candles — 4 timeframes, 5k candles/call, OI for F&O
• Authentication — token expiry and refresh flow documented

Frontend SDK

• WebView loads Apt. URL with loading indicator
• Error screen on HTTP/network failures with retry
• FlutterChannel registered and navigateToHome handled
• JS messaging download trigger implemented
• Navigation interception fallback for file URLs
• Android DownloadManager with correct package name

Ops & Access

• 3 test accounts provisioned (Equity + F&O, NSE + BSE)
• IP whitelisting requirements confirmed
• WebSocket reconnection behaviour documented
• Rate limits documented for all endpoints

Rate Limits & Open Items

Items needing your confirmation before integration testing begins.