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

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:

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

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:

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:

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:

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:

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:

Use gRPC when:

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

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.