Built by Developers, for Business.

Explore our comprehensive guides and API references to get started in seconds.

Masadir Economics provides institutional-grade financial data infrastructure designed to power the next generation of fintech applications, trading platforms, and enterprise analytics. Our API delivers real-time precision for gold, silver, and global currency markets, ensuring your business decisions are driven by the most accurate and timely data available.

Whether you are building a consumer-facing investment app or an internal risk management dashboard, our scalable infrastructure grows with your needs. We handle the complexities of data aggregation, normalization, and delivery so your team can focus on building value for your customers, backed by enterprise-level reliability and support.

Market Data Notice: Some datasets and widgets may include publicly available or delayed third-party market feeds for reference instruments such as indices, futures, energy commodities, or non-exchange-direct benchmark prices. These values are provided for informational and editorial use and may differ from licensed real-time exchange or broker feeds. Please review our Terms of Use and Disclaimer for the governing conditions.

Session & Status Notice: Market-state indicators such as LIVE, CLOSED, session open, and session close are operational references driven by Masadir's internal session schedules. They are designed for monitoring and display consistency and should not be treated as official exchange notices.

Admin Operations Notice: Manual support actions for expired subscriptions are recorded in Masadir's billing and subscription audit logs. Internal support extensions are tracked separately from end-user Stripe billing events.

Quick Start Guide

Copy-paste your first request using cURL or Python.

cURL

curl -X GET "https://api.masadir.net/v1/gold/USD" \
  -H "Authorization: Bearer mk_live_YOUR_KEY"

Python

import requests

url = "https://api.masadir.net/v1/gold/USD"
headers = {"Authorization": "Bearer mk_live_YOUR_KEY"}

response = requests.get(url, headers=headers)
print(response.json())

Authentication

Clear instructions on using your mk_live_ keys securely. Always keep your keys secret and never expose them in client-side code.

Manage your key from Dashboard. Existing keys are shown as preview only (mk_live_...).

Trial Access: verified new users may receive a one-time trial that uses the same dashboard and API key flow as subscribers, but with lower quota, RPM, and cache freshness limits until upgraded. Trial accounts can access protected market endpoints that follow the standard Bearer-key subscription model.

API Key Management

View Key

Go to Dashboard.
If a full key was just issued/regenerated, it appears once in the API key field.
After that, only a preview is shown (for security).

Regenerate Key

In Dashboard, click the regenerate button (♻️) in the Usage Hub.
Confirm the action.
Copy and save the new key immediately. The old key stops working right away.

Revoke / Disable Key

Use key regeneration to revoke the previous key automatically.
Enterprise/admin teams can also disable keys from backend operations when required.

Audit Trail

Key regeneration actions are logged in api_key_events with timestamp, IP address, user agent, and key preview change metadata.

Admin Operations

Masadir's internal admin dashboard includes support operations for subscribers and market-data monitoring.

Expired subscribers: support staff can review the full expired list or narrow it to subscriptions that ended in the last 7, 15, or 30 days.
Support extensions: expired or inactive subscriptions can be extended by a short support window while preserving an internal audit trail.
Audit records: manual support extensions are written to transactions, subscription_events, and stripe_events.

Endpoint Reference

Interactive documentation for protected market endpoints including Gold, Silver, Bitcoin, Brent, WTI, Natural Gas, and 150+ currency pairs.

GET /v1/{metal}/{currency}

Parameters:

metal: gold, silver, btc, brent, wti, or natural-gas
currency: 3-letter ISO code (e.g. USD, AED, SAR)

Protected Endpoint Examples

curl -X GET "https://api.masadir.net/v1/btc/USD" \
  -H "Authorization: Bearer mk_live_YOUR_KEY"

curl -X GET "https://api.masadir.net/v1/brent/USD" \
  -H "Authorization: Bearer mk_live_YOUR_KEY"

curl -X GET "https://api.masadir.net/v1/wti/USD" \
  -H "Authorization: Bearer mk_live_YOUR_KEY"

curl -X GET "https://api.masadir.net/v1/natural-gas/USD" \
  -H "Authorization: Bearer mk_live_YOUR_KEY"

Example Response: Gold (USD)

{
    "unit": "gram",
    "rates": {
        "XAU_9k": 60.62,
        "XAU_12k": 80.83,
        "XAU_14k": 94.57,
        "XAU_18k": 121.25,
        "XAU_21k": 141.45,
        "XAU_22k": 148.08,
        "XAU_24k": 161.66,
        "XAU_ounce": 5028.23,
        "XAU_pound": 1131.63
    },
    "success": true,
    "fetchedAt": "2025-02-10T03:58:24.418Z",
    "baseCurrency": "USD"
}

Example Response: Silver (AED)

{
    "unit": "gram",
    "rates": {
        "XAG_585k": 0.4166,
        "XAG_750k": 0.5337,
        "XAG_800k": 0.5718,
        "XAG_875k": 0.6236,
        "XAG_916k": 0.6535,
        "XAG_925k": 0.659,
        "XAG_958k": 0.6835,
        "XAG_999k": 0.7134,
        "XAG_ounce": 22.1838
    },
    "success": true,
    "fetchedAt": "2025-02-10T03:58:24.730Z",
    "baseCurrency": "AED"
}

Supported Currencies

We support a wide range of global currencies including:

USD, AED, SAR, EUR, GBP, EGP, KWD, QAR, BHD, OMR, JOD, LBP, IQD, TRY, IRR, AFN, ALL, AMD, ANG, AOA, ARS, AUD, AWG, AZN, BAM, BBD, BDT, BGN, BIF, BMD, BND, BOB, BRL, BSD, BTN, BWP, BYN, BZD, CAD, CDF, CHF, CLF, CLP, CNH, CNY, COP, CRC, CUP, CVE, CZK, DJF, DKK, DOP, DZD, ERN, ETB, FJD, FKP, FOK, GEL, GGP, GHS, GIP, GMD, GNF, GTQ, GYD, HKD, HNL, HRK, HTG, HUF, IDR, ILS, IMP, INR, ISK, JEP, JMD, JPY, KES, KGS, KHR, KID, KMF, KRW, KYD, KZT, LAK, LKR, LRD, LSL, LYD, MAD, MDL, MGA, MKD, MMK, MNT, MOP, MRU, MUR, MVR, MWK, MXN, MYR, MZN, NAD, NGN, NIO, NOK, NPR, NZD, PAB, PEN, PGK, PHP, PKR, PLN, PYG, RON, RSD, RUB, RWF, SBD, SCR, SDG, SEK, SGD, SHP, SLE, SLL, SOS, SRD, SSP, STN, SYP, SZL, THB, TJS, TMT, TND, TOP, TTD, TVD, TWD, TZS, UAH, UGX, UYU, UZS, VES, VND, VUV, WST, XAF, XCD, XCG, XDR, XOF, XPF, YER, ZAR, ZMW, ZWG, ZWL

Rate Limits

Transparent tiers designed to scale with your business growth.

Trial: 2,500 total requests over 7 days • 20 RPM • 10 min updates
Starter: 25,000 requests/month • 60 RPM • 5 min updates
Business: 150,000 requests/month • 120 RPM • 60s updates
Professional (pro): 600,000 requests/month • 240 RPM • 60s updates
Enterprise: 3,000,000 requests/month • 800 RPM • 30s updates

Usage display: Dashboard shows consumption since subscription start, plus all-time usage.

Market Sessions & Feed Sources

Masadir now tracks session state through DB-backed schedules rather than fixed UI logic. This keeps cron behavior, admin monitoring, homepage data blocks, and future widgets aligned.

Gold / Silver: session scheduling is maintained in UTC and used by both fetch gating and admin monitoring.
Bitcoin: treated as 24/7.
S&P 500: tracked against the New York cash session, with public-reference polling targeted at 15 to 30 minutes and freshness expected to remain within a 30 minute ceiling.
Brent / WTI / Natural Gas: tracked against New York futures-style sessions, sourced from Yahoo Finance futures pages for public informational use, and polled on a 15 to 30 minute cycle with a 30 minute freshness ceiling.

Admin monitoring exposes these values through a market-health panel that combines freshness (fetchedAt) and session state (opensAt, closesAt, timezone).

Widget Gallery

To protect browser stability, documentation uses static previews only. Click Get Widget for full interactive setup and embed code.

Note: hosted domain widget.masadir.net remains restricted by domain whitelist (Enterprise customers and approved partners).

Important: Widget connection status is domain-whitelist based and is independent from subscriber Bearer API key rotation.

Unified URL Switch Contract: all widgets support lang, theme|mode, currency, width, height, hide_led, hide_status, hide_currency, hide_mode, hide_timeframes|hide_tf, hide_updated, hide_branding|hide_masadir. Unsupported switches on a specific widget are safely ignored.