API Documentation — StockTrendz AI

Overview

✅ Base URL: https://stocktrendz.in — all endpoints are relative to this origin.

⚖️ StockTrendz AI™ is not registered with SEBI as an Investment Adviser or Research Analyst. All data is for informational purposes only — not investment advice.

Authentication

JWT Bearer Tokens

Obtain an access_token by calling POST /api/auth/login. Include it in every protected request:

        HTTP Header
Authorization: Bearer <access_token>
      

Tokens are also accepted as a cookie named access_token_cookie if you prefer cookie-based auth.

Auth · Register

POST /api/auth/register Create account ▼

Create a new user account. Returns a JWT access token on success.

Request Body

Field	Type	Description
email*	string	Valid email address
password*	string	Min 8 characters
nameopt	string	Display name

Responses

201Account created, returns access_token

400Validation error or email already registered

POST /api/auth/login Get JWT token ▼

Authenticate and receive a JWT access token valid for 7 days.

Request Body

Field	Type	Description
email*	string	Registered email
password*	string	Account password

Example Response

{ "access_token": "eyJ...", "user": { "id": 42, "email": "user@example.com" } }

200Returns access_token + user info

401Invalid credentials

Market Data

GET /api/index/snapshot NIFTY, SENSEX, top signals ▼

Returns live index prices, market status, sector heatmap, and top trading signals. Served from a shared L1/L2 cache — typically responds in <2 ms. No auth required.

Response Fields

Field	Type	Description
nifty_price	number	NIFTY 50 last price
nifty_change	number	NIFTY % change from prev close
banknifty_price	number	BANK NIFTY last price
sensex_price	number	BSE SENSEX last price
signals	array	Top pattern signals (symbol, pattern, confidence)
sectors	array	Sector % changes
market.is_open	boolean	True if NSE is currently trading
market.as_of_ist	string	Timestamp of data in IST

GET /api/portfolio/live-prices Batch stock quotes ▼

Returns live last-traded prices for up to 50 symbols. Falls back to Yahoo Finance when Zerodha is unavailable. No auth required.

Query Parameters

Param	Type	Description
symbols*	string	Comma-separated instrument IDs, e.g. `NSE:TCS,NSE:INFY`

Example

GET /api/portfolio/live-prices?symbols=NSE:TCS,NSE:RELIANCE,BSE:HDFCBANK

{ "quotes": [
  { "symbol": "NSE:TCS", "last_price": 3842.5, "change": 12.3, "change_pct": 0.32 }
]}

Portfolio · Zerodha Sync

🔒 All portfolio endpoints require a valid JWT token. Credentials supplied for broker sync (api_key, api_secret, tokens) are used in-memory only and are never written to the database, logs, or disk.

POST /api/portfolio/sync 🔑 JWT ▼

Syncs holdings and positions from Zerodha via KiteConnect. Credentials used in-memory only.

Field	Type	Description
api_key*	string	Your Zerodha KiteConnect API key
api_secret*	string	Your KiteConnect API secret
request_token*	string	One-time token from Zerodha OAuth redirect

# Example request
POST /api/portfolio/sync
Authorization: Bearer <token>
Content-Type: application/json

{
  "api_key":       "abcdef1234567890",
  "api_secret":    "your_api_secret",
  "request_token": "one_time_token_from_redirect"
}

200holdings_count, net_positions_count

401Invalid or expired request_token

Portfolio · ICICI Direct Sync

POST /api/portfolio/icici-sync 🔑 JWT ▼

Syncs holdings and positions from ICICI Direct via the Breeze Connect API. Credentials used in-memory only.

💡 To get api_session: visit https://api.icicidirect.com/apiuser/login?api_key=YOUR_KEY, log in, and copy the api_session value from the redirect URL.

Field	Type	Description
api_key*	string	Your ICICI Breeze API key
api_secret*	string	Your Breeze API secret
api_session*	string	One-time session code from ICICI portal redirect

200holdings_count, positions_count

401Invalid or expired session

Portfolio · Read Endpoints

GET /api/portfolio/holdings 🔑 JWT ▼

Returns the user's last-synced holdings with P&L figures. Sync first via /api/portfolio/sync or /api/portfolio/icici-sync.

{ "holdings": [
  { "tradingsymbol": "TCS", "quantity": 10, "average_price": 3600.0,
    "last_price": 3842.5, "pnl": 2425.0, "pnl_pct": 6.74 }
], "summary": { "total_invested": 36000, "total_current_value": 38425, "total_pnl": 2425 } }

GET /api/portfolio/positions 🔑 JWT ▼

Returns open positions. Optional ?type=day or ?type=net to filter.

GET /api/portfolio/pnl 🔑 JWT ▼

P&L summary with up to 365-day trend. Optional ?days=30 (max 365).

Query Param	Type	Description
daysopt	integer	Number of days for trend data (default 30, max 365)

DELETE /api/portfolio/data 🔑 JWT ▼

Permanently deletes all stored holdings, positions, and P&L snapshots for the authenticated user. Does not affect Trade Journal entries. Irreversible.

200Confirmation message

Broker Integrations

GET /zerodha/status Global token validity ▼

Returns the validity and expiry of the server's shared Zerodha access token. Safe to call publicly.

{ "initialized": true, "valid": true, "token_type": "access_token",
  "set_at": "2026-04-07T02:30:00+00:00", "expires_at": "2026-04-07T18:30:00+00:00" }

GET /icici/status ICICI token validity ▼

Returns validity of the server's shared ICICI Breeze token.

{ "initialized": true, "valid": true,
  "set_at": "2026-04-07T03:00:00+00:00", "expires_at": "2026-04-07T18:30:00+00:00" }

POST /icici/activate Activate global ICICI session (admin) ▼

Admin-only. Activates the server's shared ICICI Breeze session using a fresh api_session code. Requires ICICI_ADMIN_SECRET if configured.

Field	Type	Description
api_session*	string	Session code from ICICI portal redirect URL
secretopt	string	Admin secret (`ICICI_ADMIN_SECRET`)

System

GET /api/health System health check ▼

Returns database connectivity, L1/L2 cache stats, and warmer status. No auth required.

{ "status": "healthy", "database": "connected",
  "cache_l1": { "size": 12 }, "warmers": { "index:snapshot": "warm" } }

StockTrendz API

JWT Bearer Tokens