gold-api

A middleware API for XAU/USD data built with Express + TypeScript. It stores real-time price points and historical OHLC candles in Firestore, then serves them via public endpoints for charting.

Architecture

Firestore Collections

Collection	Interval	Used For
gold_prices	2-minute realtime	Latest price endpoint
gold_ohlc_daily	1day	3M, 6M, YTD charts
gold_ohlc_weekly	1week	1Y, 2Y charts
gold_ohlc_monthly	1month	5Y, 10Y charts

Why split by interval:

• Twelve Data intraday depth is limited.
• Daily, weekly, and monthly series are better for long-range chart windows.

Range Mapping

Query range	Collection
1h	gold_prices (full 2-minute points)
5h	gold_prices (full 2-minute points)
1d	gold_prices (downsampled to 10-minute points)
5d	gold_prices (downsampled to 10-minute points)
1w	gold_prices (downsampled to 10-minute points)
1m	gold_prices (downsampled to 2-hour points)
3m	gold_ohlc_daily
6m	gold_ohlc_daily
ytd	gold_ohlc_daily
1y	gold_ohlc_weekly
2y	gold_ohlc_weekly
5y	gold_ohlc_monthly
10y	gold_ohlc_monthly

Requirements

• Node.js 18+
• Twelve Data API key
• Firebase project with Firestore
• GOOGLE_APPLICATION_CREDENTIALS pointing to a service-account JSON file

Setup

1. Install dependencies:

npm install

2. Create .env in project root:

TWELVE_DATA_KEY=your_twelve_data_api_key
INTERNAL_API_KEY=your_private_scheduler_key
FIRESTORE_DATABASE=gold-api
PORT=3000

Run

Development:

npm run dev

Production:

npm run build
npm start

API

Public Endpoints

GET /api/gold

Returns latest cached realtime price.

Response 200:

{
  "timestamp": 1741651200000,
  "price": 3150.42
}

Response 503 when service has no cached price yet.

GET /api/gold/history?range=1m

Returns historical series sorted oldest to newest.

Allowed range values:

• 1h, 5h, 1d, 5d, 1w, 1m, 3m, 6m, ytd, 1y, 2y, 5y, 10y

Sampling rules:

• 1h, 5h: full 2-minute data from gold_prices
• 1d, 5d, 1w: downsampled to 10-minute steps from gold_prices
• 1m: downsampled to 2-hour steps from gold_prices
• 3m+: OHLC candles from daily/weekly/monthly collections

Response 200 example:

[
  { "timestamp": 1741651200000, "price": 3150.42 },
  { "timestamp": 1741651320000, "price": 3150.35 }
]

GET /api/gold/trading-day

Returns realtime points (gold_prices) plus summary values for the active or most recently completed trading day (XAU/USD). Gold trades 24 hours a day from Sunday 18:00 to Friday 17:00 New York time, with a daily 1-hour break from 17:00 to 18:00.

• During Active Market Hours: Returns all points for the current ongoing trading session (starting at 18:00 NY time the previous day).
• During Weekends & Daily Breaks: If requested outside of trading hours, the API automatically returns the full data of the previous completed trading day. This ensures clients always receive a complete set of data to render, even on a Saturday.

Response 200 example:

{
  "tradingDay": "2026-03-26",
  "previousClose": 3024.15,
  "high": 3040.22,
  "low": 3018.76,
  "points": [
    { "timestamp": 1774473600000, "price": 3022.55 },
    { "timestamp": 1774473720000, "price": 3023.10 }
  ]
}

Notes:

• points includes all stored points exactly matching the resolved NY trading session.
• previousClose is taken from the previous daily candle close when available.
• If no previous daily candle exists, it falls back to the latest realtime point before the active session.

OHLC response example (3m, 6m, ytd, 1y, 2y, 5y, 10y):

[
  { "date": "2026-02-12", "open": 3050.1, "high": 3080.5, "low": 3040.0, "close": 3070.2 },
  { "date": "2026-02-13", "open": 3071.0, "high": 3095.0, "low": 3060.0, "close": 3088.5 }
]

Realtime WebSocket

WS /ws/realtime

Mobile clients connect to this endpoint and then send a subscribe message. The server opens and maintains a Twelve Data WS connection only while subscribers exist.

Client subscribe message:

{ "action": "subscribe", "symbol": "XAU/USD" }

Server price message example:

{
  "type": "price",
  "symbol": "XAU/USD",
  "price": 3150.42,
  "timestamp": 1741651200000,
  "source": "twelvedata-ws"
}

Notes:

• Current implementation supports XAU/USD only.
• If no subscribers remain, server closes the upstream Twelve Data WS connection after a short grace period.

Private Endpoints

All endpoints below require header:

x-api-key: your_private_scheduler_key

Returns 401 if the key is missing or invalid.

POST /api/internal/gold/fetch

Realtime fetch endpoint for 2-minute scheduler.

POST /api/internal/gold/fetch-daily

Fetches missing daily candles (smart incremental).

POST /api/internal/gold/fetch-weekly

Fetches missing weekly candles (smart incremental).

POST /api/internal/gold/fetch-monthly

Fetches missing monthly candles (smart incremental).

POST /api/internal/gold/backfill

Backfills older history in 5000-candle chunks.

Request body:

{ "interval": "daily" }

interval must be one of: daily, weekly, monthly.

Response example:

{ "done": false, "stored": 5000, "oldestDate": "2012-03-14" }

When no more historical candles are returned:

{ "done": true, "stored": 0, "oldestDate": "1969-12-31" }

Scheduler Cron Examples (MYT)

Set scheduler timezone to Asia/Kuala_Lumpur.

Cron format:

minute hour day-of-month month day-of-week

Frequency	Cron (MYT)	Endpoint
Realtime market session (Mon 06:00-Mon 23:59)	*/2 6-23 * * 1	POST /api/internal/gold/fetch
Realtime market session (Tue-Fri full day)	*/2 * * * 2-5	POST /api/internal/gold/fetch
Realtime market session (Sat 00:00-Sat 05:59)	*/2 0-5 * * 6	POST /api/internal/gold/fetch
Daily history (Tue-Sat 07:10)	10 7 * * 2-6	POST /api/internal/gold/fetch-daily
Weekly history (Monday 08:15)	15 8 * * 1	POST /api/internal/gold/fetch-weekly
Monthly history (day 1, 08:20)	20 8 1 * *	POST /api/internal/gold/fetch-monthly

Backfill Suggestion

Run each backfill endpoint repeatedly until done: true:

• Daily interval: likely multiple calls for deep history
• Weekly interval: usually one call is enough
• Monthly interval: usually one call is enough

Project Structure

src/
  index.ts
  app.ts
  config/
    index.ts
  db/
    firestore.ts
  middleware/
    privateAuth.ts
  routes/
    index.ts
    gold.routes.ts
    internal/
      index.ts
      gold.routes.ts
  services/
    gold.service.ts
    gold.history.service.ts
  types/
    gold.types.ts

Tech Stack

• Node.js
• TypeScript
• Express
• Axios
• Firebase Admin SDK (Firestore)
• dotenv