Bullion API metal prices in Home Assistant
Add gold price sensors with the RESTful sensor, show them on a dashboard and get a notification when the price crosses a level. Prices refresh hourly on weekdays, each with its observation time.
Prices refresh hourly on weekdays. The sensors poll every hour, and a second sensor holds the observation time, so the dashboard can show how old the price is.
Home Assistant is a home automation tool. This guide is for dashboards and notifications, not for billing, trading or accounting. It needs Home Assistant 2024.10 or later for the automation syntax.
What the dashboard card shows
Synthetic example. The card reads the sensor's price and unit and the observed sensor's time.
4100.00 USD per troy_oz
Observed 2026-11-05 14:00 UTCKeep the key in secrets.yaml
Create an API key in your dashboard. Add it to secrets.yaml in your Home Assistant configuration folder. The sensors read it with !secret and send it in the X-API-Key header, so the key never appears in configuration.yaml.
# secrets.yaml
bullion_api_key: bullion_YOUR_API_KEYDo not paste the key into a dashboard card, a template, a screenshot, a shared backup or a forum post. If it leaks, revoke it in your dashboard and put a new key in secrets.yaml. Test a key from a terminal before you use it in Home Assistant:
export BULLION_KEY=bullion_YOUR_API_KEY
curl "https://bullionapi.dev/v1/gold/price?currency=USD&unit=troy_oz" \
-H "X-API-Key: $BULLION_KEY"Add the sensors
Add this to configuration.yaml. It makes four sensors from three URLs: the gold price and its observation time, the one-day change, and the 18 karat price per gram. Drop any URL you do not need, because each one is a request every hour.
# configuration.yaml
rest:
- resource: https://bullionapi.dev/v1/gold/price?currency=USD&unit=troy_oz
scan_interval: 3600
headers:
X-API-Key: !secret bullion_api_key
sensor:
- name: Bullion gold price
unique_id: bullion_gold_price_usd_troy_oz
unit_of_measurement: USD/oz
value_template: "{{ value_json.series[0].observations[0].value | float | round(2) }}"
json_attributes_path: "$"
json_attributes:
- metal
- currency
- unit
- series
- name: Bullion gold price observed
unique_id: bullion_gold_price_observed
device_class: timestamp
value_template: "{{ value_json.series[0].observations[0].date }}"
- resource: https://bullionapi.dev/v1/gold/change?currency=USD&unit=troy_oz&period=1d
scan_interval: 3600
headers:
X-API-Key: !secret bullion_api_key
sensor:
- name: Bullion gold change 1d
unique_id: bullion_gold_change_1d_usd_troy_oz
unit_of_measurement: "%"
value_template: "{{ value_json.change_percent | float | round(2) }}"
json_attributes:
- change
- change_percent
- start
- end
- resource: https://bullionapi.dev/v1/gold/carat?currency=USD
scan_interval: 3600
headers:
X-API-Key: !secret bullion_api_key
sensor:
- name: Bullion gold 18k per gram
unique_id: bullion_gold_18k_usd_gram
unit_of_measurement: USD/g
value_template: "{{ value_json.karats['18k'] | float | round(2) }}"
json_attributes:
- currency
- unit
- as_of
- karats- Run Developer tools, then YAML, then Check configuration. Fix any error it reports before you continue.
- On the same page, choose Reload REST entities, or restart Home Assistant. The sensors are
sensor.bullion_gold_price,sensor.bullion_gold_price_observed,sensor.bullion_gold_change_1dandsensor.bullion_gold_18k_per_gram. - Open the price sensor in Developer tools, then States. Its attributes hold the metal, the currency, the unit and the full response series, with the price as a decimal string.
To change the metal, currency or unit, change the URL and the name, unique_id and unit_of_measurement lines together. The carat endpoint prices gold per gram in a currency, so it has no unit option.
Why the sensor state is a number
Home Assistant draws history graphs only for numeric states. So the state of each price sensor is a number rounded to two decimals, made with float and round(2) in the value_template. These templates are the only place the guide uses float: Home Assistant templates have no decimal type, and the dashboard card and the notification use it only to show two decimals.
The API's own value stays a decimal string in the series attribute, and any calculation that matters should start from that string, not from the state. The sensors are for display. Do not use them as a source for billing, trading or accounting.
Show it on a dashboard
Add a Markdown card. It formats the state to two decimals for display, and it shows the price with its observation time. If the sensor has no price, it says so instead of showing zero.
type: markdown
title: Gold
content: >-
{% set price = states('sensor.bullion_gold_price') %}
{% if is_number(price) %}
## {{ '%.2f' | format(price | float) }} {{ state_attr('sensor.bullion_gold_price', 'currency') }}
per {{ state_attr('sensor.bullion_gold_price', 'unit') }}
Observed {{ as_timestamp(states('sensor.bullion_gold_price_observed')) | timestamp_custom('%Y-%m-%d %H:%M', false) }} UTC
{% else %}
Price unavailable. Check the log.
{% endif %}Add a history graph card to see the price over time. This is the reason the state is numeric.
type: history-graph
title: Gold, last 7 days
hours_to_show: 168
entities:
- entity: sensor.bullion_gold_priceNotify when the price crosses a level
This automation sends a notification when the gold price rises above 4,200 USD. A numeric_state trigger fires when the price crosses the level, not on every poll above it, so it fires again after the price has fallen back below and then crossed again. It also fires again if the sensor becomes unavailable and returns while the price is above the level, which a failed request, a reload of the REST entities or a restart of Home Assistant causes. Change notify.notify to your own notify service.
# automations.yaml
- alias: Gold above 4,200 USD
triggers:
- trigger: numeric_state
entity_id: sensor.bullion_gold_price
above: 4200
actions:
- action: notify.notify
data:
title: Gold price alert
message: >-
Gold is {{ '%.2f' | format(trigger.to_state.state | float) }}
{{ state_attr('sensor.bullion_gold_price', 'currency') }} per
{{ state_attr('sensor.bullion_gold_price', 'unit') }}. Observed
{{ states('sensor.bullion_gold_price_observed') }}.The level is a number you choose, so it is a plain number in the YAML. The message shows the price to two decimals with the observation time of the price that crossed.
How fresh the prices are
Prices refresh hourly on weekdays. No refresh runs at 22:00 UTC on weekdays or at 23:00 UTC on Friday. Home Assistant polls every hour, weekends included, so polls at those times, and all weekend polls, return the last stored price with its earlier observation time. At the weekend the observed sensor shows Friday's time.
The scan_interval is 3600 seconds, one hour. A shorter interval only repeats the same stored price and uses more of your allowance.
What the API sends back
The templates read these responses. Every price is a decimal string, and the price series date is the UTC time of the observation. The change endpoint compares the final price of two UTC days, and change_percent is a percentage, so 0.452 means 0.452%.
Price
{
"status": "success",
"metric": "price",
"metal": "gold",
"currency": "USD",
"unit": "troy_oz",
"start": null,
"end": null,
"series": [
{
"id": "gold_price",
"label": "Gold spot price",
"unit": "troy_oz",
"frequency": "hourly",
"method": "latest",
"observations": [{ "date": "2026-11-05T14:00:00.000Z", "value": "4100" }]
}
]
}Change over one day
{
"status": "success",
"metric": "change",
"metal": "gold",
"currency": "USD",
"unit": "troy_oz",
"start": { "date": "2026-11-04", "value": "4081.55" },
"end": { "date": "2026-11-05", "value": "4100" },
"change": "18.45",
"change_percent": "0.452"
}Karat prices per gram
{
"status": "success",
"currency": "USD",
"unit": "gram",
"as_of": "2026-11-05T14:00:00.000Z",
"karats": {
"24k": "131.81806093",
"23k": "126.32564173",
"22k": "120.83322252",
"21.6k": "118.63625484",
"21k": "115.34080331",
"18k": "98.86354570",
"16k": "87.87870729",
"14k": "76.89386888",
"12k": "65.90903047",
"10k": "54.92419205",
"9k": "49.43177285",
"8k": "43.93935364",
"6k": "32.95451523"
}
}The samples use synthetic values. The three requests were run against a local build of the API with a test key, and the templates were rendered against what it returned. The YAML was parsed, but not run in Home Assistant itself, whose option names can change between releases. If one differs, check Home Assistant's RESTful documentation.
Errors you may see
When the API answers with an error, the response has no price for the templates to read, so the sensor does not update. Check Settings, System, then Logs, and the status below. A carat or change sensor can fail while the price sensor works.
| Status | Message | What to check |
|---|---|---|
| 401 | Missing API key | The headers block has no X-API-Key line, or its indentation is wrong. |
| 401 | Invalid or revoked API key | Copy the key again from your dashboard. Check that the !secret name matches the name in secrets.yaml. |
| 403 | Your free trial has ended. Choose a plan at https://bullionapi.dev/pricing to keep using the API. | Choose a paid plan. The sensors recover on their next poll. |
| 404 | The requested API path was not found. | Check the URL, including the metal name and the path. |
| 404 | No stored price for one or both requested dates. | Wait for the next refresh. The price sensor still works. |
| 429 | Rate limit exceeded | Too many requests in a short time. Keep scan_interval at 3600 and do not reload the sensors repeatedly. |
| 429 | Your monthly usage limit has been reached. Please upgrade your subscription plan. | Your plan has used its monthly requests. Remove a URL or choose a larger plan. |
For every endpoint and parameter, see the API reference. For a workflow tool instead, see n8n or Zapier.