Get Hong Kong Dollar (HKD) - N/A prices using this API for real-time quotes

Metals-API 8 min read
Get Hong Kong Dollar (HKD) - N/A prices using this API for real-time quotes

You need a reliable, programmatic way to fetch the live Hong Kong Dollar (HKD) quote so your app can price products, convert balances, or trigger trading logic in real time. In this tutorial you’ll integrate Metals-API’s /latest endpoint to pull the HKD rate, parse the response correctly, invert the quote when needed, and wire it into two common workflows: instant repricing and threshold alerts.

What the HKD quote represents and who uses it

HKD is the currency code for the Hong Kong Dollar. Teams building trading tools, cross-border e-commerce, treasury dashboards, and manufacturing ERP systems use a live HKD quote to convert prices, compare supplier costs, and keep UIs in sync with market moves. Metals-API delivers currencies alongside metals in the same JSON, which lets you unify pricing logic across spot metals and fiat conversions without switching data sources.

Illustration: Get Hong Kong Dollar (HKD) - N/A prices using this API for real-time quotes

If you’re unsure about symbol correctness or want to see additional codes you can request with HKD, check the always-current listing at Metals-API Supported Symbols.

Fetch the live HKD quote with the /latest endpoint

The /latest endpoint returns the current rate snapshot. By default, rates are quoted relative to USD (the base). You’ll request HKD specifically with the symbols parameter. The API returns a timestamp and a normalized rate you can use immediately.

cURL request

curl "https://metals-api.com/api/latest?access_key=YOUR_API_KEY&base=USD&symbols=HKD"

Replace YOUR_API_KEY with your key. If you don’t have one yet, you can get it here: Register.

Python example

import os
import requests
from decimal import Decimal, ROUND_HALF_UP

API_KEY = os.getenv("METALS_API_KEY", "YOUR_API_KEY")
url = "https://metals-api.com/api/latest"
params = {
"access_key": API_KEY,
"base": "USD",
"symbols": "HKD"
}

r = requests.get(url, params=params, timeout=10)
r.raise_for_status()
data = r.json()

# Extract essentials
if not data.get("success", False):
raise RuntimeError(f"API error: {data}")

timestamp = data.get("timestamp") # UNIX seconds
date_str = data.get("date") # YYYY-MM-DD
base = data.get("base") # 'USD'
rates = data.get("rates", {})
hkd_per_usd = Decimal(str(rates.get("HKD"))) # e.g., 7.84... HKD per 1 USD

# If you need USD per 1 HKD (the inverse), compute it
usd_per_hkd = (Decimal("1") / hkd_per_usd).quantize(Decimal("0.0000001"), rounding=ROUND_HALF_UP)

print({
"timestamp": timestamp,
"date": date_str,
"base": base,
"HKD_per_USD": str(hkd_per_usd),
"USD_per_HKD": str(usd_per_hkd)
})

Read the response correctly

Here is a real response example for this request. Your numbers will vary with market conditions, but the field structure is stable.

{"success":true,"timestamp":1791936540,"date":"2026-10-14","base":"USD","rates":{"HKD":7.8481933333333,"USD":1,"USDHKD":0.12741786007650222}}

Fields you’ll actually use:

  • success: Boolean status flag. Check this before using rates.
  • timestamp: UNIX seconds since epoch. Convert to your app’s timezone if displaying in UI. Store it to decide when to refresh.
  • date: The calendar date of the snapshot (YYYY-MM-DD).
  • base: The currency that other rates are quoted against. Here it’s USD.
  • rates.HKD: The primary number you’ll use. It’s HKD per 1 USD (HKD/USD). In the example, 1 USD equals 7.8481933333333 HKD.
  • rates.USD: Always 1 when base is USD. Handy sanity check.
  • rates.USDHKD: An additional convenience value in this payload. Use rates.HKD as your canonical “HKD per USD” quote; use USDHKD only if your logic prefers that naming.

Inverting the quote:

  • If you need USD per 1 HKD, compute 1 / rates.HKD. Using the sample above, USD/HKD ≈ 1 / 7.8481933333333 ≈ 0.12741786.
  • If your business logic stores prices in HKD and needs USD quickly, multiply an HKD amount by USD/HKD.

Two practical uses wired to specific fields

1) Repricing a multi-currency catalog on the fly

Problem: Your ERP stores base prices in USD but needs to display HKD to Hong Kong customers and partners. You want consistent, rounded retail prices without over-refreshing.

What you’ll read from the response:

  • rates.HKD to convert USD → HKD.
  • timestamp to decide whether you can reuse a cached rate.
  • date for reporting/analytics logs.

Implementation sketch:

  • Each pricing function reads the latest cached HKD per USD. If cache is stale (see refresh section below), call /latest again.
  • hk_price = usd_price × rates.HKD. Apply your retail rounding rules and display formatting.
  • Store timestamp alongside the rate used for auditability, especially if your invoices must prove the conversion basis.

2) A threshold alert when HKD strengthens or weakens

Problem: Your treasury team wants a push notification when the USD/HKD ratio crosses a threshold to time conversions or hedges.

What you’ll read from the response:

  • rates.HKD as HKD per USD. For a USD/HKD threshold, invert: usd_per_hkd = 1 / rates.HKD.
  • timestamp to avoid duplicate alerts from the same snapshot.

Implementation sketch:

  • Poll /latest on your chosen cadence. Keep the last notified state keyed by date and a hash of (threshold, direction).
  • Compute inverted USD per HKD if your alerts track USD/HKD. Compare to thresholds. Trigger alert if a strict inequality is met and the snapshot is new (timestamp has advanced).
  • Debounce by enforcing a minimum time gap between alerts or a minimum percentage move since the last alert.

Units, base, and conversion notes (save yourself debugging time)

  • Base currency: Unless you override base, rates are relative to USD. In the sample call we explicitly used base=USD.
  • HKD rate meaning: rates.HKD is the number of HKD per 1 USD. This is not a percentage. Multiply USD amounts by this rate to get HKD.
  • Inversion: To get USD per HKD, compute 1 / rates.HKD. Use sufficient precision when inverting; Decimal or big.js-style libraries are recommended.
  • Timestamps: timestamp is UNIX seconds. Treat it as UTC when converting to human time for logs and alerts.
  • Metals vs currencies: Metals endpoints often return units “per troy ounce.” Currency quotes like HKD are unitless ratios against the base; there is no “per ounce” for fiat.

Caching and refresh frequency

To avoid unnecessary calls and stay within your operational constraints, add a thin caching layer around /latest:

  • Cache key: (endpoint=/latest, base=USD, symbols=HKD).
  • Staleness: Respect the snapshot’s timestamp and your plan’s refresh cadence. Metals-API updates latest quotes in plan-specific intervals; only refresh when you need a new snapshot. See the Documentation for endpoint behavior.
  • Expiry: Many apps use a time-based TTL aligned to their UI expectations (e.g., 1–10 minutes). The simplest policy: if cached.timestamp equals the new response’s timestamp, keep the cache; if it advances, update it.
  • Fallback: If a fresh call fails briefly, reuse the last good cached rate and surface a degraded-mode flag to your UI or logs.

Validation and symbol hygiene

Use the official symbols index to ensure you request valid codes and reduce 4XX errors. You’ll find HKD (and all supported metals and currencies) at Metals-API Supported Symbols. If you need to expand your integration to historical queries or more advanced endpoints, consult the Metals-API Documentation.

Going further: conversions, historicals, and method notes

If your workflow needs to convert arbitrary amounts or backtest strategies, Metals-API also provides a conversion endpoint and historical/time-series endpoints you can call with HKD. For full parameter lists and examples, see the Documentation. For methodology and market coverage notes, review MCP.

Operational nuances: weekends, closures, and reliability

  • Market hours: FX liquidity varies by time and venue. Over weekends or holidays, snapshots may change less frequently. Use timestamp to confirm whether you have a new tick.
  • Idempotency: /latest is read-only and safe to call multiple times. Implement simple backoff on transient network errors.
  • Precision: Store rates as strings or high-precision decimals to prevent rounding drift, especially when inverting multiple times.
  • Observability: Log access_key usage context, base, symbols, timestamp, and top-line rates. This is often enough to debug price discrepancies later.

Why developers pair currencies and metals in one feed

Metals-API is used not only for currency conversion but also for pricing precious and industrial metals. If your product quotes jewelry, components, or hedges metal exposure in HKD, a single feed that includes both metals and HKD cuts integration complexity. You can request both in the same /latest call by including multiple symbols and still normalize everything to the same base. Explore the catalog at Metals-API Supported Symbols.

Reference links and context

  • Register for an API key to start calling /latest.
  • Read the Documentation for endpoint parameters, update frequency, and usage notes.
  • Confirm available symbols at the Symbols page.
  • Methodology and coverage overview: MCP.
  • Contextual market sources you might cross-check during integration:
    • Hong Kong Monetary Authority exchange rate resources: HKMA
    • Spot HKD quote pages on terminals/data sites, e.g., Bloomberg USD/HKD (for visual validation only)

FAQ

  • Which symbol should I request for the Hong Kong Dollar?
    Use HKD. Confirm it on the Symbols page.
  • How do I get USD per 1 HKD instead of HKD per 1 USD?
    The API returns rates relative to the base (USD here). Compute USD/HKD as 1 / rates.HKD. Keep enough decimal precision to avoid drift.
  • How often does the /latest rate update?
    Update cadence depends on your plan and market conditions. Use the response timestamp to detect new snapshots. See the Documentation for details.
  • Why do I sometimes see both HKD and USDHKD in rates?
    Use rates.HKD as the canonical “HKD per USD” figure. If rates.USDHKD is present, treat it as an additional convenience value; you can always compute the inverse as 1 / rates.HKD.
  • What happens on weekends or holidays?
    Snapshots may change less frequently. Always check timestamp to determine whether you’re seeing a new tick, and rely on your cache-with-expiry policy if markets are quiet.

Ready to ship this? Get your key in minutes and wire the HKD quote into your app today: Register. If you need deeper features—like time series for backtesting or OHLC—browse the Documentation and verify codes on Symbols.