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

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