Precious Metals Price Query
Zero-configuration precious metals price lookup covering all four major metals
across international futures and Chinese domestic markets.
No API key, no registration, no local plugins — works everywhere.
Quick Start
# Query all metals (JSON output)
python3 scripts/query.py
# Query specific metal
python3 scripts/query.py --metal gold
# Human-readable table output
python3 scripts/query.py --format table
# Query Chinese domestic retail prices only
python3 scripts/query.py --market cn
Interface Contract
Any IDE, agent, or automation tool can invoke this skill:
python3 scripts/query.py [--metal {all,gold,silver,platinum,palladium}] [--format {json,table}] [--market {all,intl,cn}]
- Input: CLI arguments (all optional, defaults to all metals, JSON output)
- Output: JSON to stdout (exit code 0) or markdown table
- Error handling: Exit code 1 with JSON
{"error": "message"}on failure - Idempotent: Same query returns consistent results (cached per minute)
JSON Output Schema
{
"timestamp": "2026-06-03T11:12:20+08:00",
"markets": {
"international": {
"gold": { "symbol": "GC", "latest": 4513.7, "open": 4520.0, "high": 4525.1, "low": 4490.5, "unit": "USD/oz", "exchange": "COMEX" },
"silver": { "symbol": "SI", "latest": 75.36, "open": 75.50, "high": 75.63, "low": 74.11, "unit": "USD/oz", "exchange": "COMEX" },
"platinum": { "symbol": "XPT", "latest": 1937.4, "open": 1941.0, "high": 1946.4, "low": 1923.8, "unit": "USD/oz", "exchange": "NYMEX" },
"palladium": { "symbol": "XPD", "latest": 1395.0, "open": 1394.5, "high": 1395.5, "low": 1384.0, "unit": "USD/oz", "exchange": "NYMEX" }
},
"shanghai_futures": {
"gold": { "symbol": "AU0", "latest": 986.48, "high": 988.20, "low": 976.00, "prev_settle": 979.76, "unit": "CNY/g", "exchange": "SHFE" },
"silver": { "symbol": "AG0", "latest": 18375, "high": 18484, "low": 17933, "prev_settle": 18159, "unit": "CNY/kg", "exchange": "SHFE" }
},
"domestic_retail": {
"gold_bank_bars": [
{ "bank": "工商银行如意金条", "price": 998.68, "unit": "CNY/g" }
],
"gold_recycle": { "price": 961.0, "unit": "CNY/g" },
"palladium_recycle": { "price": 277.0, "unit": "CNY/g" }
}
},
"data_sources": ["sina_finance", "xxapi.cn"],
"note": "International futures: real-time during US/Asia electronic hours. Shanghai futures: real-time 09:00-15:00 CST. Retail prices: updated daily."
}
Architecture
┌──────────────────────────────────────────────────────────┐
│ query.py (entry point) │
│ python3 scripts/query.py --metal all --format json │
└──────┬──────────────────────────┬────────────────────────┘
│ │
▼ ▼
┌──────────────┐ ┌──────────────────┐
│ Sina Finance │ │ xxapi.cn │
│ (hq.sinajs) │ │ (v2.xxapi.cn) │
├──────────────┤ ├──────────────────┤
│ hf_GC COMEX │ │ bank_gold_bar │
│ hf_SI COMEX │ │ gold_recycle │
│ hf_XPT NYMEX │ │ pd_recycle │
│ hf_XPD NYMEX │ │ ag_recycle │
│ nf_AU0 SHFE │ └──────────────────┘
│ nf_AG0 SHFE │ Zero auth
└──────────────┘
Zero auth
Data Sources
| Source | Coverage | Auth | Update | Reliability |
|---|---|---|---|---|
| Sina Finance | COMEX GC/SI, NYMEX XPT/XPD, SHFE AU/AG | None | Real-time | High (backed by exchange data) |
| xxapi.cn | Domestic bank bars, brand retail, recycle prices | None | Daily | Medium (aggregator, not primary) |
Limitations
- No SGE spot (AU9999) real-time: SHFE futures (nf_AU0) is the closest proxy. SGE direct data requires commercial API access.
- International futures during Asian hours: Electronic (Globex) session, lower volume than US pit session. Prices are valid but spreads may be wider.
- Platinum/Palladium domestic retail: xxapi.cn covers brand retail prices; SGE Pt99.95 real-time not available via free APIs.
- Free-tier rate limits: Sina Finance has no documented rate limit for moderate use. xxapi.cn has no published limit. Avoid sub-second polling.
Integration Examples
From any shell script
PRICE=$(python3 precious-metals/scripts/query.py --metal gold | python3 -c "import sys,json; print(json.load(sys.stdin)['markets']['international']['gold']['latest'])")
echo "COMEX Gold: $PRICE USD/oz"
From Python code
import subprocess, json
result = subprocess.run(
["python3", "scripts/query.py", "--metal", "all", "--format", "json"],
capture_output=True, text=True, cwd="precious-metals"
)
data = json.loads(result.stdout)
gold = data["markets"]["international"]["gold"]
print(f"{gold['symbol']}: {gold['latest']} {gold['unit']}")
From AI agent / LLM tool call
Tool: bash
Command: python3 /path/to/precious-metals/scripts/query.py --metal all --format json
→ Parse JSON response → Present to user
Reference
Detailed API documentation: references/api-reference.md
