Documentation

borsa — self-hostable REST API for Egyptian Exchange market data.

Quickstart

git clone https://github.com/7ashraf/borsa.git
cd borsa
cp .env.example .env
# Add at least one provider key to .env
docker compose up

API available at http://localhost:8000. Interactive Swagger docs at /docs.

Endpoints

GET/v1/health

Service health + provider status

{
  "status": "ok",
  "version": "0.1.0",
  "providers_configured": {
    "yahoo": true,
    "alpha_vantage": true,
    "finnhub": true
  }
}

GET/v1/stocks

List all pre-configured EGX symbols

{
  "count": 223,
  "symbols": [
    { "symbol": "COMI", "name": "Commercial International Bank Egypt (CIB) S.A.E.", "sector": "Financials" }
  ]
}

GET/v1/quote/{symbol}

Real-time quote: price, OHLC, volume, change

{
  "symbol": "COMI",
  "company": "Commercial International Bank Egypt (CIB) S.A.E.",
  "price": 136.0,
  "change": null,
  "change_percent": null,
  "volume": 3579806,
  "high": 136.49,
  "low": 132.5,
  "currency": "EGP",
  "source": "Yahoo Finance (COMI.CA)",
  "api_symbol": "COMI.CA"
}

GET/v1/quotes/batch?symbols=COMI,ETEL

Fetch several quotes in one request

{
  "results": [],
  "failed": []
}

GET/demo/quote/{symbol}

Public demo quote endpoint with a global daily request limit

{
  "symbol": "COMI",
  "company": "Commercial International Bank Egypt (CIB) S.A.E.",
  "price": 136.0,
  "currency": "EGP",
  "source": "Yahoo Finance (COMI.CA)"
}

Environment variables

Variable	Default	Description
ALPHA_VANTAGE_KEY	_(empty)_	Alpha Vantage key — provider disabled if empty
FINNHUB_KEY	_(empty)_	Finnhub key — provider disabled if empty
DEMO_ALPHA_VANTAGE_KEY	_(empty)_	Operator key used by /demo endpoints
DEMO_FINNHUB_KEY	_(empty)_	Operator key used by /demo endpoints
ENABLE_YAHOO_FINANCE	false	Enable unofficial Yahoo Finance/yfinance fetching
CACHE_TTL_SECONDS	300	Seconds before a cached response expires
CACHE_MAX_SIZE	512	Maximum entries in the in-process cache
CORS_ORIGINS	*	Comma-separated browser origins allowed to call the API
HOST	0.0.0.0	Bind address
PORT	8000	Bind port
LOG_LEVEL	info	debug · info · warning · error

Architecture

borsa is a thin FastAPI service with an in-process TTL cache. On a cache miss, the StocksService tries configured providers in order. A provider is skipped if its key is absent or its feature flag is false. If all fail, the API returns 503 with per-provider error details.

Client → FastAPI → TTL Cache (hit → return)
                              ↓ (miss)
                         StocksService
                         ├── Provider 1  (if key set, if enabled)
                         ├── Provider 2  (if key set, if enabled)
                         └── Provider N  (fallback source)

EGX Symbols

200+ EGX symbols pre-configured with provider-specific ticker mappings. Use GET /v1/stocks for the full list at runtime, or see the symbol dictionary in the source.

CIBEACOMIEASTEKHOETELHRHOJUFOMFPCOCDIORWEPHDCSMSASUGRSWDYTALM