How to fetch Bhutanese Ngultrum (BTN) - N/A Price API JSON with curl examples

You need to price a metals product, hedged exposure, or checkout total in Bhutanese Ngultrum (BTN) right now, and you want a clean JSON feed you can wire into your app. By the end of this guide, you’ll pull the latest BTN rate from Metals-API with curl and a short script, understand how to read the response, and know how to cache, convert, and productionize it.

What you’ll build: fetch BTN latest in one request

We’ll query the Latest endpoint for BTN with base USD so you can convert between USD and BTN deterministically. This is the simplest integration to price metals, invoices, or quotes for Bhutan-based customers, or to reconcile settlements denominated in BTN.

• Endpoint: GET /api/latest
• Symbols: BTN and USDBTN (both directions for clean math)
• Use case: price in BTN, or convert BTN amounts to USD for reporting

If you’re browsing capabilities or authentication details, scan the Metals-API Documentation. For supported symbols beyond BTN, see the Metals-API Supported Symbols.

BTN latest with curl

Copy, replace YOUR_API_KEY, and run:

curl "https://metals-api.com/api/latest?access_key=YOUR_API_KEY&symbols=BTN,USDBTN"

Sample JSON response (use these exact values to test your parsing):

{"success":true,"timestamp":1791332700,"date":"2026-10-07","base":"USD","rates":{"BTN":96.3216625,"USD":1,"USDBTN":0.010381880607594372}}

How to read this JSON

• base: "USD" — all rates are relative to 1 USD by default.
• rates.BTN: 96.3216625 — BTN per 1 USD.
• rates.USDBTN: 0.010381880607594372 — USD per 1 BTN (the inverse rate).
• timestamp/date: UTC timestamp and calendar date for the snapshot.

If you price metal quotes in BTN, multiply USD prices by rates.BTN. If you need to convert BTN back to USD, multiply BTN amounts by rates.USDBTN. This “two-sided” approach avoids floating-point drift from manual inversion.

BTN conversion examples you’ll actually use

• USD to BTN: total_btn = total_usd × rates.BTN
• BTN to USD: total_usd = total_btn × rates.USDBTN

Example math from the sample JSON above:

• 100 USD → BTN = 100 × 96.3216625 = 9,632.16625 BTN
• 10,000 BTN → USD = 10,000 × 0.010381880607594372 ≈ 103.81880607594372 USD

Node.js example: fetch BTN and compute a checkout total

import https from "https";
import { URL } from "url";

const API_KEY = process.env.METALS_API_KEY || "YOUR_API_KEY";

function getLatestBTN() {
return new Promise((resolve, reject) => {
const url = new URL("https://metals-api.com/api/latest");
url.searchParams.set("access_key", API_KEY);
// Request both BTN and USDBTN so we can convert in either direction without inverting
url.searchParams.set("symbols", "BTN,USDBTN");

https.get(url, (res) => {
let data = "";
res.on("data", (chunk) => (data += chunk));
res.on("end", () => {
try {
const json = JSON.parse(data);
if (!json.success) {
return reject(new Error("Metals-API error payload"));
}
const { base, date, timestamp, rates } = json;
if (!rates || rates.BTN == null || rates.USDBTN == null) {
return reject(new Error("Missing BTN/USDBTN in response"));
}
resolve({ base, date, timestamp, btnPerUsd: rates.BTN, usdPerBtn: rates.USDBTN });
} catch (e) {
reject(e);
}
});
}).on("error", reject);
});
}

// Example: convert a USD metals cart to BTN and round to 2 decimals
(async () => {
const { base, date, timestamp, btnPerUsd, usdPerBtn } = await getLatestBTN();
console.log(`Base: ${base} Date: ${date} Timestamp: ${timestamp}`);
console.log(`BTN per USD: ${btnPerUsd} | USD per BTN: ${usdPerBtn}`);

const cartUsd = 387.45; // your computed metals price in USD
const cartBtn = cartUsd * btnPerUsd;
console.log(`Cart in USD: ${cartUsd}`);
console.log(`Cart in BTN: ${Math.round(cartBtn * 100) / 100}`);
})();

Production details that save time

1) Units and base logic

• Metals-API defaults to base=USD. For currency symbols like BTN, rates are “per USD”.
• rates.BTN means BTN/1 USD. rates.USDBTN means USD/1 BTN.
• For metals like gold, the API expresses rates per troy ounce when you request metals. For pure currency work (BTN), you won’t see a metals unit field in the response.

2) Timezone and timestamps

• timestamp is a Unix epoch in seconds (UTC). Use it for cache keys, reconciliation, and to compare freshness across environments.
• date is the calendar date associated with the data snapshot. If you need intraday updates, consult your plan’s update frequency in the docs.

3) Caching and request strategy

• Cache the entire successful JSON by timestamp for at least the update interval of your plan. Many teams cache for 60s–10m depending on traffic and required staleness.
• Serve from cache and refresh in the background to reduce tail latencies and request volume.
• Pin conversions to a single timestamp per order to avoid mid-checkout re-pricing.

4) Weekends and market closures

• Expect fewer or no changes over weekends and certain holidays. Always check timestamp to verify whether a new snapshot is available.
• For historical audits, log both your source price (e.g., metal in USD) and the BTN rate used with the same timestamp.

5) Symbols you can request alongside BTN

If you need to pair BTN with metal prices (e.g., USD gold price → BTN checkout), first fetch the metal rate relative to USD, then convert that USD total into BTN. Explore which symbols are available on the Symbols page.

Adding historical context for BTN (optional)

For backtesting, budget forecasts, or volatility-aware pricing, query historical or time-series data. Use the date-based Historical endpoint for a specific day, or the time-series endpoint for a date range. These are documented with parameters and date formats here: endpoint reference.

• Historical: get the BTN rate as of a specific date (e.g., end-of-month closing for accounting).
• Time-series: daily BTN rates between two dates to build charts and compute returns.

Tip: if your application displays price deltas, store the BTN rate you used at order time, then compare to a new latest rate using a single, consistent decimal precision to avoid rounding noise.

BTN in a metals pricing flow

Here’s a common flow to price a metals product (quoted in USD internally) for a Bhutan-based customer:

1. Price your metal in USD using your chosen pricing model (spot, OHLC-based, or internal book price).
2. Fetch BTN latest with symbols=BTN,USDBTN once per update interval.
3. Convert USD total to BTN with rates.BTN; persist amount and timestamp on the order.
4. For refunds or chargebacks, use the original BTN amount; if you must reprice, fetch the BTN at refund time and show the timestamp difference for transparency.

Smart integration and analytics notes

• Precision: Keep at least 6–8 decimal places in intermediate math, then round for display and storage as required by your finance policy.
• Idempotency: Pair each quote or payment intent with a BTN rate timestamp. Reuse it on retries to avoid FX drift.
• Observability: Emit structured logs: { endpoint, symbols, timestamp, btn_per_usd, usd_per_btn, cache_hit }.
• Security: Do not expose your Metals-API key in client-side code. Call the API from your server or an authenticated edge worker.

About BTN and digital transformation in metals

BTN (Bhutanese Ngultrum) is pegged to the Indian Rupee, and practical pricing often needs consistent USD ⇄ BTN conversion to align metals quotes with regional payments and ledgers. With programmatic BTN rates, you can:

• Automate e-commerce pricing for jewelry SKUs sold in Bhutan.
• Reconcile BTN settlements to USD books without manual FX lookups.
• Backfill historical BTN conversions to measure P&L impact from timing.

As you adopt real-time data, combine BTN with your metal exposures and risk rules to drive smarter replenishment and margin controls. Metals-API’s JSON format is straightforward for streaming into dashboards, ETL jobs, or anomaly alerts.

Plan notes and next steps

• Metals-API does not offer a free trial. Choose a plan that fits your update frequency and coverage needs.
• Copper Monthly is $19.99/mo. For current plan details and endpoints, see the Documentation.
• If you partner with marketplaces or need enterprise controls, review Metals-API MCP for multi-channel or compliance workflows.

Additional resources

• Official symbols index for all available metals and currencies: Metals-API Supported Symbols
• Bhutan’s monetary authority (for policy context): Royal Monetary Authority of Bhutan
• Reference for currency codes: ISO 4217 Currency Codes

FAQ

Q1: Which symbol should I use to get BTN?
A: Use BTN. If you also want the inverse (USD per BTN) without manual inversion, include USDBTN in the symbols list.

Q2: What does base=USD mean for BTN?
A: It means the rate fields are expressed relative to 1 USD. rates.BTN is BTN per USD; rates.USDBTN is USD per BTN.

Q3: How often should I fetch the latest BTN?
A: Match your plan’s update cadence and your UX needs. Cache results by timestamp and refresh slightly behind the update frequency to avoid redundant calls.

Q4: How do I handle weekends or holidays?
A: Expect the same timestamp across multiple requests when markets are inactive. Always rely on the timestamp to decide if you should refresh pricing or continue serving the cached rate.

Q5: Can I query BTN historically?
A: Yes—use the Historical or Time-series endpoints for specific dates or ranges. See parameters and date formats in the Documentation.

Ready to wire BTN pricing into your checkout, trading tool, or ERP? Get your API key now and start calling the endpoint: Register. For multi-channel or compliance needs, explore MCP.