Aress SDK

Official Python client for the Aress Data API — read access to the Iranian capital market: instruments (TSETMC), bonds, currencies, funds, market lists and reports.

• Synchronous and asyncio clients with an identical surface.
• Fully typed pydantic v2 models for every response.
• Jalali (Persian) dates parsed into real jdatetime.date objects.
• Money kept as Decimal (rials) — no float rounding.
• Sensible defaults: timeouts, automatic retries with backoff for transient failures, and a clear exception hierarchy.

Installation

pip install aress-sdk

Requires Python 3.9+. Depends on httpx, pydantic>=2, and jdatetime.

Quickstart

from aress_sdk import AressClient

# An API key is required. The client talks to aress data backend
# by default and sends the key in the ``X-API-Key`` header on every request.
with AressClient("<your api key>") as client:
    # Currencies
    for currency in client.currencies.list():
        print(currency.symbol, currency.farsi_name)

    usd_history = client.currencies.daily_price_history("USD")
    print(usd_history[-1].trade_jdate, usd_history[-1].close_price)

    # Instruments
    sectors = client.instruments.list_sectors()
    steel = client.instruments.list(sector_code="27")
    trades = client.instruments.daily_trade_history("778253364357513")

    # Bonds
    bonds = client.bonds.list(market=1)
    bond = client.bonds.get(bonds[0].id)
    ytm = client.bonds.daily_trade_history(bond.id)

Async

import asyncio
from aress_sdk import AsyncAressClient

async def main():
    async with AsyncAressClient("<your api key>") as client:
        sectors = await client.instruments.list_sectors()
        usd = await client.currencies.daily_price_history("USD")

asyncio.run(main())

Configuration

client = AressClient(
    "<your api key>",                 # required
    timeout=30.0,            # per-request, seconds
    calculate_timeout=300.0, # report calculation endpoints, seconds
    max_retries=2,           # retries on connection errors / 5xx / 429
    backoff_factor=0.5,      # exponential backoff base, seconds
)

Bring your own configured httpx client (proxies, custom TLS, connection pools); the SDK will use it and leave its lifecycle to you:

import httpx
from aress_sdk import AressClient

http = httpx.Client(proxies="http://proxy.example.com:8080")
client = AressClient("<your api key>", http_client=http)  # the key is still sent

Error handling

Every error derives from AressError:

from aress_sdk import AressClient, NotFoundError, AressTransportError

with AressClient("<your api key>") as client:
    try:
        bond = client.bonds.get(999999)
    except NotFoundError as exc:
        print(exc.status_code, exc.detail)   # 404 and the error detail
    except AressTransportError as exc:
        print("network problem:", exc)

Resources & endpoints

Time-series endpoints return records sorted by date ascending.

Development

The project uses Hatch and a src/ layout.

hatch test            # pytest against the installed package (in-process httpx mock, no network)
hatch build           # sdist + wheel into dist/
hatch version minor   # bump src/aress_sdk/_version.py

License

MIT, see LICENSE.