Overview
Samco Trade API lets you integrate trading, market data, and account management into your own applications. This page describes the recommended setup flow using the current APIs.
Quick Start
Step 1 — Create an OAuth App (One-Time Setup)
All API access starts with an OAuth App. Log in to the Web Dashboard using your Samco Client ID and create an app to obtain:
- API Key — delivered to your registered email address.
- API Secret — shown once in the dashboard; copy it immediately and store it securely.
Detailed steps: Web Dashboard Guide
Step 2 — Register a Static IP (One-Time Setup)
Register the IP address(es) your server will call from under Static IPs in the dashboard. Requests from unregistered IPs are rejected by order-related APIs.
Detailed steps: Web Dashboard Guide — Static IPs
Step 3 — Obtain a Session Token
Choose the flow that fits your integration:
| Flow | When to use | How |
|---|---|---|
Direct (POST /session/token) | Backend / server-to-server — your own apiKey + apiSecret, no browser involved | Generate Session Token |
| OAuth 2.1 (authorization-code) | Third-party apps authenticating end-users through a browser | OAuth 2.1 Authorization-Code Flow |
The session token is a JWT returned by both flows. Send it as the x-session-token header on all subsequent API calls. It is valid until 08:00 IST the next day.
Step 4 — Call the APIs
With a valid x-session-token you can call:
- Orders, Order Book, Trade Book
- Positions, Holdings, User Limit
- Quote, Option Chain, Future Chain
- GTT Orders, Basket Orders
- Intraday & Historical Candle Data
- Streaming Market Data
- Personal Index, Market Depth, Contract Analyser, Span Margin
- Trade View Analytics
Supported Client Runtimes
Samco tests the v3.2 code samples against the following runtime floors. Older versions may work but are not supported.
| Language | Minimum Version | Library Used |
|---|---|---|
| cURL | Any modern shell (bash / zsh) | — (single-quote JSON bodies) |
| Java | JDK 17 LTS+ | Built-in java.net.http.HttpClient (REST) and java.net.http.WebSocket (streaming) |
| Node.js | Node 22 LTS+ | Built-in fetch (REST); ws package for streaming |
| Python | Python 3.8+ | requests (REST); websocket-client (streaming) |
Token Lifetime
Session token expiry
All session tokens — regardless of how they were obtained — expire at 08:00 IST the next calendar day. Refresh by calling POST /session/token again or by repeating the OAuth Login flow.
Deprecated APIs
The following APIs from the legacy flow are deprecated. They continue to work during a transition period but will be removed in a future release. Migrate to the current equivalents listed above.
| Deprecated API | Replacement |
|---|---|
POST /login | Not required with the new session token flow |
POST /login2FA/generateOTP | OTP is handled by the Web Dashboard |
POST /login2FA/generateSecretApiKey | API Secret is generated in the Web Dashboard |
POST /login2FA/generateAccessToken | POST /session/token |
POST /ip/ipRegistration | Web Dashboard — Static IPs |
POST /ip/ipUpdate | Web Dashboard — Static IPs |