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