aiomoexalgo 1.0.1

API client for api.moex and iss.moex

aiomoexalgo

Документация на русском

Library supporting sync/async clients, websockets for Moexalgo.

Problems Addressed by the Library

• Addition of async clients and websockets;
• Pydantic type validation of API responses;
• Static typing of API responses, enabling LSP type hinting;
• Single point of truth for MOEX APIs documentation, in-code doc-strings directly referencing respective resources;
• Technology availability: this project is licensed under MIT license, providing an open source alternative which does not require a user to reimburse the authors of the project in any way.

Documentation

The documentation for APIs can be found on:

• Moexalgo (Algopack): moexalgo.github.io
• ISS MOEX API: moex.com
• ISS MOEX API Reference: iss.moex.com
• ISS MOEX Developer Manual: fs.moex.com
• ISS MOEX Informational Product (Subscriptions via passport.moex.com, Data Descriptions): moex.com

Installation

# install from PyPI
pip install aiomoexalgo

Usage

The primary API for interacting with Moexalgo is here. You can get all necessary information about securities for stock, forex, futures markets and derived features specified in the documentation.

import os
from aiomoexalgo import MOEXClient
from aiomoexalgo.types import ISSMarket


client = MOEXClient(
    api_token=os.environ.get("MOEX_API_TOKEN")
)
response = client.get_rt_market_data("SBER", ISSMarket.STOCK)

print(response["marketdata"][0]["OPEN"])

Async Usage

Simply import async flavour of MOEXClient or WebSocket and use await for each API call:

import os
import asyncio
from aiomoexalgo import AsyncMOEXClient
from aiomoexalgo.types import ISSMarket


async def main():
    client = AsyncMOEXClient(
        api_token=os.environ.get("MOEX_API_TOKEN")
    )
    response = await client.get_rt_market_data("SBER", ISSMarket.STOCK)

    print(response["marketdata"][0]["OPEN"])

asyncio.run(main())

Using Types

All returned objects from clients are TypedDict-typed, what provides static typing and enables LSP type hints. Also, that means the data provided "as-is" without any modifications on the side of the API wrapper with minimal performance costs, and user is free to make modifications (pydantic models, pandas.DataFrame, etc.) with the retrieved object.

Important note: no MOEX API documentations explicitly state the methods' response types, especially optional fields, which may cause pydantic.ValidationError. If that happens, please file an issue detailing the type, the field and the value which caused the error. In the meantime, you can set validate_return to False.

API Documentations Specifics

This is the part devoted to the specifics of MOEX APIs which are not explicitly stated in the documentations:

• iss.moex.com and apim.moex.com are backwards compatible and share common query params, however, not all of them work. You can check them here (page 4-5).
• MOEX APIs do not accept a Content-Type header, instead they use file extensions at the end of an endpoint. Available extensions: .xml, .json. If the extension is not specified, then the default is .xml.
• MOEX APIs do not provide correct status codes. What usually happens is that you are redirected to an HTML page stating that an error occurred with status 200.
• It is not possible to verify the validity of an API token. If the token is invalid, you are redirected to an HTML page stating that you need to update it with status 200.

Note: if you have passed an invalid token, any method requiring it will fail, and it is not possible to consistently avoid this behaviour on the client side, since there is no status code policy or explicit documentation for error types.

Engineering Decisions

• niquests is used for the client library. requests is low performant and currently feature-frozen; aiohttp is the fastest python client lib, but recent niquests benchmarks give better results than it, and aiohttp only supports async clients, whereas niquests supports both; httpx is rather unstable with the drama involved with the creator and people in the community going as far as forking and maintaining their own forks (e.g httpx2, httpxyz).
• Query params: iss.meta=off, iss.json=extended. Metadata placement varies across different iss.json responses, which makes it hard to type and later handle these types. Moreover, iss.json=compact (orient=split) requires manually transforming the data to be key-value paired, whereas iss.json=extended (orient=record) already does this despite the increased size of the data transmitted over the network.

Requirements

Python 3.12 or higher.

Contributing

See the contributing documentation.