Skip to content

Quickstart

This guide walks you through a safe first run. It prioritizes read-only and paper-safe workflows before any live trading.

1) Install

From the repo root for development (editable):

pip install -r requirements.txt
pip install -e .

For installed usage (site-packages), set a runtime root and copy templates:

# Choose a writable runtime root; it will hold config/, secrets/, logs/
$env:FYERS_STORE_ROOT="C:\\fyers_store_runtime"
fyers-store init-config         # copies packaged YAML templates into the runtime root

2) Config path precedence (explicit)

Runtime config never lives inside src/fyers_store_resources/config/; that folder only ships templates.

Resolution order (highest to lowest): 1. FYERS_CREDENTIALS_YAML=/absolute/or/relative/path/to/fyers_credentials.yaml 2. FYERS_STORE_ROOT=/path/to/runtime_root → uses: - credentials: ${FYERS_STORE_ROOT}/config/fyers_credentials.yaml - token: ${FYERS_STORE_ROOT}/secrets/fyers_token.json (default) - logs: ${FYERS_STORE_ROOT}/logs/ (default) 3. OS user-data dir (Windows example): C:\Users\<user>\AppData\Local\fyers_store\fyers_store\config\fyers_credentials.yaml

Supported user setups: - Direct file override: set FYERS_CREDENTIALS_YAML to the credentials file path. - Runtime root: set FYERS_STORE_ROOT and keep config/, secrets/, logs/ under it. Use fyers-store init-config to seed templates, then edit them.

Check what the library will use at any time: 

fyers-store print-paths

3) Set minimal config

Create or edit the following files under your runtime config/ (see precedence above). These are required for most workflows.

config/fyers_credentials.yaml 

version: 1
totp_key: "YOUR_TOTP_KEY"
username: "YOUR_USERNAME"
pin: "YOUR_PIN"
client_id: "APP_ID-100"
app_id: "APP_ID"
app_type: "APP_TYPE"
secret_key: "APP_SECRET"
redirect_uri: "https://your.redirect/uri"

config/cache.yaml 

version: 1
db_path: "state_db/history_cache.db"

config/state.yaml 

version: 1
state_db_path: "state_db/fyers_state.db"
account_id: "YOUR_STABLE_ACCOUNT_ID"

Optional but recommended: config/broker.yaml 

version: 1
environment: "PAPER"
allow_live_orders: false

4) Run auth and profile check

This validates credentials and token storage.

$env:PYTHONPATH="src"; python -m fyers_store.auth_client

5) Fetch market history (safe, read-only)

Run the beginner-friendly quick script to pull a small bar window:

python examples/quick_scripts/quick_history_fetch.py

Scenario: You want to confirm the cache is working. - Run the command twice. - The second run should be faster and log fewer REST calls.

6) Paper trade (live data, no real orders)

Paper mode blocks live orders by default. This lets you test your strategy logic against live data without risking funds.

$env:FYERS_ENVIRONMENT="PAPER"
python examples/quick_scripts/quick_live_trading.py

Scenario: You want live ticks but must avoid real orders. - Keep FYERS_ENVIRONMENT=PAPER. - Do not set ALLOW_LIVE_ORDERS=true. - The broker will raise a safety error if any order is submitted.

7) Live trading warning (read carefully)

Live orders are blocked unless you explicitly opt in.

To allow live orders: 

$env:FYERS_ENVIRONMENT="LIVE"
$env:ALLOW_LIVE_ORDERS="true"

Scenario: You are ready to go live. - Double-check config/state.yaml uses a real account_id. - Ensure you understand the no-idempotency risk (see docs/ops/safety-rules.md). - Run a live example only after the paper workflow is clean.

Next Steps

  • Architecture: docs/architecture/system-overview.md
  • Ops playbooks: docs/ops/daily-operations.md
  • Config reference: docs/config/overview.md
  • Usage patterns: docs/usage/backtrader-setup.md