For the complete documentation index, see llms.txt. This page is also available as Markdown.

32 - Master Contract Download

Overview

Master contracts contain symbol mappings between OpenAlgo's standardized format and broker-specific formats. They are downloaded daily and cached for fast symbol resolution.

Architecture Diagram

┌──────────────────────────────────────────────────────────────────────────────┐
│                    Master Contract Download Architecture                     │
└──────────────────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────────────────┐
│                         Download Trigger                                     │
│                                                                              │
│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐             │
│  │  On Broker      │  │   Manual        │  │   Daily         │             │
│  │  Login          │  │   Trigger       │  │   Scheduled     │             │
│  └────────┬────────┘  └────────┬────────┘  └────────┬────────┘             │
│           │                    │                    │                       │
│           └────────────────────┼────────────────────┘                       │
│                                │                                             │
│                                ▼                                             │
│           ┌─────────────────────────────────────────────────────────┐       │
│           │              Async Download Task                         │       │
│           │              (Background Thread)                         │       │
│           └─────────────────────────────────────────────────────────┘       │
└─────────────────────────────────────────────────────────────────────────────┘


┌─────────────────────────────────────────────────────────────────────────────┐
│                      Broker-Specific Download                                │
│                                                                              │
│  broker/{name}/database/master_contract_db.py                               │
│                                                                              │
│  ┌─────────────────────────────────────────────────────────────────────┐   │
│  │  1. Fetch from broker API or static URL                              │   │
│  │  2. Parse CSV/JSON format                                            │   │
│  │  3. Transform to OpenAlgo format                                     │   │
│  │  4. Store in symtoken table                                          │   │
│  └─────────────────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────────────────┘


┌─────────────────────────────────────────────────────────────────────────────┐
│                        Symbol Database                                       │
│                                                                              │
│  ┌─────────────────────────────────────────────────────────────────────┐   │
│  │                     symtoken table                                   │   │
│  │                                                                      │   │
│  │  symbol     │ exchange │ token    │ lotsize │ tick_size │ ...       │   │
│  │  ──────────────────────────────────────────────────────────────────  │   │
│  │  SBIN       │ NSE      │ 779      │ 1       │ 0.05      │           │   │
│  │  NIFTY      │ NFO      │ 256265   │ 65      │ 0.05      │           │   │
│  │  BANKNIFTY  │ NFO      │ 260105   │ 30      │ 0.05      │           │   │
│  └─────────────────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────────────────┘

Download Process

1. Trigger on Broker Login

2. Background Download

3. Broker-Specific Download

Symbol Database Schema

symtoken Table

Symbol Mapping

OpenAlgo to Broker

Get Token

Get Symbol Info

Broker Implementations

Zerodha

Dhan

Angel One

Caching Strategy

In-Memory Cache

Database Index

Status Tracking

master_contract_status Table

Stuck Download Detection

The system auto-detects stuck master contract downloads. If a download stays in 'downloading' state for more than a configurable timeout (default: 5 minutes), it is automatically marked as an error, and the UI enables the "Force Download" button for manual retry.

Error Handling

Download Failures

Fallback to Cache

If download fails, use existing cached data:

Daily Refresh

Scheduled Update

Key Files Reference

File
Purpose

broker/*/database/master_contract_db.py

Broker download

database/token_db.py

Symbol lookup

database/master_contract_status_db.py

Status tracking

utils/auth_utils.py

Async download trigger

Last updated