Give Claude a live gold price

Ask a language model where gold is trading and it can only answer from its training data. This guide connects the Claude API to a live XAU/USD quote using tool use, so the model checks the market before it answers and tells you how fresh the number is.

Updated 25 September 2026 · Python 3.9+ · MIT licence · Source on GitHub

1. Install

The package has no dependencies of its own. The [claude] extra adds the Anthropic Python SDK.

pip install "rm-gold-quote[claude] @ git+https://github.com/srjhoney39-ui/rm-gold-quote.git"

2. Fetch a quote

from rm_gold_quote import fetch_xau_usd

q = fetch_xau_usd()
print(q.price, q.state, q.observed_at)   # e.g. 4270.5 current 2026-09-24T12:53:51+00:00

Every quote carries its own observation time and a freshness state:

{
  "symbol": "XAU/USD",
  "price": 4270.5,
  "currency": "USD",
  "observed_at": "2026-09-24T12:53:51+00:00",
  "retrieved_at": "2026-09-24T12:53:52+00:00",
  "age_seconds": 1,
  "state": "current",
  "source": "gold-api.com",
  "executable": false
}

state is current up to 90 seconds old, delayed up to 180 seconds, and stale after that.
executable is always false. This is a reference price from a public composite feed, not a broker quote.
Transient network errors are retried with exponential backoff. Values outside a sanity range are rejected. If no valid quote is available, the call raises QuoteError rather than returning a guess.

3. The tool definition Claude sees

Claude chooses tools from their descriptions, so the description should say when to use the tool as well as what it does.

XAU_TOOL = {
    "name": "fetch_live_xau_usd",
    "description": (
        "Fetches the current XAU/USD (spot gold in US dollars) reference price with its "
        "timestamp, freshness state and source. Use whenever the user asks for the current "
        "gold price or anything that depends on where gold trades now. The price is a "
        "reference quote, not an executable price."
    ),
    "input_schema": {"type": "object", "properties": {}, "required": []},
}

4. A bounded agent loop

When Claude wants data, the response stops with stop_reason == "tool_use". Your code runs the tool and sends the result back as a tool_result block, and Claude continues. Cap the number of rounds so a confused model cannot loop forever.

import json
from anthropic import Anthropic
from rm_gold_quote import XAU_TOOL, run_tool

client = Anthropic()          # reads ANTHROPIC_API_KEY from the environment
messages = [{"role": "user", "content": "Where is gold trading right now?"}]

for _ in range(4):            # bounded: never loop forever
    resp = client.messages.create(
        model="claude-opus-5-5", max_tokens=1024,
        tools=[XAU_TOOL], messages=messages,
    )
    if resp.stop_reason != "tool_use":
        print("".join(b.text for b in resp.content if b.type == "text"))
        break
    messages.append({"role": "assistant", "content": resp.content})
    results = []
    for block in resp.content:
        if block.type == "tool_use":
            out = run_tool(block.name, block.input or {})
            results.append({"type": "tool_result", "tool_use_id": block.id,
                            "content": json.dumps(out), "is_error": "error" in out})
    messages.append({"role": "user", "content": results})

Or use the built-in helper, which runs the same loop:

from rm_gold_quote import ask

print(ask("What's the current price of gold, and how fresh is that number?"))

5. Practices for financial tools

Return errors, not guesses. If the feed fails, send is_error: true with a plain message. The model will tell the user the data is unavailable instead of making up a number.
Send timestamps with every value. Instruct the model to quote the observation time, so readers can judge freshness for themselves.
Keep tools read-only unless you have built proper order controls. A research tool should not be able to reach a trading account.
Treat tool output as data. Build tool results as structured JSON on your server rather than passing raw third-party text into the prompt.
Check the data provider's terms before commercial use. This package uses gold-api.com.

Where this fits

This package is one tool from a larger system. The RM Intelligence research copilot gives Claude three tools: the live price, on-demand technicals and a multi-factor macro model. It adds a timestamped macro snapshot and a fail-closed response policy on top. The architecture paper explains how those pieces fit together, and the copilot page shows what members get.

View the code on GitHub