Gold savings and fintech apps

A gold savings app turns a deposit into grams, holds a balance in grams and shows what that balance is worth. The price API supplies one number for all three: the gold price per gram in the user's currency. GET /v1/convert returns it with no key, takes the amount in the user's currency and answers in grams. The run below used Indonesian rupiah on 2 November 2026.

• /v1/convert takes the deposit in local currency and returns grams in one call. It supports the 35 currencies the karat endpoint takes.
• Store grams as a decimal string, never as a float. Store the quote timestamp with every ledger entry.
• The price API returns the market price. Your sell price, buyback price and fees are your own business rules. The /v1/physical endpoint on Basic and above shows what dealers charge and pay in some countries.

Convert a deposit to grams

curl "https://api.goldprice.dev/v1/convert?from=IDR&to=XAU&amount=500000&unit=gram"

The script below calls it and truncates to six decimal places. Truncating means the app never credits more gold than the deposit bought.

import jsonfrom decimal import Decimal, ROUND_DOWNfrom urllib.request import urlopenAPI = "https://api.goldprice.dev"def grams_for(idr: str) -> dict:    with urlopen(f"{API}/v1/convert?from=IDR&to=XAU&amount={idr}&unit=gram", timeout=10) as r:        q = json.load(r)    grams = Decimal(q["result"]).quantize(Decimal("0.000001"), rounding=ROUND_DOWN)    return {"idr": idr, "grams": str(grams), "quoted_at": q["timestamp"]}print(json.dumps(grams_for("500000"), indent=2))

{  "idr": "500000",  "grams": "0.219641",  "quoted_at": "2026-11-02T11:25:01.624637Z"}

At that quote, 500,000 rupiah bought 0.219641 g at market price.

Value a balance

A balance of 1.25 g is worth Decimal("1.25") times the gram price in the user's currency. Fetch the price with from=XAU&to=IDR&amount=1&unit=gram. On 2 November 2026 that returned 2,277,632.59 rupiah per gram, so 1.25 g was worth 2,847,040.74 rupiah at market price. Choose whether the screen shows that number or the price at which you would buy the gold back. Say which one it is on the screen.

Compare with a dealer's spread

A savings product sells gold above market and buys it back below its sell price. On Basic and above, GET /v1/physical/ID returns dealer quotes with both sides. One quote from the 2 November 2026 response:

{"product":"digital_gram","price_basis":"per_gram","currency":"IDR","premium_over_spot_bps":397,"sell":"2368000","buyback":"2285000"}

The sell price was 3.97% above the market price at that moment, and the buyback price was 3.5% below the sell price. At that sell price the same 500,000 rupiah would have bought 0.211148 g, against 0.219641 g at the market price. Use quotes like this to check your own spread against the market. Dealer quotes exist for the countries in the /v1/physical index.

Build notes

• One rate per transaction. Fetch the rate on your server, show it to the user with a countdown, and write that rate and its timestamp into the ledger when the user confirms.
• Chart. GET /v1/bars returns daily gold bars. The last 30 days are available without a key, one year on Basic and history from 1996 on Plus and Pro.
• Limits. Keyless calls are 15 minutes late and capped at 10 a minute. A key raises the quota, and paid plans return live prices. A fintech app that quotes a price should use a paid plan for live data.
• Retries. A repeated deposit request should reuse the same ledger key so the user is not credited twice.