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:

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

2) Set minimal config

Create or edit the following files under config/. 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

3) Run auth and profile check

This validates credentials and token storage.

fyers-auth

Alternative (module): 

$env:PYTHONPATH="src"; python -m fyers.auth

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

Use the canonical backtest entrypoint to pull history and run a basic strategy:

python examples/backtest.py --symbol NSE:SBIN-EQ --resolution D --days 200 --ema-period 120

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

5) 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/backtest_to_live.py --symbol NSE:SBIN-EQ --resolution D --days 120 --go-live

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.

6) 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.

7) Quick health check

If you are wiring your own runner, call Store health checks:

from fyers_store.store import FyersStore

store = FyersStore(rest_adapter=rest, market_ws_adapter=data_ws, order_ws_adapter=order_ws)
print(store.health_check())

Scenario: You want to confirm paths are writable. - Look for cache_db and state_db status values.

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