Finam Trade API — Python SDK

Thin Python SDK for the Finam Trade API. Wraps the generated gRPC stubs with:

• a single FinamClient / AsyncFinamClient entry point,
• automatic JWT issuance and background refresh (via AuthService.SubscribeJwtRenewal),
• typed exceptions mapped from gRPC status codes,
• exponential-backoff retries on transient failures (UNAVAILABLE, RESOURCE_EXHAUSTED).

Service methods are invoked directly on the generated stubs, so the full proto surface is available without an extra translation layer.

Installation

pip install finam-sdk

The PyPI distribution is finam-sdk; the Python import name is finam_trade_api. (The finam-trade-api name on PyPI is held by an unrelated third-party REST client.)

Quickstart (sync)

from finam_trade_api import FinamClient
from finam_trade_api.accounts import GetAccountRequest
from finam_trade_api.market_data import SubscribeQuoteRequest

with FinamClient(secret="YOUR_API_TOKEN") as client:
    account = client.accounts.GetAccount(GetAccountRequest(account_id="A12345"))
    print(account)

    # Streaming RPCs return iterators.
    for tick in client.market_data.SubscribeQuote(
        SubscribeQuoteRequest(symbols=["SBER@MISX"])
    ):
        print(tick)

Quickstart (asyncio)

import asyncio

from finam_trade_api import AsyncFinamClient
from finam_trade_api.market_data import SubscribeQuoteRequest


async def main() -> None:
    async with AsyncFinamClient(secret="YOUR_API_TOKEN") as client:
        async for tick in client.market_data.SubscribeQuote(
            SubscribeQuoteRequest(symbols=["SBER@MISX"])
        ):
            print(tick)


asyncio.run(main())

Available services

The client exposes the full Trade API surface via sub-clients:

API reference

Every RPC defined in the .proto files is exposed directly on the sub-client. Request and response message types are re-exported from short, per-service modules:

The original deeply-nested paths (finam_trade_api.proto.grpc.tradeapi.v1.<service>.<service>_service_pb2) still work and remain the source of truth.

Legend: ▶ unary · ⇉ server-stream · ⇄ bidi-stream

client.auth — AuthService

client.accounts — AccountsService

client.assets — AssetsService

client.market_data — MarketDataService

client.orders — OrdersService

client.reports — ReportsService

client.metrics — UsageMetricsService

Client lifecycle

for_testing(...) opens an insecure (plaintext) channel against an in-process fake server. Never use against api.finam.ru — it sends your JWT in clear.

Error handling

Wrap raw grpc.RpcError into a typed FinamError:

import grpc
from finam_trade_api import FinamClient, RateLimitError, from_rpc_error

with FinamClient(secret="...") as client:
    try:
        client.accounts.GetAccount(GetAccountRequest(account_id="A12345"))
    except grpc.RpcError as raw:
        err = from_rpc_error(raw)
        if isinstance(err, RateLimitError):
            ...
        raise err

Exception classes: AuthError (401), PermissionDeniedError (403), InvalidArgumentError (400), NotFoundError (404), RateLimitError (429), InternalError (500), ServiceUnavailableError (503), DeadlineExceededError (504). All inherit from FinamError.

Retries

Unary RPCs are retried automatically on UNAVAILABLE and RESOURCE_EXHAUSTED with exponential backoff + jitter. Streaming RPCs are not retried — the caller is expected to handle reconnection at a meaningful boundary (e.g. resuming from the last received bar).

Override the policy:

from finam_trade_api import FinamClient, RetryPolicy

policy = RetryPolicy(max_attempts=6, initial_backoff=0.5, max_backoff=10.0)
client = FinamClient(secret="...", retry_policy=policy)

Local build

From the repository root:

cd sdk/python
pip install -e ".[dev]"
./scripts/generate_proto.sh

scripts/generate_proto.sh compiles the .proto files in ../../proto/ into finam_trade_api/proto/. Re-run it whenever the protos change.

Layout

sdk/python/
├── pyproject.toml
├── README.md
├── LICENSE
├── scripts/
│   └── generate_proto.sh      # protoc invocation (contributors only)
├── examples/                   # runnable scripts
└── finam_trade_api/
    ├── __init__.py
    ├── client.py               # FinamClient (sync)
    ├── aio.py                  # AsyncFinamClient
    ├── auth.py                 # JWT lifecycle
    ├── retry.py                # retry policy + interceptors
    ├── exceptions.py           # typed errors
    ├── _metadata.py            # Authorization header plumbing
    ├── accounts.py             # message re-exports (per-service)
    ├── assets.py
    ├── auth_messages.py
    ├── market_data.py
    ├── orders.py
    ├── reports.py
    ├── metrics.py
    └── proto/                  # generated stubs (committed; ships in wheel)