Altın Fiyatı API'si: Geliştiriciler İçin Eksiksiz Rehber

Bir altın fiyatı API'si size ne sunar

Bir altın fiyatı API'si, altının güncel ve geçmiş fiyatını yapılandırılmış veri olarak, genellikle HTTPS üzerinden JSON biçiminde döndürür; böylece yazılımınız web sayfalarından veri kazımadan veya sayıları elle kopyalamadan bu fiyatları kullanabilir. MetalAPI'de altının sembolü, bir troy ons altın için ISO 4217 kodu olan XAU'dur. Canlı fiyatı spot fiyattır: bankalar arası alış ve satış kotasyonlarının orta noktası.

Entegrasyonların çoğu alım satım sistemi değildir. Tipik kullanım alanları şunlardır:

• Altın ürünlerini piyasa hareket ettikçe yeniden fiyatlandıran online mağazalar ve kuyumcular.
• Hurda altın, ayarlı kuyum ürünleri veya külçe primleri için hesaplayıcılar.
• Varlıkları yerel para birimiyle değerleyen portföy takip ve kişisel finans uygulamaları.
• Stokları günlük kapanış fiyatıyla yeniden değerleyen muhasebe ve ERP sistemleri.
• Son bir yılın grafiğine ihtiyaç duyan gösterge panelleri, bültenler ve dahili raporlar.

Aynı API gümüşü (XAG), platini (XPT) ve paladyumu (XPD), dört endüstriyel metali, beş enerji kontratını, 57 para birimini ve 13 kripto parayı da kapsar: toplam 83 sembol, tümü semboller sayfasında listelenmiştir. Bu rehber altına odaklanıyor, ancak anlatılan her şey diğer semboller için de geçerlidir.

API anahtarı alın

Ücretsiz bir hesap oluşturun. Free plan kredi kartı gerektirmez ve günlük fiyat güncellemeleriyle ayda 100 istek içerir; bu, bir entegrasyonu geliştirip test etmek için yeterlidir. Ücretli planlar daha güncel fiyatlar, daha fazla istek ve ek endpoint'ler sunar; aşağıdaki plan tablosu bunları özetliyor.

Panelde API keys bölümünü açın ve bir anahtar oluşturun. Anahtarlar mk_live_ ile başlar. Yalnızca hash değeri saklandığı için tam anahtar yalnızca bir kez gösterilir; bu nedenle onu hemen bir ortam değişkenine veya bir gizli bilgi yöneticisine (secrets manager) kaydedin:

export METALAPI_KEY="mk_live_your_key_here"

API, anahtarı birbirine eşdeğer üç yolla kabul eder: api_key sorgu parametresi, Authorization: Bearer header'ı veya X-API-Key header'ı. Canlı ortamda header kullanmayı tercih edin; çünkü tam URL'ler erişim loglarına, proxy'lere ve hata izleme araçlarına düşme eğilimindedir. Kimlik doğrulama rehberi, tarayıcıdan yapılan çağrılar için alan adıyla sınırlandırılmış anahtarları da açıklar.

# 1. Sorgu parametresi
curl "https://metalapi.com/api/v1/latest?api_key=$METALAPI_KEY&currencies=XAU"

# 2. Authorization header'ı
curl "https://metalapi.com/api/v1/latest?currencies=XAU" \
  -H "Authorization: Bearer $METALAPI_KEY"

# 3. X-API-Key header'ı
curl "https://metalapi.com/api/v1/latest?currencies=XAU" \
  -H "X-API-Key: $METALAPI_KEY"

curl, JavaScript ve Python ile ilk isteğiniz

Her endpoint, https://metalapi.com/api/v1/ altında basit bir GET isteğidir. /latest endpoint'i güncel fiyatları döndürür. base, fiyatların ifade edildiği para birimini belirler (varsayılan USD); currencies ise yanıtı ihtiyacınız olan sembollerle sınırlar. Tek bir istek çok sayıda sembol döndürebilir ve yine de tek istek sayılır.

curl "https://metalapi.com/api/v1/latest?base=USD&currencies=XAU,XAG" \
  -H "X-API-Key: $METALAPI_KEY"

Başarılı bir yanıt şöyle görünür. Sayılar canlı fiyatlar değil, MetalAPI dokümantasyonu boyunca kullanılan örnek değerlerdir:

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

Aynı çağrı, fetch yerleşik olarak gelen Node.js 18 veya daha yeni sürümlerde şöyle yapılır. Üst düzey await çalışsın diye dosyayı gold.mjs olarak kaydedin, ardından node gold.mjs komutuyla çalıştırın:

const params = new URLSearchParams({ base: "USD", currencies: "XAU,XAG" });
const res = await fetch(`https://metalapi.com/api/v1/latest?${params}`, {
  headers: { Authorization: `Bearer ${process.env.METALAPI_KEY}` },
  signal: AbortSignal.timeout(10_000),
});
const data = await res.json();

if (!data.success) {
  throw new Error(`MetalAPI ${data.error.code} (${data.error.type}): ${data.error.info}`);
}

const gold = data.rates[`${data.base}XAU`];
const asOf = new Date(data.timestamp * 1000).toISOString();
console.log(`Gold: ${gold} ${data.base} per troy ounce (data from ${asOf})`);

Python'da ise requests kütüphanesiyle:

import os

import requests

resp = requests.get(
    "https://metalapi.com/api/v1/latest",
    params={"base": "USD", "currencies": "XAU,XAG"},
    headers={"X-API-Key": os.environ["METALAPI_KEY"]},
    timeout=10,
)
data = resp.json()
if not data["success"]:
    err = data["error"]
    raise RuntimeError(f"MetalAPI {err['code']} ({err['type']}): {err['info']}")

base = data["base"]
print(f"Gold:   {data['rates'][base + 'XAU']} {base} per troy ounce")
print(f"Silver: {data['rates'][base + 'XAG']} {base} per troy ounce")

Her iki kod parçacığı da kur anahtarını sabit kodlamak yerine data.base üzerinden oluşturur. Bu küçük alışkanlık, ileride baz para birimini değiştirdiğinizde kodun doğru çalışmaya devam etmesini sağlar ve bizi bu rehberin en önemli bölümüne getirir.

Kur formatını doğru okuyun

Her sembol rates içinde iki kez yer alır ve bu iki sayı birbirinin tersidir:

Genel kural şudur: rates.<BASE><SYMBOL>, sembolün bir biriminin baz para birimi cinsinden fiyatıdır. Yalın rates.<SYMBOL> anahtarı ise bunun tersidir, yani baz para biriminin bir birimi başına sembol miktarı. Ters biçim, forex tarzı API'lerle ve eski MetalAPI entegrasyonlarıyla uyumluluk için korunmaktadır.

Eski bir entegrasyondan kalma ters değerleri zaten saklıyorsanız onları yeniden indirmeniz gerekmez: fiyat = 1 ÷ ters değer. Yukarıdaki örnekte 1 ÷ 0,0002501319, son basamaklardaki yuvarlama farkı dışında yine 3997,89 sonucunu verir.

Para birimleri de aynı kuralı izler. Baz USD iken USDEUR bir euronun dolar cinsinden fiyatı, EUR ise dolar başına euro miktarıdır. Veri formatları rehberinde, Standard ve üzeri planlarda kullanılabilen alış ve satış anahtarları dahil daha fazla örnek bulunur.

Baz para birimleri ve birimler

Altını başka bir para birimiyle fiyatlandırmak için base değerini değiştirin. Kur anahtarı da onunla birlikte değişir: base=EUR, EURXAU değerini; base=INR ise INRXAU değerini döndürür. Çapraz kurlar tek bir anlık görüntüden gelir; bu nedenle euro cinsinden altın ile dolar cinsinden euro birbiriyle her zaman tutarlıdır.

Metal fiyatları varsayılan olarak troy ons başınadır. unit parametresi fiyatları başka bir ağırlık birimi başına döndürür:

Bu istek altın ve gümüşü gram başına euro cinsinden döndürür. unit varsayılan değerde olmadığında yanıt bunu üst düzeydeki bir unit alanında tekrarlar:

curl "https://metalapi.com/api/v1/latest?base=EUR&currencies=XAU,XAG&unit=gram" \
  -H "X-API-Key: $METALAPI_KEY"

unit yalnızca değerli ve endüstriyel metalleri etkiler. Enerji, para birimleri ve kripto bundan etkilenmez. Troy ons, gram, tola ve yuvarlama ile ilgili ayrıntılar için Troy ons, gram ve kilogram yazısını okuyun. Kuyum ürünleri satıyorsanız ayara göre altın fiyatları yazısı 22 ve 18 ayar fiyatlarını ve /carat endpoint'ini ele alıyor.

Geçmiş altın fiyatları

Geçmiş fiyatlar aynı parametreleri ve aynı yanıt formatını kullanır. Geçmiş veriler metaller ve enerji için 2000'de, para birimleri için 1999-01-04'te ve kripto için 2014'te başlar. İhtiyaçların çoğunu dört endpoint karşılar:

• /YYYY-MM-DD (veya /historical?date=YYYY-MM-DD ya da /yesterday): tek bir günün kapanış fiyatları. Hafta sonları ve tatiller için en son işlem gününün kapanışı döner.
• /timeframe (takma adı /timeseries): start_date ile end_date arasındaki günlük kapanışlar; Free planda istek başına en fazla 30 gün, ücretli planlarda 365 gün.
• /change: iki tarih arasındaki başlangıç kuru, bitiş kuru, mutlak ve yüzde değişim.
• /ohlc: tek bir günün açılış, en yüksek, en düşük ve kapanış değerleri.

# 15 Ocak 2024 kapanışında altın ve gümüş
curl "https://metalapi.com/api/v1/2024-01-15?currencies=XAU,XAG" \
  -H "X-API-Key: $METALAPI_KEY"

# Eylül 2026 için euro cinsinden günlük altın kapanışları
curl "https://metalapi.com/api/v1/timeframe?start_date=2026-09-01&end_date=2026-09-30&base=EUR&currencies=XAU" \
  -H "X-API-Key: $METALAPI_KEY"

Geçmiş günlerin kapanış fiyatları değişmez; bu nedenle onları tekrar tekrar istemek yerine bir kez saklayın. API ile geçmiş altın ve gümüş fiyatları yazısı 25 yıllık veriyi sayfalara bölerek çekmeyi, yerel olarak saklamayı ve grafiğe dökmeyi adım adım anlatıyor. Geçmiş veriler rehberinde uzun aralıklar için bir JavaScript yardımcısı bulunur.

Hatalar, kotalar ve plan limitleri

Başarısız bir istek, bir HTTP hata durum kodu ve success: false içeren bir gövde döndürür. error nesnesi sayısal bir code, makine tarafından okunabilir bir type ve insan tarafından okunabilir bir info içerir. Kodunuzda info metnine göre değil, her zaman code veya type değerine göre dallanın. İstek limiti (104), kota (105), plan kısıtlaması (106) ve zaman aralığı (207) hataları ayrıca bir upgrade_url içerir:

{
  "success": false,
  "error": {
    "code": 106,
    "type": "plan_restriction",
    "info": "The carat endpoint requires a paid subscription plan",
    "upgrade_url": "https://metalapi.com/dashboard/billing"
  }
}

En sık karşılaşacağınız kodlar:

Kimliği doğrulanmış her yanıt, kotanızı hem X-RateLimit-* header'ları olarak hem de gövdedeki rate_limit nesnesinde bildirir. /usage ve /symbols hiçbir zaman kotadan düşülmez; bu nedenle izleme sistemleriniz onları serbestçe çağırabilir. 104, 106, 107 veya bir sunucu hatasıyla reddedilen istekler ücretlendirilmez, ancak doğrulama hataları ücretlendirilir. Hata yönetimi rehberi tüm kodları listeler ve bir yeniden deneme yardımcısı içerir.

Planlar esas olarak istek hacminde ve fiyatların ne kadar güncel olduğunda farklılık gösterir:

Yıllık faturalandırmayla %25'e varan tasarruf sağlarsınız. Güncel ayrıntılar her zaman fiyatlandırma sayfasında yer alır.

Önbellekleme ve canlı ortam ipuçları

/latest endpoint'ini planınızın güncelleme sıklığından daha sık çağırmak aynı sayıları döndürür ve kotanızı boşa harcar. Güncel fiyatları en az planınızın güncelleme aralığı kadar, geçmiş günleri ise kalıcı olarak önbelleğe alın. Bu Python yardımcısı güncel fiyatları önbelleğe alır ve API'ye ulaşılamazsa son başarılı yanıtı sunmaya devam eder:

import os
import time

import requests

TTL_SECONDS = 600  # Standard plan: fiyatlar 10 dakikada bir güncellenir
session = requests.Session()
session.headers["X-API-Key"] = os.environ["METALAPI_KEY"]
_cache = {"at": 0.0, "data": None}


def latest_prices():
    now = time.monotonic()
    if _cache["data"] and now - _cache["at"] < TTL_SECONDS:
        return _cache["data"]
    try:
        r = session.get(
            "https://metalapi.com/api/v1/latest",
            params={"currencies": "XAU,XAG,XPT,XPD"},
            timeout=10,
        )
        data = r.json()
    except (requests.RequestException, ValueError):
        data = None
    if data and data.get("success"):
        _cache.update(at=now, data=data)
        return data
    if _cache["data"]:
        return _cache["data"]  # son geçerli fiyatlar; zaman damgalarını gösterin
    raise RuntimeError(data["error"] if data else "MetalAPI unreachable")

Bir entegrasyonu ucuz ve güvenilir tutan birkaç alışkanlık daha:

• Tüm sembolleri tek bir çağrıda isteyin. currencies=XAU,XAG,XPT,XPD tek bir isteğe mal olur; dört ayrı çağrı ise dört isteğe.
• Anahtarı sunucuda tutun. API'yi bir tarayıcının çağırması gerekiyorsa alan adıyla sınırlandırılmış bir anahtar kullanın. Kod yazmadan bir web sitesinde fiyat göstermek için gömülebilir bir widget anahtarı sayfanın tamamen dışında tutar.
• Zaman damgasını gösterin. timestamp, isteğinizin değil verinin zamanıdır. Özellikle önbellekteki bir değeri sunarken veya piyasa hafta sonu kapalıyken bunu fiyatın yanında gösterin.
• Sorgulama sıklığınızı planlayın. 10 dakikada bir sorgulama ayda yaklaşık 4.500, dakikada bir sorgulama ise yaklaşık 45.000 istek kullanır. Pro ve üzeri planlarda bunun yerine gerçek zamanlı akışı kullanabilir, Advanced ve üzeri planlarda ise webhook fiyat alarmları alabilirsiniz.
• Zaman aşımları ve seçici yeniden denemeler kullanın. 10 saniye civarında bir zaman aşımı belirleyin, 104 hatasını Retry-After süresinden sonra, 5xx hatalarını ise geri çekilmeyle yeniden deneyin; doğrulama hatalarını asla yeniden denemeyin.
• Sembolleri önceden doğrulayın. Başlangıçta /symbols endpoint'ini bir kez yükleyin (ücretsizdir) ve bilinmeyen kodları bir isteğe mal olmadan reddedin.

AI asistanlarıyla çalışıyorsanız https://metalapi.com/mcp adresindeki MetalAPI MCP sunucusu aynı verileri araçlar olarak sunar; böylece Claude, ChatGPT, Cursor veya VS Code, planınız dahilinde altın fiyatlarına ve geçmiş verilere erişebilir. Bkz. Yapay zekâ ve MCP. Tüm endpoint'ler ve parametreler için başvuru kaynağı API dokümantasyonudur.