finam

# Finam Trade API Skill

## Setup

**Prerequisites:** `$FINAM_API_KEY` and `$FINAM_ACCOUNT_ID` must be set in your environment.

If not configured by environment, follow these steps:
1. Register and obtain your API Key from [tokens page](https://tradeapi.finam.ru/docs/tokens)
2. Obtain your Account ID from your [Finam account dashboard](https://lk.finam.ru/)
3. 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
```

### Search Assets by Name

Find a stock by name (case-insensitive) across all exchanges:

```shell
QUERY="apple"
jq -r --arg q "$QUERY" 'to_entries[] | .value[] | select(.name | ascii_downcase | contains($q)) | "\(.symbol) - \(.name)"' assets/equities.json
```

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