Finam Trade API Skill

intent

execute trades and manage portfolios on Finam, fetch real-time and historical market data (quotes, order book, candles), search and browse market assets across Russian and US exchanges, scan volatility, and get market news. use this skill when you need to trade equities, futures, bonds, or funds on Finam; check positions and balances; retrieve price data for analysis; or monitor market conditions. requires active Finam account with API credentials and active JWT session (refreshed every 15 minutes).

inputs

required environment variables:

• FINAM_API_KEY - API secret key from tokens page. scope: full trading and data access.
• FINAM_ACCOUNT_ID - your numeric account ID from Finam dashboard. used in all account and order endpoints.

runtime token:

• FINAM_JWT_TOKEN - obtained by exchanging API key for JWT. expires after 15 minutes. regenerate before use if stale.

binaries required:

• curl - HTTP client for API calls
• jq - JSON parser and formatter
• python3 - for asset search, volatility scanning, and news parsing

external connections:

• Finam REST API (https://api.finam.ru/v1/) - primary endpoint for trades, quotes, historical data
• Finam gRPC API (grpc.finam.ru:443) - optional, for real-time subscriptions (requires FinamPy library)
• Finam web feeds (finam.ru/analysis/conews/rsspoint/, finam.ru/international/advanced/rsspoint/) - news RSS (no auth required)

procedure

1. authenticate and obtain JWT token

inputs: FINAM_API_KEY

steps:

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

outputs: FINAM_JWT_TOKEN environment variable set. token valid for 15 minutes.

edge cases:

• if API key is invalid, curl returns HTTP 401 or API error; jq -r '.token' returns null
• if jq fails to parse, token is empty string; subsequent API calls will fail with 401
• network timeout (>30s): curl hangs; use --max-time 10 to enforce timeout

---

2. retrieve account portfolio (positions, balances, P&L)

inputs: FINAM_JWT_TOKEN, FINAM_ACCOUNT_ID

steps:

curl -sL "https://api.finam.ru/v1/accounts/$FINAM_ACCOUNT_ID" \
  --header "Authorization: $FINAM_JWT_TOKEN" | jq

outputs: JSON object with fields: balance, equity, open_positions[], cash, margin_used, etc.

edge cases:

• if account ID is invalid, HTTP 404 is returned
• if token is expired, HTTP 401; regenerate token (step 1)
• if account has no open positions, open_positions array is empty but present

---

3. search and browse market assets

inputs: optional ticker glob pattern, name substring, asset type filter, active/archived flag

steps (option A: by ticker glob):

python3 scripts/asset_search.py 'SBER*'

steps (option B: by name substring, case-insensitive):

python3 scripts/asset_search.py --name 'apple'

steps (option C: by type filter):

python3 scripts/asset_search.py 'NG*' --type FUTURES

steps (option D: include archived instruments):

python3 scripts/asset_search.py 'NG*' --type FUTURES --active false

outputs: list of matching instruments with symbol, name, type, MIC code. format: TICKER@MIC

asset types: EQUITIES, FUTURES, BONDS, FUNDS, SPREADS, OTHER, CURRENCIES, OPTIONS, SWAPS, INDICES

available exchanges (MIC codes):

• MISX - Moscow Exchange
• RUSX - RTS
• XNGS - NASDAQ/NGS
• XNMS - NASDAQ/NMS
• XNYS - New York Stock Exchange

edge cases:

• if pattern matches >1000 results, pagination required; script uses --max=N flag and switches to /v1/assets/all endpoint (rate limit: 200 req/min)
• if no matches, empty array returned
• archived instruments excluded by default; use --active false to include them

---

4. get asset specification (lot size, price step, decimals, trading hours)

inputs: symbol in format TICKER@MIC, optional FINAM_ACCOUNT_ID for account-specific fields

steps:

SYMBOL="SBER@MISX"
curl -sL "https://api.finam.ru/v1/assets/$SYMBOL?account_id=$FINAM_ACCOUNT_ID" \
  --header "Authorization: $FINAM_JWT_TOKEN" | jq

outputs: JSON object with fields: lot_size, price_step, decimals, trading_schedule, margin_buy, margin_sell, available_for_short_sell, etc.

edge cases:

• if symbol not found, HTTP 404
• if account ID omitted, account-specific fields (margin, available qty) are excluded
• if token expired, HTTP 401

---

5. fetch latest quote (bid/ask, last trade price)

inputs: symbol in TICKER@MIC format, FINAM_JWT_TOKEN

steps:

SYMBOL="SBER@MISX"
curl -sL "https://api.finam.ru/v1/instruments/$SYMBOL/quotes/latest" \
  --header "Authorization: $FINAM_JWT_TOKEN" | jq

outputs: JSON object with: bid, ask, last_price, last_trade_time, volume, open_interest

edge cases:

• market closed: last_price, bid, ask may be stale (from last session close)
• illiquid instruments: bid/ask spreads wide or missing
• if instrument halted, fields present but marked halted: true

---

6. view order book (bid/ask depth)

inputs: symbol, FINAM_JWT_TOKEN

steps:

SYMBOL="SBER@MISX"
curl -sL "https://api.finam.ru/v1/instruments/$SYMBOL/orderbook" \
  --header "Authorization: $FINAM_JWT_TOKEN" | jq

outputs: JSON object with bids[] and asks[] arrays. each level contains price, quantity, and order count.

edge cases:

• no bids/asks if market closed or instrument halted
• depth limited to top 20 levels (API restriction)
• rapid updates; snapshot may be stale within milliseconds

---

7. retrieve recent executed trades

inputs: symbol, FINAM_JWT_TOKEN

steps:

SYMBOL="SBER@MISX"
curl -sL "https://api.finam.ru/v1/instruments/$SYMBOL/trades/latest" \
  --header "Authorization: $FINAM_JWT_TOKEN" | jq

outputs: JSON array of recent trades with: price, quantity, time, side (buyer or seller aggressor)

edge cases:

• limited to last 100 trades
• empty array if no recent activity
• timestamps in UTC or specified timezone

---

8. retrieve historical OHLCV candles

inputs: symbol, timeframe, start time (RFC 3339, inclusive), end time (RFC 3339, exclusive), FINAM_JWT_TOKEN

steps:

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

outputs: JSON array of candles with fields: time, open, high, low, close, volume

available timeframes and max data depth:

timeframe	max range
TIME_FRAME_M1	7 days
TIME_FRAME_M5	30 days
TIME_FRAME_M15	30 days
TIME_FRAME_M30	30 days
TIME_FRAME_H1	30 days
TIME_FRAME_H2	30 days
TIME_FRAME_H4	30 days
TIME_FRAME_H8	30 days
TIME_FRAME_D	365 days
TIME_FRAME_W	5 years
TIME_FRAME_MN	5 years
TIME_FRAME_QR	5 years

date format (RFC 3339): YYYY-MM-DDTHH:MM:SSZ (UTC) or YYYY-MM-DDTHH:MM:SS+HH:MM (with offset). start_time inclusive, end_time exclusive.

edge cases:

• if date range exceeds max depth for timeframe, API returns empty array (no error)
• if start_time >= end_time, empty array returned
• if instrument had no trades in range, empty array returned
• if timeframe invalid, HTTP 400

---

9. fetch market news (Russian and US)

inputs: none (no JWT required)

steps (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]}')
"

steps (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]}')
"

outputs: plain text headlines with snippet from description. one per line.

edge cases:

• feed unavailable (HTTP 5xx): curl fails silently with no output
• XML parse error: python script exits with traceback
• no items in feed: empty output

---

10. place market or limit order

inputs: symbol, quantity, side (BUY/SELL), order type (MARKET or LIMIT), optional limit price, FINAM_JWT_TOKEN, FINAM_ACCOUNT_ID

prerequisite: user must explicitly confirm order details (symbol, side, qty, price, type) before execution.

steps (limit order):

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

steps (market order):

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_MARKET" \
    '{symbol: $symbol, quantity: {value: $quantity}, side: $side, type: $type}')" \
  | jq

outputs: JSON object with fields: order_id, symbol, quantity, side, type, status (typically ACCEPTED), created_at

order parameters:

• symbol - format: TICKER@MIC (e.g. SBER@MISX)
• quantity.value - integer shares or contracts
• side - SIDE_BUY or SIDE_SELL
• type - ORDER_TYPE_MARKET or ORDER_TYPE_LIMIT
• limit_price - required for LIMIT orders only; omit for MARKET orders

edge cases:

• insufficient cash/margin: HTTP 400 with error message
• invalid symbol: HTTP 404
• market closed: order accepted but remains PENDING until market open
• quantity exceeds lot size or position limits: HTTP 400
• token expired: HTTP 401

---

11. check order status

inputs: order ID, FINAM_JWT_TOKEN, FINAM_ACCOUNT_ID

steps:

ORDER_ID="12345678"
curl -sL "https://api.finam.ru/v1/accounts/$FINAM_ACCOUNT_ID/orders/$ORDER_ID" \
  --header "Authorization: $FINAM_JWT_TOKEN" | jq

outputs: JSON object with fields: order_id, status (ACCEPTED, PENDING, EXECUTED, CANCELLED, REJECTED), filled_quantity, remaining_quantity, executed_price, created_at, executed_at

edge cases:

• order ID not found: HTTP 404
• token expired: HTTP 401

---

12. cancel pending order

inputs: order ID, FINAM_JWT_TOKEN, FINAM_ACCOUNT_ID

steps:

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

outputs: HTTP 200 on success. returns cancelled order details or confirmation.

edge cases:

• order ID not found: HTTP 404
• order already executed or cancelled: HTTP 400 (cannot cancel)
• token expired: HTTP 401

---

13. scan top stocks for volatility

inputs: market (ru or us), number of results (default 10)

steps:

python3 scripts/volatility.py ru 10

steps (US market):

python3 scripts/volatility.py us 5

outputs: ranked list of top-N most volatile stocks by annualized historical volatility (close-to-close, last 60 days). format: ticker, name, volatility percentage.

edge cases:

• if market code invalid: script exits with usage error
• if top-100 list unavailable: script fails with file not found or network error
• volatility calculated on minimum 20 data points; if fewer candles available, calculation may be unreliable

---

decision points

decision: token expired or invalid?

• if API returns HTTP 401 (Unauthorized), regenerate JWT token immediately (step 1). do not retry with same token.
• if token is null after step 1, API key is invalid; abort and ask user to verify FINAM_API_KEY.

decision: symbol not found (HTTP 404)?

• user provided incorrect ticker or MIC code.
• fallback: run asset search (step 3) to find correct symbol and MIC.

decision: insufficient funds for order placement?

• API returns HTTP 400 with margin or balance error.
• do not retry; fetch account portfolio (step 2) to show user current cash, equity, margin. ask user to adjust order quantity or deposit funds.

decision: order type chosen?

• if user wants immediate execution at any price, use ORDER_TYPE_MARKET (no limit price required).
• if user wants price protection and willing to wait, use ORDER_TYPE_LIMIT (must specify limit price).

decision: market open or closed?

• if market is closed, orders accepted but remain PENDING until market open. use asset spec (step 4) to check trading_schedule for exact open/close times.
• if market closed and user requests immediate execution (market order), warn that order will not fill until market opens.

**decision: date range exceeds max depth for time