Building an Open-Source API for Egyptian Stock Market Data

Muhamed Ashraf — Tue, 26 May 2026 03:33:22 +0000

A few months ago I was working on an investments page inside an app. Standard stuff — a portfolio view, some live prices, a few charts, the ability to track stocks the user cared about.

The Egyptian Exchange (EGX) data piece was the last thing on my list. I figured it would be the easiest. Just pip install whichever library people use, plug in an API key, ship the feature.

That's not how Egyptian market data works.

Two days of dead ends later I was writing my own data layer — a small Python service that stitched together multiple providers, fell back between them when any of them rate-limited, and gave the app one clean interface to call. It worked. The investments page launched. I kept using the script internally.

After a while it became increasingly obvious that I wasn't the only Egyptian developer who'd hit this wall. So I cleaned it up, packaged it properly, and open sourced it. That's Borsa.

This post is about why I built it, how it works, and the piece of the implementation I'm most proud of.

The problem: programmatic EGX access barely exists

If you trade or build on US equities you're spoiled for choice. yfinance, Polygon, Tiingo, Alpaca, IEX Cloud — pick your poison. The data is clean, the libraries are mature, and there's an entire ecosystem of tooling that "just works."

For EGX, the landscape is brutal:

Bloomberg Terminal covers EGX well. It also costs around $20,000+/year per seat.
Reuters Eikon / Refinitiv Workspace has it too. Institutional pricing.
Mubasher is what most retail traders in Egypt actually use. There's no public API.
Direct EGX data feeds are sold to brokerages, not to individuals.
A handful of consumer providers (Alpha Vantage, Finnhub, Yahoo Finance) include some EGX coverage — but each covers a different partial slice, with different intraday support, different rate limits, and different terms of service. For one of the largest stock exchanges in MENA, the message to individual developers is essentially: pay $20k+/year or stitch it together yourself.

I stitched it together myself.

Why existing tools didn't fit

I looked, hard, before resigning myself to writing my own. There are scrapers people have published as gists. There's pandas_datareader, which is mostly unmaintained for international markets. There are wrappers for individual providers that don't talk to each other. There are SaaS startups in the broader MENA fintech space, but most are closed and product-focused, not infrastructure.

What I couldn't find was anything that:

Abstracted over the consumer providers that do cover EGX,
Fell back gracefully when one rate-limited me, and
Ran on infrastructure I controlled. So the script I wrote for the app did all three. It was rough at first — hard-coded mappings, single file, no tests — but it worked. Once I'd been using it for a few weeks and the rough edges had smoothed out, turning it into a proper open-source project felt like the next natural step.

The architecture decision: self-host + BYOK

Two choices shaped what Borsa became when I cleaned it up.

Self-hostable. Borsa runs as a FastAPI service in a single Docker container. No SaaS, no signup, no usage tracking. You clone the repo, set env vars for whichever providers you want, and docker compose up. The whole thing fits on a $5 VPS.

Bring your own keys (BYOK). I don't proxy requests through my own keys. You sign up directly with Alpha Vantage, Finnhub, or Yahoo Finance, paste the keys into .env, and Borsa uses them. This dodges two problems: I don't manage a shared rate-limit pool (your quota is yours), and I don't have to handle billing if you outgrow free tiers.

The combination — self-host + BYOK — is also what makes it legally clean. Borsa is MIT, providers have their own ToS, and the relationship is just "you brought their key to my code." No reselling, no aggregation business, no risk of getting yanked offline.

Technical walkthrough

The request flow is unsurprising: FastAPI receives a request, checks the cache, falls through to a provider chain if cold, and returns a unified response shape regardless of which provider answered.

# app/routes.py
@router.get("/quote/{symbol}", response_model=QuoteResponse)
async def get_quote(symbol: str) -> QuoteResponse:
    canonical = normalize_symbol(symbol)
    if cached := cache.get(canonical):
        return cached
    quote = await provider_chain.fetch_quote(canonical)
    cache[canonical] = quote
    return quote

For batch requests — say, fetching quotes for 30 symbols at once — asyncio.gather parallelizes the work. Each symbol runs through its own provider chain independently, so a rate-limit on one symbol doesn't block the others.

async def fetch_quotes(symbols: list[str]) -> list[QuoteResult]:
    return await asyncio.gather(
        *(get_quote(s) for s in symbols),
        return_exceptions=True,
    )

The cache is deliberately boring: cachetools.TTLCache with a 60-second TTL by default, configurable per-endpoint. In-process, no Redis, no extra moving parts. For a self-hosted API that one developer is hitting from a notebook or a backtest harness, this is plenty. If you outgrow it, swap in Redis — the cache is a single dependency-injected protocol.

The fallback chain (the interesting bit)

This is the piece that mattered most in the original app, and still matters in Borsa.

Free-tier providers are unreliable. Alpha Vantage caps you at 25 calls/day. Finnhub at 60/minute. Yahoo isn't even rate-limited cleanly — it just starts returning empty payloads or 429s when it decides you've had enough. When my investments page depended on any one of these, I had a bad day on a regular basis.

The fallback chain treats providers as interchangeable for any given symbol. Try the primary; if it fails or rate-limits, transparently try the next.

# app/providers/chain.py
class ProviderChain:
    def __init__(self, providers: list[Provider]):
        self.providers = providers

    async def fetch_quote(self, symbol: CanonicalSymbol) -> Quote:
        last_error = None
        for provider in self.providers:
            if not provider.supports(symbol):
                continue
            try:
                return await provider.fetch_quote(symbol)
            except (RateLimitError, ProviderUnavailable) as e:
                last_error = e
                continue
        raise NoDataAvailable(symbol, last_error)

What makes this work is that every provider exposes the same shape. Quote is a single dataclass, every provider implementation returns one, and the route handler doesn't know or care who answered. Adding a new provider is implementing one interface:

class Provider(Protocol):
    async def fetch_quote(self, symbol: CanonicalSymbol) -> Quote: ...
    async def fetch_history(self, symbol: CanonicalSymbol, ...) -> History: ...
    def supports(self, symbol: CanonicalSymbol) -> bool: ...

supports() matters because providers don't have identical coverage — the chain skips providers that can't serve a given symbol rather than wasting a call. Coverage and provider-specific symbol mapping live in a single YAML registry loaded at startup:

# symbols/egx.yaml
- canonical: CIB
  name: Commercial International Bank
  sector: Banking
  providers:
    alpha_vantage: CIBEA.CAI
    finnhub: COMI.CA
    yahoo: COMI.CA

Borsa ships with 200+ EGX symbols pre-mapped this way. Adding more is a PR against this one file — anyone can do it.

What I learned

A few things stuck.

Building infrastructure for a market that already has good infrastructure is a slog — everything has been done. Building for a market that doesn't is invigorating, because every small improvement is the new state of the art. The first time someone other than me used Borsa to pull EGX data without manual fiddling, I understood why people enjoy infra work.

Open sourcing internal tools you've already battle-tested is a much better path than building open source from scratch with no concrete user. By the time I was packaging Borsa, the design choices had been validated by months of an actual product depending on them. The hard questions were already answered.

Also: rate limits will humble you. Designing for failure (the fallback chain) rather than the happy path made the whole system more honest about what it actually is — a thin, careful layer over services I don't control.

How to contribute

Borsa lives at https://github.com/7ashraf/borsa (MIT).

The live demo is at borsa.ashh.me — please be gentle, it's a single small instance.

The most useful contributions right now:

More EGX symbols in symbols/egx.yaml. 200+ are pre-mapped, but EGX has more and coverage maps drift over time.
A Mubasher provider for users who already have access. The Provider interface is maybe 40 lines to implement.
Arabic translations for the README and API error messages.
Backtest examples showing how to wire Borsa into vectorbt or backtrader. If you're in the MENA dev or quant scene, this tool is for you as much as for me. Open an issue, send a PR, or just tell me what's missing. The point is to build the layer the ecosystem doesn't yet have.

DEV Community: Muhamed Ashraf