Free Gold Price API: XAU, JSON & Python

For XAU/USD, start with Gold Price Aggregation. The October 21, 2026 end-to-end test returned HTTP 200 and success=true, with price, bid and ask in USD per troy ounce. The request examples below use that exact tool.

• Free means trial access. QVeris currently lists 1,000 one-time signup trial credits after verification. Each of the two tested calls recorded 1 credit; settlement was still pending at response time.
• Region changes the setup. The international test used the aggregation tool; the China test used a different MetalpriceAPI tool and endpoint.
• Latest does not prove real time. The two returned data timestamps differed by 8 hours, 45 minutes, 5 seconds. Neither call establishes an update-frequency guarantee.

All test times on this page are Beijing time (UTC+08:00). These are dated test observations, not a live price feed. Catalog verification remains unverified. See current trial and billing terms.

Gold Price Aggregation is the international-region starting point. Use the tool page to inspect its inputs and current billing rule, then obtain a Token for the same region before calling the API.

Recommended path: this guide → exact tool details → matching-region Token → one request. Use general tool search when you need a different capability, and the Call API documentation for the execution contract.

Configure your international-region Token as the environment variable QVERIS_API_KEY in your local terminal or server. The examples contain no credentials. The cURL and Python snippets are alternatives: each execution sends one billable request.

cURL: one XAU/USD request

: "${QVERIS_API_KEY:?Set the matching region Token in QVERIS_API_KEY first}"
curl --fail-with-body --silent --show-error --max-time 30 \
  --request POST "https://qveris.ai/api/v1/tools/execute" \
  --header "Authorization: Bearer $QVERIS_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
  "tool_id": "qveris_finance.gold_price_aggregation_v1",
  "parameters": {
    "symbol": "XAU",
    "quote": "USD",
    "limit": 1
  }
}'

Python 3: request and print the returned JSON

Uses only the Python standard library. Save as gold_price.py and run python3 gold_price.py after configuring the environment variable.

import json
import os
import urllib.error
import urllib.request

token = os.environ.get("QVERIS_API_KEY")
if not token:
    raise SystemExit("Set QVERIS_API_KEY to your international-region Token.")

payload = {
    "tool_id": "qveris_finance.gold_price_aggregation_v1",
    "parameters": {"symbol": "XAU", "quote": "USD", "limit": 1},
}
request = urllib.request.Request(
    "https://qveris.ai/api/v1/tools/execute",
    data=json.dumps(payload).encode("utf-8"),
    headers={
        "Authorization": f"Bearer {token}",
        "Content-Type": "application/json",
    },
    method="POST",
)
try:
    with urllib.request.urlopen(request, timeout=30) as response:
        result = json.load(response)
except urllib.error.HTTPError as exc:
    raise SystemExit(f"HTTP {exc.code}: check the region, credits and parameters.") from exc
except (urllib.error.URLError, TimeoutError) as exc:
    raise SystemExit("Network failure or timeout. Check Usage before retrying.") from exc

if not isinstance(result, dict) or result.get("success") is not True:
    raise SystemExit("Tool execution did not succeed; inspect the response before retrying.")
print(json.dumps(result, ensure_ascii=False, indent=2))

The Python example checks HTTP errors and the API’s success flag, then prints the real response without assuming a nested price-field path. Neither example automatically retries. A timeout can leave the execution outcome uncertain; check Usage before submitting another call. For application retries, respect 429 responses and the documented execution contract.

The international test returned price = ask = 4,122.22 and bid = 4,121.72, in USD per troy ounce. The data time was October 21, 2026 at 16:45:04 Beijing time, with commodity_price_api as the source.

{
  "tool_id": "qveris_finance.gold_price_aggregation_v1",
  "observed_fields": {
    "price": 4122.22,
    "ask": 4122.22,
    "bid": 4121.72
  },
  "currency": "USD",
  "unit": "troy_ounce",
  "source": "commodity_price_api",
  "data_time_beijing": "2026-10-21T16:45:04+08:00"
}

Store the raw response as well as your normalized values. Preserve source, currency, unit and timezone, and flag missing or stale data before displaying it as a current quote.

Authentication, search and one data call succeeded in each region in the supplied test record. Tool availability must still be checked separately: an ID lookup in China did not return the international gold aggregation tool.

China-region cURL example

Use a China-region Token in QVERIS_CN_API_KEY. The MetalpriceAPI tool details page is on the international website; the tested China API endpoint remains https://api.qveris.cn/api/v1/tools/execute.

: "${QVERIS_CN_API_KEY:?Set the matching region Token in QVERIS_CN_API_KEY first}"
curl --fail-with-body --silent --show-error --max-time 30 \
  --request POST "https://api.qveris.cn/api/v1/tools/execute" \
  --header "Authorization: Bearer $QVERIS_CN_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
  "tool_id": "metalpriceapi.latest.retrieve.v1.f8ea59a7",
  "parameters": {
    "base": "USD",
    "currencies": "XAU"
  }
}'

Read USDXAU and XAU in the correct direction

{
  "USDXAU": 4137.5007344064,
  "XAU": 0.0002416918
}

With base=USD, XAU=0.0002416918 is the amount of gold per US dollar, while USDXAU=4137.5007344064 is the reciprocal dollar price per troy ounce. 1 / 0.0002416918 ≈ 4137.5007344064. Never label 0.0002416918 as the USD gold price. See the MetalpriceAPI unit and rate documentation.

This call did not verify CNY per gram, Shanghai gold, jewelry retail prices or historical data. The international catalog also listed commodity_price_api direct access and an NBP today-gold-price tool; neither was executed in this test, so neither is presented here as tested.

As checked on October 21, 2026, the international QVeris pricing page lists 1,000 one-time trial credits after signup verification. Discover and Inspect are free; execution follows the selected tool’s billing rule. The trial is not an unlimited or permanently free gold-price feed. China-region eligibility and offers must be checked in that region’s account.

Both public tool detail pages displayed 1 credit per call when checked. The two successful test calls each recorded 1 credit, but settlement was still pending when the responses arrived. These are observed pre-settlement records, not a claim that final charges have been reconciled.

After trial credits are used, further billable calls require sufficient credits under the account’s current plan or top-up terms. Check the tool rule before execution and Usage or the credits ledger afterward for final settlement. Retries, extra tools and external AI-client fees can add cost.

Is a free live gold price API actually live?

Both calls returned a latest-price result, but the tests did not establish either tool’s refresh interval, maximum delay or market-hours behavior. Check the source timestamp on each response. The catalog’s “Updated” or “Freshness” timestamp describes the catalog entry, not necessarily the gold observation. MetalpriceAPI documents plan-dependent delay; that alone does not identify the upstream plan behind the tested QVeris call. Read the provider documentation.

Can I get free historical gold prices by API?

Historical gold data was not tested. The latest-price request on this page does not establish historical coverage. For a historical workflow, inspect a suitable tool, then verify date range, daily or intraday granularity, gaps, revisions, price methodology, units and cost with a separate test.

Does XAU/USD give me CNY per gram or a local retail price?

No such capability was verified here. A currency or weight conversion is a calculation, not evidence of a Shanghai-market quote or a jewelry store’s retail price. Spot, benchmark, futures and retail datasets have different meanings. The World Gold Council gold-price reference and LBMA Gold Price information help distinguish price methodologies; they are not additional tested QVeris endpoints.

Keep the initial acceptance task small: inspect the tool, run one request, validate the JSON, retain its timestamp and review the final usage record. A successful call is one piece of evidence, not a reliability or licensing guarantee.

Updated October 21, 2026. The two-region execution results above come from the supplied end-to-end test record: successful authentication and discovery, then one actual query in each region. This page revision rechecked the public guide, tool details, pricing and call documentation; it did not repeat paid data calls. No Tokens are included.

Both tool detail URLs returned HTTP 200 with matching titles and tool IDs. Their catalog status remained unverified. A single successful query does not establish continuous availability, formal certification or commercial redistribution rights. The test record does not include complete raw responses or a final settlement audit.

The retained whiteboard illustration is a selection workflow, including checks for live and historical needs; it is not evidence that every pictured capability was tested.