Skip to content
Bullion API

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.

Plain text
4100.00 USD per troy_oz
Observed 2026-11-05 14:00 UTC

Keep 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.

YAML
# secrets.yaml
bullion_api_key: bullion_YOUR_API_KEY

Do 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:

GEThttps://bullionapi.dev/v1/gold/price?currency=USD&unit=troy_ozShell
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.

YAML
# 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
  1. Run Developer tools, then YAML, then Check configuration. Fix any error it reports before you continue.
  2. 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_1d and sensor.bullion_gold_18k_per_gram.
  3. 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.

YAML
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.

YAML
type: history-graph
title: Gold, last 7 days
hours_to_show: 168
entities:
  - entity: sensor.bullion_gold_price

Notify 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.

YAML
# 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

JSON
{
  "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

JSON
{
  "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

JSON
{
  "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.

Common API errors and what to check
StatusMessageWhat to check
401Missing API keyThe headers block has no X-API-Key line, or its indentation is wrong.
401Invalid or revoked API keyCopy the key again from your dashboard. Check that the !secret name matches the name in secrets.yaml.
403Your 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.
404The requested API path was not found.Check the URL, including the metal name and the path.
404No stored price for one or both requested dates.Wait for the next refresh. The price sensor still works.
429Rate limit exceededToo many requests in a short time. Keep scan_interval at 3600 and do not reload the sensors repeatedly.
429Your 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.