توثيق API

# Header (recommended)
curl -H "Authorization: Bearer YOUR_API_KEY" https://metalapi.com/api/v1/latest
curl -H "X-API-Key: YOUR_API_KEY" https://metalapi.com/api/v1/latest

# Query string
curl "https://metalapi.com/api/v1/latest?api_key=YOUR_API_KEY"

curl "https://metalapi.com/api/v1/latest?api_key=YOUR_API_KEY&base=USD&currencies=XAU,XAG,EUR"

{
  "success": true,
  "timestamp": 1792834892,
  "date": "2026-10-24",
  "base": "USD",
  "rates": {
    "XAU": 0.0002501319,
    "USDXAU": 3997.89,
    "XAG": 0.0185392857,
    "USDXAG": 53.94,
    "EUR": 0.8925,
    "USDEUR": 1.1204
  },
  "rate_limit": { "limit": 10000, "remaining": 9875, "reset": 1793491200, "used": 125, "plan": "Standard", "reset_date": "2026-11-01T00:00:00.000Z" }
}

curl "https://metalapi.com/api/v1/2024-01-15?api_key=YOUR_API_KEY&currencies=XAU,XAG"

{
  "success": true,
  "timestamp": 1705276800,
  "historical": true,
  "date": "2024-01-15",
  "base": "USD",
  "rates": {
    "XAU": 0.0004874244,
    "USDXAU": 2051.6,
    "XAG": 0.0431741646,
    "USDXAG": 23.162
  },
  "rate_limit": { "...": "..." }
}

curl "https://metalapi.com/api/v1/convert?api_key=YOUR_API_KEY&from=USD&to=XAU&amount=1000&unit=gram"

{
  "success": true,
  "query": { "from": "USD", "to": "XAU", "amount": 1000, "unit": "gram" },
  "info": { "timestamp": 1792834892, "rate": 0.0077799, "quote": 0.0077799 },
  "date": "2026-10-24",
  "result": 7.7799,
  "rate_limit": { "...": "..." }
}

curl "https://metalapi.com/api/v1/timeframe?api_key=YOUR_API_KEY&start_date=2026-10-19&end_date=2026-10-23&currencies=XAU"

{
  "success": true,
  "timeframe": true,
  "start_date": "2026-10-19",
  "end_date": "2026-10-23",
  "base": "USD",
  "rates": {
    "2026-10-19": { "XAU": 0.0002403788, "USDXAU": 4160.1 },
    "2026-10-20": { "XAU": 0.0002413943, "USDXAU": 4142.6 },
    "2026-10-21": { "XAU": 0.0002409639, "USDXAU": 4150 },
    "2026-10-22": { "XAU": 0.0002462812, "USDXAU": 4060.4 },
    "2026-10-23": { "XAU": 0.0002495072, "USDXAU": 4007.9 }
  },
  "rate_limit": { "...": "..." }
}

curl "https://metalapi.com/api/v1/change?api_key=YOUR_API_KEY&start_date=2026-01-02&end_date=2026-10-23&currencies=XAU"

{
  "success": true,
  "change": true,
  "start_date": "2026-01-02",
  "end_date": "2026-10-23",
  "base": "USD",
  "rates": {
    "XAU": { "start_rate": 0.0002309682, "end_rate": 0.0002495072, "change": 0.000018539, "change_pct": 8.02665 },
    "USDXAU": { "start_rate": 4329.6, "end_rate": 4007.9, "change": -321.7, "change_pct": -7.43025 }
  },
  "rate_limit": { "...": "..." }
}

curl "https://metalapi.com/api/v1/ohlc?api_key=YOUR_API_KEY&date=2026-10-23&currencies=XAU"

{
  "success": true,
  "ohlc": true,
  "date": "2026-10-23",
  "base": "USD",
  "rates": {
    "USDXAU": { "open": 4042.2, "high": 4050.2, "low": 3989.1, "close": 4007.9 },
    "XAU": { "open": 0.000247390, "high": 0.000250683, "low": 0.000246901, "close": 0.000249507 }
  },
  "rate_limit": { "...": "..." }
}

curl "https://metalapi.com/api/v1/carat?api_key=YOUR_API_KEY&carat=22&unit=gram&base=EUR"

{
  "success": true,
  "carat": "22",
  "date": "2026-10-24",
  "base": "EUR",
  "timestamp": 1792834892,
  "rates": {
    "XAU22K": { "price": 105.5297, "unit": "gram", "carat": "22", "purity": 0.916667 }
  },
  "rate_limit": { "...": "..." }
}

curl "https://metalapi.com/api/v1/symbols?api_key=YOUR_API_KEY"

{
  "success": true,
  "symbols": {
    "XAU": "Gold",
    "XAG": "Silver",
    "XPT": "Platinum",
    "XPD": "Palladium",
    "XCU": "Copper",
    "USD": "US Dollar",
    "EUR": "Euro",
    "BTC": "Bitcoin"
  },
  "rate_limit": { "...": "..." }
}

curl "https://metalapi.com/api/v1/usage?api_key=YOUR_API_KEY"

{
  "success": true,
  "usage": {
    "requests_made": 125,
    "requests_quota": 10000,
    "requests_remaining": 9875,
    "plan": "standard",
    "period_start": "2026-10-01T00:00:00.000Z",
    "period_end": "2026-11-01T00:00:00.000Z"
  },
  "result": { "plan": "Standard", "used": 125, "total": 10000, "remaining": 9875 },
  "rate_limit": { "...": "..." }
}

const es = new EventSource(
  "https://metalapi.com/api/v1/stream?api_key=YOUR_API_KEY&currencies=XAU,XAG,EUR"
);
es.addEventListener("prices", (e) => {
  const { timestamp, rates } = JSON.parse(e.data);
  console.log(timestamp, rates.USDXAU);
});
es.addEventListener("error", (e) => console.warn("stream error", e));

event: prices
data: {"timestamp":1792834897,"base":"USD","rates":{"XAU":0.0002501,"USDXAU":3998.12,"XAG":0.01853,"USDXAG":53.97}}

X-RateLimit-Limit: 10000          # monthly quota
X-RateLimit-Remaining: 9875
X-RateLimit-Used: 125
X-RateLimit-Reset: 1793491200     # unix time of the next reset
X-RateLimit-Reset-Date: 2026-11-01T00:00:00.000Z
X-RateLimit-Plan: Standard
X-RateLimit-Minute-Limit: 60
X-RateLimit-Minute-Remaining: 58
Retry-After: 21                   # only on 429 responses

{
  "success": false,
  "error": { "code": 105, "type": "quota_exceeded", "info": "User has reached or exceeded his subscription plan's monthly API request allowance" },
  "rate_limit": { "limit": 100, "remaining": 0, "used": 100, "plan": "Free", "...": "..." }
}

import crypto from "node:crypto";

// Express example: use the raw request body.
app.post("/metalapi-webhook", express.raw({ type: "application/json" }), (req, res) => {
  const header = req.get("X-MetalAPI-Signature") ?? "";        // "t=1792834892,v1=5f0c…"
  const { t, v1 } = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  const expected = crypto
    .createHmac("sha256", process.env.METALAPI_WEBHOOK_SECRET)
    .update(`${t}.${req.body}`)
    .digest("hex");
  const fresh = Math.abs(Date.now() / 1000 - Number(t)) < 300;
  if (!fresh || !crypto.timingSafeEqual(Buffer.from(v1, "hex"), Buffer.from(expected, "hex"))) {
    return res.status(400).end();
  }
  const event = JSON.parse(req.body);              // { event: "alert.triggered", alert: {...}, price: 4012.5 }
  res.status(200).end();
});

<div id="metalapi-widget-w_abc123"></div>
<script src="https://metalapi.com/js/widget.js" data-widget="w_abc123" async></script>