Finam

Execute trades, manage portfolios, access real-time market data, browse and search market assets, scan volatility, and answer questions about Finam Trade API

Alexander Panov@alexander-panov

Install

openclaw skills install @alexander-panov/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:

Register and obtain your API Key from tokens page
Obtain your Account ID from your Finam account dashboard
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 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

Finam

Install

Finam Trade API Skill

Setup

Market assets

List Available Exchanges and Equities

Get Asset Specification

Search Assets

Get Top N Stocks by Volume

Account Management

Get Account Portfolio

Market Data

Get Latest Quote

Get Order Book (Depth)

Get Recent Trades

Get Historical Candles (OHLCV)

News

Get Latest Market News

Order Management

Place Order

Get Order Status

Cancel Order

Volatility Scanner

REST vs gRPC — When to Use Which

Related skills