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
2. Obtain your Account ID from your Finam account dashboard
3. Set environment variables:

export FINAM_API_KEY="your_api_key_here"
export FINAM_ACCOUNT_ID="your_account_id_here"

Obtain JWT token before using the API:

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:

jq -r '.exchanges[] | "\(.mic) - \(.name)"' assets/exchanges.json

List stocks available on a specific exchange:

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

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:

# 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:

N=10
jq -r ".[:$N] | .[] | \"\(.ticker) - \(.name)\"" assets/top_ru_equities.json

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:

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:

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:

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:

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:

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:

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

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

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)

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:

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:

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:

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:

# 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 Python library ( pip install git+https://github.com/cia76/FinamPy.git). Full usage reference: gRPC Python Reference

For full REST API details, use the local file: REST Reference For extra gRPC API details, fetch from: gRPC Reference