Get Ethiopian Birr (ETB) - N/A Historical Prices using this API (daily and monthly endpoints)
Ethiopian Birr (ETB) historical prices are critical for anyone pricing jewelry in Addis Ababa, backtesting commodity hedges in ETB, or reconciling ERP transactions denominated in Birr. In this guide, you’ll learn how to fetch daily and “monthly” ETB history with two Metals-API endpoints: a single-date Historical Rates query (for point-in-time prices) and the Time-Series endpoint (for a range like a calendar month). We’ll also cover practical implementation details developers care about: base currency decisions, unit handling (troy ounces vs grams), timestamps, weekend/holiday behavior, caching strategies, and data validation. By the end, you’ll be able to programmatically retrieve ETB-based historical prices and integrate them into trading tools, analytics pipelines, or production pricing flows. For symbols and capabilities, refer to the official Metals-API Supported Symbols and full reference in the Metals-API Documentation.
Use case: backfill daily and monthly ETB prices into your product
Let’s say you need to:
- Backfill a dashboard with end-of-day ETB-denominated prices over the past month (monthly view).
- Retrieve a specific day’s ETB price to close a P&L book or reconcile an invoice (daily view).
We’ll accomplish this with two endpoints that directly support daily and monthly workflows:
- Historical Rates (single date) for a given day.
- Time-Series (date range) for an entire calendar month (or any custom period).
In both workflows, you will include ETB in your query configuration so that the result is ETB-centric. You can either request ETB as the base currency to receive metal prices quoted per ETB, or keep USD as base and calculate ETB prices by conversion. Below you’ll see both approaches and when to use each.
Key concepts before you start
- Symbols and availability: Always confirm supported codes in the Metals-API Supported Symbols. ETB is a supported fiat currency, and common precious/industrial metals (e.g., XAU for gold, XAG for silver, XPT for platinum, etc.) are also available.
- Base currency: Metals-API responses are by default relative to USD. If you want ETB-centric results, you can switch the base to ETB (which yields “metal per 1 ETB”) or keep base=USD and convert to ETB on your end (to yield “ETB per 1 metal unit”).
- Units: Metals are typically returned “per troy ounce.” If you need grams, kilograms, or tolas, you’ll convert after retrieval using fixed multipliers (1 troy ounce = 31.1034768 grams).
- Timestamps and timezone: Responses include a timestamp and date string (UTC). Align your application timezone when plotting or reconciling end-of-day values.
- Weekend/holiday behavior: Metals spot markets and currency markets have downtime/low-liquidity windows. For missing days (e.g., weekends), you can forward-fill or skip per your analytics convention.
Which endpoint to use for ETB historical prices
- Daily (point-in-time): Historical Rates endpoint. Ideal for a single date (e.g., yesterday’s close).
- Monthly (range): Time-Series endpoint. Query a start_date and end_date across a whole month to retrieve daily values, then aggregate to month-end, monthly average, or custom metrics.
We’ll focus on these two. For advanced candles, see the OHLC endpoint. For more features, browse the Metals-API Documentation.
Authentication and setup
- API key: Required via access_key. Get yours free at the Metals-API Website.
- Transport: Use HTTPS.
- Security: Store keys in secure secrets management. Avoid hardcoding in front-end code or committing to version control.
Approach A: base currency ETB for direct ETB-denominated queries
When you set ETB as the base, rates express “units per 1 ETB.” For metals, that means “troy ounces per ETB.” Many applications want the opposite—“ETB per troy ounce.” You can simply invert the returned rate in your app. Example: if XAU rate is 0.000009 in the response with base=ETB, then price is 1 / 0.000009 ≈ 111,111 ETB per troy ounce.
This is a clean way to make ETB appear in every response and is especially convenient when you need to price multiple metals in ETB consistently.
Approach B: keep base=USD and convert to ETB in your app
Alternatively, leave the API base as USD and either:
- Request ETB currency rate alongside metals, then compute ETB per metal as (USD per metal) × (ETB per USD).
- Use the Convert endpoint for precise amounts when quoting or invoicing (e.g., convert 1 XAU to ETB on a historical date).
This is often more intuitive because “USD per troy ounce” is the industry standard reference quote. Your application then multiplies by the USD→ETB FX rate to finalize the ETB result. For conversion logic and more, see the endpoint docs.
Endpoint 1: Historical Rates (Daily ETB)
Purpose
Retrieve a single date’s rates to backfill a daily close, reconcile ETB-denominated invoices, or fix a valuation snapshot for a specific business day.
Typical parameters
- Date path: YYYY-MM-DD for the historical day in UTC.
- Base: Use ETB to highlight Birr in your pipeline (see Approach A). Otherwise, use default USD and post-process (Approach B).
- Symbols: Include the instruments you need. Keep your symbol list tight to reduce payload size and latency.
Example: single-day ETB-based request (curl)
This example demonstrates daily ETB-based pricing for a target date. Replace YOUR_API_KEY with your key from the Metals-API Website.
curl -s 'https://metals-api.com/api/2024-08-30?access_key=YOUR_API_KEY&base=ETB&symbols=XAU'
Example JSON response (daily ETB)
{
"success": true,
"timestamp": 1724978400,
"base": "ETB",
"date": "2024-08-30",
"rates": {
"XAU": 0.00000908
},
"unit": "per troy ounce"
}
How to interpret fields
- success: Boolean result of the call.
- timestamp: Unix epoch (UTC) for the price fix.
- base: Your requested base. Here it’s ETB, so rates express “troy ounces per 1 ETB.”
- date: The historical date (UTC calendar date).
- rates.XAU: 0.00000908 means 0.00000908 troy ounces per 1 ETB on that date.
- unit: “per troy ounce” indicates the metal unit. For consumer pricing, you will commonly invert to get ETB per troy ounce.
Converting to ETB per troy ounce
Invert the rate to get ETB per troy ounce: price_ETB_per_oz = 1 / rates.XAU. In this example, 1 / 0.00000908 ≈ 110,132.16 ETB per troy ounce.
Common pitfalls and tips (Historical)
- Weekend dates: If you ask for a Saturday/Sunday, some datasets reflect last available fix. Decide if you want to forward-fill or skip.
- Missing symbols: Always validate that rates contains the key you expect (e.g., XAU). If not, log and retry or notify.
- Numeric precision: Store and compute in decimal or high-precision floats for finance-grade accuracy.
- Units: Always annotate downstream data with “troy ounces” and “ETB per troy ounce” after inversion to avoid confusion.
Endpoint 2: Time-Series (Monthly ETB)
Purpose
Retrieve daily historical rates across a period—such as the full previous month—then compute month-end close, monthly average, or volatility metrics in ETB.
Typical parameters
- start_date / end_date: Inclusive range for your calendar month (e.g., 2024-08-01 to 2024-08-31).
- base: ETB for ETB-centric development pipelines (Approach A), or default USD for standard quotes (Approach B).
- symbols: Limit to needed instruments for faster responses.
Example: monthly ETB-based query (curl)
curl -s 'https://metals-api.com/api/timeseries?access_key=YOUR_API_KEY&start_date=2024-08-01&end_date=2024-08-31&base=ETB&symbols=XAU'
Example JSON response (ETB monthly time-series)
{
"success": true,
"timeseries": true,
"start_date": "2024-08-01",
"end_date": "2024-08-31",
"base": "ETB",
"rates": {
"2024-08-01": { "XAU": 0.00000921 },
"2024-08-02": { "XAU": 0.00000917 },
"2024-08-05": { "XAU": 0.00000910 },
"2024-08-06": { "XAU": 0.00000912 },
"2024-08-07": { "XAU": 0.00000911 },
"2024-08-08": { "XAU": 0.00000909 },
"2024-08-09": { "XAU": 0.00000908 },
"2024-08-12": { "XAU": 0.00000906 },
"2024-08-13": { "XAU": 0.00000905 },
"2024-08-14": { "XAU": 0.00000907 },
"2024-08-15": { "XAU": 0.00000904 },
"2024-08-16": { "XAU": 0.00000903 },
"2024-08-19": { "XAU": 0.00000902 },
"2024-08-20": { "XAU": 0.00000901 },
"2024-08-21": { "XAU": 0.00000900 },
"2024-08-22": { "XAU": 0.00000899 },
"2024-08-23": { "XAU": 0.00000898 },
"2024-08-26": { "XAU": 0.00000897 },
"2024-08-27": { "XAU": 0.00000898 },
"2024-08-28": { "XAU": 0.00000900 },
"2024-08-29": { "XAU": 0.00000902 },
"2024-08-30": { "XAU": 0.00000908 }
},
"unit": "per troy ounce"
}
How to build a “monthly” value from daily data
- Month-end close (preferred for charts): pick the last business day in the month (e.g., 2024-08-30 above).
- Monthly average (for smoothing): average the inverted daily ETB-per-oz values across the period.
- High/low: compute inverted daily ETB prices and track min/max over the month.
Because the base is ETB and the unit is in troy ounces, remember to invert daily before aggregating to ETB per troy ounce. This avoids nonlinearity errors.
JavaScript example: fetch daily and invert for ETB per ounce
async function getDailyEtbPerOunce(dateStr) {
const url = `https://metals-api.com/api/${dateStr}?access_key=${process.env.METALS_API_KEY}&base=ETB&symbols=XAU`;
const res = await fetch(url);
if (!res.ok) throw new Error(`HTTP ${res.status}`);
const data = await res.json();
if (!data.success) {
const msg = data.error && data.error.info ? data.error.info : 'Unknown API error';
throw new Error(msg);
}
const xauPerEtb = data.rates && data.rates.XAU;
if (typeof xauPerEtb !== 'number' || xauPerEtb <= 0) {
throw new Error('Invalid or missing XAU rate for ETB base');
}
// Invert to get ETB per troy ounce
const etbPerOunce = 1 / xauPerEtb;
return {
date: data.date,
timestamp: data.timestamp,
etbPerOunce,
unit: 'ETB per troy ounce'
};
}
Response handling notes
- Validate data.success before using rates.
- Check for missing dates and adjust your monthly loop (market closures and weekends).
- Normalize timestamp to your storage format (UTC recommended).
Alternative: derive ETB with USD base (and ETB FX in the same call)
If you stay with base=USD, request both XAU and ETB in one query, then compute:
- USD per troy ounce = rates.XAU.
- ETB per USD = invert(rates.ETB) if the rate expresses USD per ETB, or multiply directly if rate is ETB per USD (verify direction in your test call).
- ETB per troy ounce = (USD per troy ounce) × (ETB per USD).
This keeps your pricing aligned to USD spot conventions, which many trading systems prefer. For full details on parameters and symbol behavior, consult the Metals-API Documentation.
Advanced: OHLC (open/high/low/close) for ETB-based daily candles
For candlestick charts or risk models, you can pull open, high, low, and close for a given day. Request base=ETB to keep everything in ETB terms, then invert each field to get ETB per troy ounce.
Example OHLC response (ETB base)
{
"success": true,
"timestamp": 1724978400,
"base": "ETB",
"date": "2024-08-30",
"rates": {
"XAU": {
"open": 0.00000912,
"high": 0.00000915,
"low": 0.00000905,
"close": 0.00000908
}
},
"unit": "per troy ounce"
}
Invert each value to get ETB per ounce for open/high/low/close. These transformed values drive ETB-denominated candlesticks and VaR models.
Performance, scaling, and caching
- Cache historical results aggressively: historical data is immutable. Use long TTLs (e.g., 24 hours or more) for past dates.
- Batch requests with Time-Series: prefer time ranges over many single-day calls to minimize latency and request counts.
- Incremental backfills: For rolling windows, only fetch the new day(s) and append to your store.
- Data lake ingestion: Normalize to a consistent schema—date (UTC), base, symbol, quote, and unit—and store inverted ETB-per-oz alongside raw values.
Data quality and validation
- Schema checks: Ensure response keys (success, date, timestamp, base, rates) are present and types match expectations.
- Business rules: Reject negative or zero rates; log anomalies.
- Cross-validation: Optionally compare aggregate monthly averages with a secondary source when implementing new pipelines (e.g., IMF data portal or central bank stats) to spot integration bugs, not to override Metals-API data.
Security and reliability
- Secrets management: Store your access_key in environment variables or vaults; never hardcode in client-side JS.
- Network resilience: Implement retries with exponential backoff (idempotent GETs). Avoid infinite retries.
- Error handling: If success=false, inspect returned error info; fall back to cached values when appropriate.
- Observability: Log request IDs (if available), timestamps, endpoints, and symbol sets to debug data gaps quickly.
FX and unit nuances when working with ETB
- Directionality: When you set base=ETB, metal quotes are “metal per ETB.” Most finance UIs want “ETB per metal,” so invert.
- Unit conversions: If your storefront lists grams or tolas, convert after you compute ETB per troy ounce. Example: ETB per gram = (ETB per troy ounce) / 31.1034768.
- Rounding: Display precision for consumer UX (e.g., 2 decimals for ETB), but keep high-precision in storage for analytics.
Digital transformation: ETB pricing meets modern metal markets
ETB-denominated pricing is becoming more common as jewelers, manufacturers, and fintechs expand across East Africa. Modern APIs make it straightforward to price gold, silver, and other metals in ETB with consistent, auditable historical series. This unlocks:
- Programmatic repricing in e-commerce (ETB product pages auto-refresh based on latest metal/fx trends).
- Real-time risk analytics and scenario tests in ETB (e.g., hedging policies sensitive to Birr moves).
- Backtesting trading signals with ETB normalization to reflect local purchasing power.
Innovations in data pipelines—stream processors, serverless ETL, and lakehouse architectures—make it natural to land Metals-API ETB data, transform to ETB per ounce, and push to downstream systems. Explore more capabilities at the Metals-API Documentation.
Spotlight on Molybdenum (MO) in ETB: from insights to smart systems
Molybdenum (MO) sits at the intersection of industrial demand and technology-led analytics. As manufacturing digitizes, real-time MO data—normalized in ETB—can drive:
- Supplier negotiations in ETB with automated alerts when MO crosses certain thresholds.
- Smart ERP integrations that convert MO quotes to ETB per kilogram for procurement approvals.
- Data science models forecasting MO trends, feeding ETB-denominated budgets and capex planning.
Whether you’re analyzing MO, gold, or other metals, the same principles apply: choose base=ETB for ETB-centric flows (invert rates), or maintain base=USD and convert to ETB post-fetch. Either way, the framework scales from dashboards to autonomous pricing engines.
Practical production patterns
- Immutable storage: Once written, historical ETB data should be immutable. Any upstream reprocessing should version data.
- Schema evolution: Add fields rather than change meanings. Keep both raw (metal per ETB) and transformed (ETB per metal) values with explicit unit labels.
- Idempotent pipelines: Rerunning the same historical load should produce identical results; hash checks can verify integrity.
- Governance: Tag records by source (metals-api.com), endpoint, date fetched, and transformation steps for auditability.
Real-world example: ETB monthly dashboard build
- Nightly job (UTC) calls Time-Series for the month-to-date with base=ETB and symbols=XAU.
- Transform: invert daily to ETB per ounce, compute month-end (latest available business day) and monthly average.
- Persistence: write both raw and transformed results to a warehouse partitioned by date and symbol.
- Serving: BI tool queries the warehouse to render an ETB-denominated chart with last price, average, and MoM change.
Error handling and recoverability
- Transient HTTP errors: retry with jitter; circuit-break once retries exceed threshold; fall back to cached results.
- Partial data within a month: forward-fill or mark gaps; annotate chart tooltips to reflect non-trading days.
- Bad inputs: validate dates (YYYY-MM-DD), ensure start_date ≤ end_date, and symbols are supported per the symbols list.
Complete daily-to-monthly workflow checklist
- Decide base strategy (ETB or USD).
- Fetch daily via Historical for specific dates; fetch monthly via Time-Series for ranges.
- Invert when base=ETB to get ETB per troy ounce (and convert to grams/kg if needed).
- Handle weekends/holidays gracefully (forward-fill, mark, or skip).
- Cache historical responses; batch ranges to reduce calls.
- Persist with schema and unit metadata; log timestamps and request context.
Compliance, auditing, and documentation
- Documentation links: Keep a pointer to the Metals-API Documentation in your runbooks.
- Source-of-truth: Record the endpoint used (historical, timeseries), date range, base, and symbols for each job run.
- Reproducibility: Pin code versions and configuration; archive response samples for audit trails.
Get started
Ready to build ETB-denominated charts, pricing, and analytics? Visit the Metals-API Website to get a free API key, browse the supported symbols, and start integrating today.
Additional resources
- Metals-API Documentation for endpoint specifics and parameters.
- World Bank commodity market insights for macro context.
- National Bank of Ethiopia for local monetary updates.
FAQ
Can I query ETB-only historical rates without metals?
Yes. Include ETB among your symbols and use a fiat base (USD by default) to retrieve ETB FX history. If you’re pricing metals in ETB, you’ll typically retrieve metals and ETB together and compute ETB per metal.
How do I get a monthly ETB price?
Use the Time-Series endpoint for the calendar month, then choose a convention: last business day (month-end close) or an average across the month. Always transform values to “ETB per troy ounce” before aggregating if you used base=ETB.
What about weekends and holidays?
You may see missing days or last-available fixes. Choose a consistent approach (forward-fill, skip, or interpolate) and document it in your analytics.
How do units affect ETB pricing?
Metals are quoted per troy ounce. To display per gram in ETB, compute ETB per troy ounce then divide by 31.1034768.
Is there a difference between base=ETB and base=USD for ETB pricing?
Functionally you can get to the same ETB result. With base=ETB, invert the returned “metal per ETB” to “ETB per metal.” With base=USD, multiply the USD metal price by ETB per USD. Choose whichever is cleaner for your architecture.
Where can I find which symbols are supported?
See the up-to-date list on the Metals-API Supported Symbols page.
How do I start?
Head to the Metals-API Website, sign up to get your free API key, read the documentation, and make your first ETB historical query today.