Prerequisites
Everything you need in place — account, credentials, environment, compliance, and security — before making your first API call.
Overview
This page is a complete pre-integration checklist. Skipping any one of these categories is the single biggest source of "the API doesn't work" support tickets — most turn out to be setup gaps (unenabled API access, unsynced TOTP clock, missing Algo ID tagging) rather than actual API issues. Work through each section before you write your first line of integration code.
1. Account & Access Prerequisites
| Requirement | Details |
|---|
| Active Shoonya trading account | Fully KYC-verified. Your uid (client ID) is tied to this account and appears in every request body. |
| API access explicitly enabled | Opt-in, separate from having a trading account. Confirm this in account settings — a disabled flag here produces a login failure that looks identical to a credentials error. |
| Segment-level exchange enablement | NSE, NFO, BSE, MCX, CDS are enabled independently. A SearchScrip or PlaceOrder call against a segment you're not enabled for fails even with valid credentials — check this before assuming a code bug. |
| Sufficient account funding/margin | Not an API concern directly, but order-placement testing against a zero-margin account returns rejection responses that are easy to misdiagnose as an API integration error. |
2. Authentication Prerequisites
| Requirement | Details |
|---|
| TOTP 2FA configured | Mandatory for both manual and automated login. See TOTP Setup Guide. |
| TOTP secret stored securely | Needed to generate OTPs programmatically for Auto Login. Treat it as a credential, not a config value. |
| System clock synced (NTP) | TOTP is time-based — a server clock drifted by more than ~30s produces intermittent, hard-to-reproduce login failures. Verify NTP sync on any server running automated login, especially cloud VMs. |
| Understanding of session lifecycle | Read Login Flow Overview and Token Renewal — know when your AccessToken expires and how renewal works before building anything that runs unattended overnight. |
| Vendor/App credentials (if applicable) | Only if integrating as a registered vendor rather than a single account holder. See For Vendors / Partners. |
3. Technical / Environment Prerequisites
| Item | Notes |
|---|
| HTTPS-capable HTTP client | All REST endpoints are HTTPS-only, form-urlencoded (jData/jKey) — see API Structure before assuming raw JSON bodies work. |
| Python SDK (recommended) | NorenRestApiPy wraps auth, order, quote, and search calls. See Python SDK. |
| WebSocket client library | Required only for live feeds (order updates, market data). See WebSocket Overview. Not needed for REST-only, poll-based integrations. |
| Reconnect/retry handling capability | WebSocket connections drop — plan reconnect logic (exponential backoff, resubscribe-on-reconnect) as a first-class design concern, not an afterthought bolted on after production issues surface. |
| Reliable outbound network path | If running on a corporate network or restrictive cloud VPC, confirm outbound HTTPS/WSS to api.shoonya.com isn't blocked by firewall/proxy rules before debugging "connection refused" as an SDK issue. |
| Logging in place | Structured logging (request payload, response, latency) from day one — this is what actually lets you tell "no data" (normal) apart from "session expired" (needs re-auth) apart from "network failure" (needs retry) at 2am when something breaks unattended. |
4. Security Prerequisites
| Item | Notes |
|---|
| Secrets management | Env vars, a secrets manager, or encrypted config — never commit uid, password, or TOTP secret to source control, including private repos. |
| AccessToken handling | Store tokens encrypted at rest if persisted between runs. Treat a leaked AccessToken as equivalent to a leaked password — it grants full account access until it expires or is invalidated. |
| IP allowlisting awareness (if enforced on your account) | Some account configurations restrict API calls to specific IPs. If you plan to run from a dynamic-IP environment (e.g. home broadband, ephemeral cloud instances), confirm this isn't enabled or plan for a static egress IP. |
| Least-privilege deployment | If multiple services touch the same account (e.g. a quote poller and a separate order engine), consider whether they need to share one token/session or should be isolated — a bug in one shouldn't be able to silently place orders via the other. |
5. Compliance Prerequisites (if running an algo)
If you're building an automated/algorithmic strategy — as opposed to a manual-trigger tool a human approves before each order — read SEBI Algo ID Framework before writing any order-placement code.
- Determine whether your strategy is white-box or black-box under SEBI's Feb 2025 circular — this determines your disclosure obligations.
- Confirm NNF ID / Algo ID tagging requirements and build them into your order payload structure from the start — retrofitting tagging after orders are already flowing is significantly more error-prone than designing for it up front.
- If distributing your strategy to other users (vendor model), confirm empanelment status and NDA terms are in place before onboarding external clients.
- Track the enforcement deadline for your compliance category — see SEBI Algo ID Framework for current dates.
6. Operational Readiness
| Item | Why it matters |
|---|
| Rate limit awareness | Review Rate Limits before designing polling logic. Code that works fine in light testing can silently start failing near production load if it wasn't designed against the actual limits. |
| Error handling strategy | Read Error Handling — know the difference between a retryable error (session expired, transient network) and a non-retryable one (invalid input, insufficient margin) before your retry logic accidentally loops on something it can never fix. |
| Idempotency plan for order placement | Network retries on a timed-out PlaceOrder call can result in duplicate orders if you don't have a way to check "did this actually go through" before retrying. |
| Monitoring / alerting | For anything running unattended (algo strategies, scheduled quote pollers), have alerting on auth failures and WebSocket disconnects — silent failure in a trading system is worse than a loud one. |
Pre-flight Checklist
- Shoonya trading account active, KYC complete, sufficiently funded
- API access enabled on the account
- Required exchange segments enabled (NSE/NFO/BSE/MCX/CDS as needed)
- TOTP 2FA configured, secret stored securely, server clock NTP-synced
- Read Authentication Overview and Token Renewal
- HTTP client / SDK chosen and installed
- Reconnect/retry strategy planned for WebSocket use (if applicable)
- Secrets management in place — no credentials in source control
- Read Rate Limits and Error Handling
- Idempotency plan for order placement retries
- If running an algo: reviewed SEBI Algo ID Framework, Algo ID tagging designed in
- Monitoring/alerting plan for unattended processes
Notes
Treat this list as gating, not optional — most production incidents in trading integrations trace back to one of these being skipped rather than a defect in the API itself. Once every box is checked, continue to Quick Start (5 minutes) for your first authenticated call.
Overview
This page is a complete pre-integration checklist. Skipping any one of these categories is the single biggest source of "the API doesn't work" support tickets — most turn out to be setup gaps (unenabled API access, unsynced TOTP clock, missing Algo ID tagging) rather than actual API issues. Work through each section before you write your first line of integration code.
1. Account & Access Prerequisites
uid(client ID) is tied to this account and appears in every request body.SearchScriporPlaceOrdercall against a segment you're not enabled for fails even with valid credentials — check this before assuming a code bug.2. Authentication Prerequisites
AccessTokenexpires and how renewal works before building anything that runs unattended overnight.3. Technical / Environment Prerequisites
jData/jKey) — see API Structure before assuming raw JSON bodies work.NorenRestApiPywraps auth, order, quote, and search calls. See Python SDK.api.shoonya.comisn't blocked by firewall/proxy rules before debugging "connection refused" as an SDK issue.4. Security Prerequisites
uid, password, or TOTP secret to source control, including private repos.AccessTokenas equivalent to a leaked password — it grants full account access until it expires or is invalidated.5. Compliance Prerequisites (if running an algo)
If you're building an automated/algorithmic strategy — as opposed to a manual-trigger tool a human approves before each order — read SEBI Algo ID Framework before writing any order-placement code.
6. Operational Readiness
PlaceOrdercall can result in duplicate orders if you don't have a way to check "did this actually go through" before retrying.Pre-flight Checklist
Notes
Treat this list as gating, not optional — most production incidents in trading integrations trace back to one of these being skipped rather than a defect in the API itself. Once every box is checked, continue to Quick Start (5 minutes) for your first authenticated call.