GDTrack

🇪🇬 Egypt Gold API

Real-time Egyptian gold market prices — buy/sell spreads, all karats, historical data, and the local USD/EGP gold rate.

A production-ready REST API built with Kotlin + Ktor that scrapes and serves live gold prices from the Egyptian local market (Saghah). Unlike generic financial APIs, this one delivers the actual buy/sell prices that Egyptian gold traders use, complete with per-karat breakdowns and persistent price history.

---

✨ Features

Feature	Details
🔴 Real-Time Prices	Live buy & sell prices scraped directly from Egyptian gold market sources
📊 All Major Karats	Supports 24K, 21K, 18K, 14K, and 12K gold
📈 Price History	Query up to 100 historical records per karat stored in PostgreSQL
💵 Dollar Rate	Returns the actual USD/EGP exchange rate used by local gold traders
🔁 Multi-Source	Falls back across 3 data sources to guarantee uptime
⚡ Smart Caching	In-memory cache refreshed every 10 minutes — fast responses, minimal scraping
🗄️ Persistent Storage	All price snapshots saved to PostgreSQL for trend analysis
🐳 Docker Ready	Single docker-compose up gets the full stack running
📖 OpenAPI / Swagger	Interactive API docs served at /swagger
🔒 Rate Limiting & CORS	Built-in Ktor middleware for production safety

---

🛠️ Tech Stack

• Language: Kotlin
• Framework: Ktor
• Database: PostgreSQL 16 + Exposed ORM + HikariCP connection pooling
• HTML Parsing: Ksoup
• Serialization: kotlinx.serialization
• Build Tool: Gradle (Kotlin DSL)
• Deployment: Docker + Docker Compose

---

📡 API Endpoints

All endpoints are prefixed with /api/v1/gold.

GET /prices

Returns current buy and sell prices for all karats along with the dollar rate and cache metadata.

Example Response:

{
   "data": {
      "karat24": {
         "karat": 24,
         "buyPrice": 8000,
         "sellPrice": 8034,
         "pricePerGram": 8017,
         "pricePerOunce": 249356.76,
         "updatedAt": "2026-05-08T11:59:05.833065293Z"
      },
      "karat21": {
         "karat": 21,
         "buyPrice": 7000,
         "sellPrice": 7029,
         "pricePerGram": 7014.5,
         "pricePerOunce": 218175.5,
         "updatedAt": "2026-05-08T11:59:05.833065293Z"
      },
      "karat18": {
         "karat": 18,
         "buyPrice": 6000,
         "sellPrice": 6025,
         "pricePerGram": 6012.5,
         "pricePerOunce": 187009.79,
         "updatedAt": "2026-05-08T11:59:05.833065293Z"
      },
      "karat14": {
         "karat": 14,
         "buyPrice": 4666,
         "sellPrice": 4686,
         "pricePerGram": 4676,
         "pricePerOunce": 145439.97,
         "updatedAt": "2026-05-08T11:59:05.833065293Z"
      },
      "karat12": {
         "karat": 12,
         "buyPrice": 4000,
         "sellPrice": 4017,
         "pricePerGram": 4008.5,
         "pricePerOunce": 124678.38,
         "updatedAt": "2026-05-08T11:59:05.833065293Z"
      },
      "dollarRate": 52.67,
      "goldUsdPerOunce": 0
   },
   "meta": {
      "updatedAt": "2026-05-08T11:59:05.833065293Z",
      "nextUpdateAt": "2026-05-08T12:59:05.833065293Z"
   }
}

---

GET /prices/{karat}

Returns prices for a single karat. Accepted values: 24, 21, 18, 14, 12.

GET /api/v1/gold/prices/21

{
  "data": {
    "karat": 21,
    "buyPrice": 7000,
    "sellPrice": 7029,
    "pricePerGram": 7014.5,
    "pricePerOunce": 218175.5,
    "updatedAt": "2026-05-08T11:59:05.833065293Z"
  },
  "meta": {
    "updatedAt": "2026-05-08T11:59:05.833065293Z",
    "nextUpdateAt": "2026-05-08T12:59:05.833065293Z"
  }
}

Returns 400 for invalid karats, 503 if the source is unreachable.

---

GET /history/{karat}?limit=30

Returns historical price snapshots for a given karat, ordered newest first.

Query Param	Default	Max
limit	30	100

{
  "karat": 18,
  "data": [
    {
      "buyPrice": 5996,
      "sellPrice": 6021,
      "pricePerGram": 6008.5,
      "pricePerOunce": 186885.37975,
      "recordedAt": "2026-05-08T12:09:07.286515Z"
    },
    {
      "buyPrice": 6000,
      "sellPrice": 6025,
      "pricePerGram": 6012.5,
      "pricePerOunce": 187009.79375,
      "recordedAt": "2026-05-08T11:59:05.833065Z"
    },
    {
      "buyPrice": 6000,
      "sellPrice": 6025,
      "pricePerGram": 6012.5,
      "pricePerOunce": 187009.79375,
      "recordedAt": "2026-05-08T11:49:03.245126Z"
    },
    {
      "buyPrice": 5996,
      "sellPrice": 6021,
      "pricePerGram": 6008.5,
      "pricePerOunce": 186885.37975,
      "recordedAt": "2026-05-08T11:39:01.229080Z"
    }
  ]
}

---

GET /dollar-rate

Returns the USD/EGP exchange rate as used in the Egyptian gold market, plus the international gold price per troy ounce.

{
   "dollarRate": 52.67,
   "goldUsdPerOunce": 2350.5,
   "updatedAt": "2026-05-07T14:18:29Z"
}

---

GET /health

Returns the service health status and cache validity.

{
   "status": "ok",
   "cacheValid": true,
   "lastUpdate": "2026-05-08T12:09:07.286514794Z"
}

---

📦 Project Structure

src/main/kotlin/com/egyptgold/
├── Application.kt                   # Entry point
├── plugins/
│   ├── Plugins.kt                   # Ktor plugin configuration (CORS, rate limiting, etc.)
│   ├── Routing.kt                   # Route registration + Swagger UI
│   └── Database.kt                  # Database connection & table creation
├── routes/
│   └── GoldRoutes.kt                # All /api/v1/gold route handlers
├── services/
│   ├── GoldService.kt               # Business logic, caching, DB persistence
│   └── GoldScraperService.kt        # Multi-source web scraper
├── scheduler/
│   └── PriceUpdateScheduler.kt      # Background coroutine — refreshes prices every 10 min
├── models/
│   ├── GoldModels.kt                # Request/response data classes
│   ├── DiamondModels.kt             # (Planned) Diamond pricing models
│   └── Tables.kt                    # Exposed database table definitions
└── Authentication/
    └── configureAuth.kt             # Auth configuration

---

📖 API Documentation

Interactive Swagger UI is available at:

https://pension-charging-supplier.ngrok-free.dev/swagger

---

📄 License

© 2026 GoldTrack Egypt