finam

# Finam Trade API Skill ## Setup **Prerequisites:** `$FINAM_API_KEY` and `$FINAM_ACCOUNT_ID` must be already set in your environment. If not configured by environment, follow these steps: 1. Register and obtain your API Key from [tokens page](https://tradeapi.finam.ru/docs/tokens) 2. Obtain your Account ID from your [Finam account dashboard](https://lk.finam.ru/) 3. Set environment variables: ```shell export FINAM_API_KEY="your_api_key_here" export FINAM_ACCOUNT_ID="your_account_id_here" ``` Obtain JWT token before using the API: ```shell export FINAM_JWT_TOKEN=$(curl -sL "https://api.finam.ru/v1/sessions" \ --header "Content-Type: application/json" \ --data '{"secret": "'"$FINAM_API_KEY"'"}' | jq -r '.token') ``` **Note:** Token expires after 15 minutes. Re-run this command if you receive authentication errors. ## Market assets ### List Available Exchanges and Equities **Symbol Format:** All symbols must be in `ticker@mic` format (e.g., `SBER@MISX`) **Base MIC Codes:** - `MISX` - Moscow Exchange - `RUSX` - RTS - `XNGS` - NASDAQ/NGS - `XNMS` - NASDAQ/NNS - `XNYS` - New York Stock Exchange View all supported exchanges with their MIC codes: ```shell jq -r '.exchanges[] | "\(.mic) - \(.name)"' assets/exchanges.json ``` List stocks available on a specific exchange: ```shell MIC="MISX" LIMIT=20 jq -r ".$MIC[:$LIMIT] | .[] | \"\(.symbol) - \(.name)\"" assets/equities.json ``` ### Get Asset Specification Fetch detailed specification for a specific instrument (lot size, price step, decimals, trading schedule, etc.): ```shell SYMBOL="SBER@MISX" curl -sL "https://api.finam.ru/v1/assets/$SYMBOL?account_id=$FINAM_ACCOUNT_ID" \ --header "Authorization: $FINAM_JWT_TOKEN" | jq ``` `account_id` is optional but recommended — returns account-specific fields (margin, available quantity, etc.). ### Search Assets Search instruments by ticker glob pattern and/or name substring: ```shell # By ticker glob python3 scripts/asset_search.py 'SBER*' # By name (case-insensitive substring) python3 scripts/asset_search.py --name 'apple' # By ticker glob + type filter python3 scripts/asset_search.py 'NG*' --type FUTURES # Search across all instruments (including archived) via /assets/all python3 scripts/asset_search.py 'NG*' --type FUTURES --active false ``` Available types: `EQUITIES`, `FUTURES`, `BONDS`, `FUNDS`, `SPREADS`, `OTHER`, `CURRENCIES`, `OPTIONS`, `SWAPS`, `INDICES` `--max=N` switches to `GET /v1/assets/all` with pagination (rate limit: 200 req/min). `--active false` includes archived instruments. ### Get Top N Stocks by Volume Pre-ranked lists of the 100 most liquid equities for each market, ordered by trading volume descending: ```shell N=10 jq -r ".[:$N] | .[] | \"\(.ticker) - \(.name)\"" assets/top_ru_equities.json ``` ```shell N=10 jq -r ".[:$N] | .[] | \"\(.ticker) - \(.name)\"" assets/top_us_equities.json ``` ## Account Management ### Get Account Portfolio Retrieve portfolio information including positions, balances, and P&L: ```shell curl -sL "https://api.finam.ru/v1/accounts/$FINAM_ACCOUNT_ID" \ --header "Authorization: $FINAM_JWT_TOKEN" | jq ``` ## Market Data ### Get Latest Quote Retrieve current bid/ask prices and last trade: ```shell SYMBOL="SBER@MISX" curl -sL "https://api.finam.ru/v1/instruments/$SYMBOL/quotes/latest" \ --header "Authorization: $FINAM_JWT_TOKEN" | jq ``` ### Get Order Book (Depth) View current market depth with bid/ask levels: ```shell SYMBOL="SBER@MISX" curl -sL "https://api.finam.ru/v1/instruments/$SYMBOL/orderbook" \ --header "Authorization: $FINAM_JWT_TOKEN" | jq ``` ### Get Recent Trades List the most recent executed trades: ```shell SYMBOL="SBER@MISX" curl -sL "https://api.finam.ru/v1/instruments/$SYMBOL/trades/latest" \ --header "Authorization: $FINAM_JWT_TOKEN" | jq ``` ### Get Historical Candles (OHLCV) Retrieve historical price data with specified timeframe: ```shell SYMBOL="SBER@MISX" TIMEFRAME="TIME_FRAME_D" START_TIME="2024-01-01T00:00:00Z" END_TIME="2024-04-01T00:00:00Z" curl -sL "https://api.finam.ru/v1/instruments/$SYMBOL/bars?timeframe=$TIMEFRAME&interval.start_time=$START_TIME&interval.end_time=$END_TIME" \ --header "Authorization: $FINAM_JWT_TOKEN" | jq ``` **Available Timeframes:** | Timeframe | Description | Max data depth (end_time - start_time) | |---|---|---| | `TIME_FRAME_UNSPECIFIED` | Not specified | — | | `TIME_FRAME_M1` | 1 minute | 7 days | | `TIME_FRAME_M5` | 5 minutes | 30 days | | `TIME_FRAME_M15` | 15 minutes | 30 days | | `TIME_FRAME_M30` | 30 minutes | 30 days | | `TIME_FRAME_H1` | 1 hour | 30 days | | `TIME_FRAME_H2` | 2 hours | 30 days | | `TIME_FRAME_H4` | 4 hours | 30 days | | `TIME_FRAME_H8` | 8 hours | 30 days | | `TIME_FRAME_D` | Day | 365 days | | `TIME_FRAME_W` | Week | ~5 years | | `TIME_FRAME_MN` | Month | ~5 years | | `TIME_FRAME_QR` | Quarter | ~5 years | > **Note:** The max data depth is the maximum allowed range for `end_time - start_time`. If the range exceeds the limit, the API returns empty data. **Date Format (RFC 3339):** - Format: `YYYY-MM-DDTHH:MM:SSZ` or `YYYY-MM-DDTHH:MM:SS+HH:MM` - `start_time` - Inclusive (interval start, included in results) - `end_time` - Exclusive (interval end, NOT included in results) - Examples: - `2024-01-15T10:30:00Z` (UTC) - `2024-01-15T10:30:00+03:00` (Moscow time, UTC+3) ## News ### Get Latest Market News Fetch and display the latest news headlines. No JWT token required. Russian market news ```shell curl -sL "https://www.finam.ru/analysis/conews/rsspoint/" | python3 -c " import sys, xml.etree.ElementTree as ET root = ET.parse(sys.stdin).getroot() for item in reversed(root.findall('.//item')): print(f'* {item.findtext('title','')}. {item.findtext('description','').split('...')[0]}') " ``` US market news ```shell curl -sL "https://www.finam.ru/international/advanced/rsspoint/" | python3 -c " import sys, xml.etree.ElementTree as ET root = ET.parse(sys.stdin).getroot() for item in reversed(root.findall('.//item')): print(f'* {item.findtext('title','')}. {item.findtext('description','').split('...')[0]}') " ``` **Parameters:** - Change `[:10]` to any number to control how many headlines to display ## Order Management > **IMPORTANT:** Before placing or cancelling any order, you MUST explicitly confirm the details with the user and > receive their approval. State the full order parameters (symbol, side, quantity, type, price) and wait for confirmation > before executing. ### Place Order **Order Types:** - `ORDER_TYPE_MARKET` - Market order (executes immediately, no `limit_price` required) - `ORDER_TYPE_LIMIT` - Limit order (requires `limit_price`) ```shell curl -sL "https://api.finam.ru/v1/accounts/$FINAM_ACCOUNT_ID/orders" \ --header "Authorization: $FINAM_JWT_TOKEN" \ --header "Content-Type: application/json" \ --data "$(jq -n \ --arg symbol "SBER@MISX" \ --arg quantity "10" \ --arg side "SIDE_BUY" \ --arg type "ORDER_TYPE_LIMIT" \ --arg price "310.50" \ '{symbol: $symbol, quantity: {value: $quantity}, side: $side, type: $type, limit_price: {value: $price}}')" \ | jq ``` **Parameters:** - `symbol` - Instrument (e.g., `SBER@MISX`) - `quantity.value` - Number of shares/contracts - `side` - `SIDE_BUY` or `SIDE_SELL` - `type` - `ORDER_TYPE_MARKET` or `ORDER_TYPE_LIMIT` - `limit_price` - Only for `ORDER_TYPE_LIMIT` (omit for market orders) ### Get Order Status Check the status of a specific order: ```shell ORDER_ID="12345678" curl -sL "https://api.finam.ru/v1/accounts/$FINAM_ACCOUNT_ID/orders/$ORDER_ID" \ --header "Authorization: $FINAM_JWT_TOKEN" | jq ``` ### Cancel Order Cancel a pending order: ```shell ORDER_ID="12345678" curl -sL --request DELETE "https://api.finam.ru/v1/accounts/$FINAM_ACCOUNT_ID/orders/$ORDER_ID" \ --header "Authorization: $FINAM_JWT_TOKEN" | jq ``` ## Volatility Scanner Scans the top-100 stocks for a given market and prints the most volatile ones based on annualized historical volatility (close-to-close, last 60 days). **Usage:** ```shell python3 scripts/volatility.py [ru|us] [N] ``` **Arguments:** - `ru` / `us` — market to scan (default: `ru`) - `N` — number of top results to display (default: `10`) **Examples:** ```shell # Top 10 most volatile Russian stocks python3 scripts/volatility.py ru 10 # Top 5 most volatile US stocks python3 scripts/volatility.py us 5 ``` All scripts support `--help` for usage details (e.g. `python3 scripts/volatility.py --help`). ## REST vs gRPC — When to Use Which **Use REST when:** - Fetching historical OHLCV data for backtesting or analysis - Retrieving account info, positions, balances, and trade history - Searching instruments or fetching asset specifications - Placing or cancelling a one-off order where 100–200 ms latency is acceptable - Checking order status after placement **Use gRPC when:** - Subscribing to real-time market data: quotes, order book, trade feed - Processing live bar data (M1, M5) for signal generation in event-driven strategies - Monitoring own orders and trades in real time via subscription - Your strategy requires minimal latency for rapid order placement/cancellation - Building long-running trading bots that need persistent, auto-reconnecting connections For gRPC, use the [FinamPy](https://github.com/cia76/FinamPy) Python library ( `pip install git+https://github.com/cia76/FinamPy.git`). Full usage reference: [gRPC Python Reference](references/GRPC.md) --- For full REST API details, use the local file: [REST Reference](references/REST.md) For extra gRPC API details, fetch from: [gRPC Reference](https://tradeapi.finam.ru/docs/grpc/)