altinapi — Türkiye Altın & Döviz Fiyat API'si

altinapi için resmi Node.js / TypeScript SDK

Gerçek zamanlı altın fiyatları, döviz kurları, gümüş, platin, paladyum ve sarrafiye verisi — REST API ve WebSocket ile.

🎯 Harem Altın ile Birebir Aynı Fiyat Verisi

altinapi, Harem Altın ile aynı veri sağlayıcısından beslenir. Bu sayede uygulamanızda gösterdiğiniz fiyatlar, Harem Altın'da görünen fiyatlarla %100 örtüşür.

⚖️ Yasal not: altinapi bağımsız bir servistir. Harem Altın ile ortaklığı, iştiraki veya organik bir bağı yoktur. "Harem Altın" tescilli bir markadır; burada yalnızca veri kaynağının aynılığını belirtmek amacıyla karşılaştırma yapılmaktadır.

🔑 Ücretsiz API key al →

🚀 Niye altinapi?

| | altinapi | Diğer altın fiyat API'leri | |---|---|---| | Veri kaynağı | Harem Altın ile aynı feed | Genelde LBMA / international ons | | Sarrafiye desteği | ✅ Çeyrek, yarım, tam, ata, gremese | ❌ Yok | | 22/14 ayar | ✅ Var | ❌ Yok | | Gram altın (5/10/20/50/100 gr) | ✅ Var | ❌ Yok | | Türk lirası pariteleri | ✅ 15+ döviz | ⚠️ Sınırlı | | Gecikme | <1 saniye | 5-60 saniye (REST polling) | | WebSocket | ✅ Socket.io | ⚠️ Genellikle yok | | Fiyatlandırma | $0 - $99/ay | $50 - $500/ay |

📦 Özellikler

• 🥇 66+ sembol — Altın (gram & ons), gümüş, platin, paladyum, sarrafiye, döviz, parite
• ⚡ <1 saniye gecikme — Socket.io WebSocket ile anlık güncellemeler
• 🔒 Type-safe — Tam TypeScript tip desteği
• 📦 Evrensel — Node.js 18+, Bun, Deno, tarayıcı, edge runtime
• 🌐 REST + WebSocket — Tek pakette
• 🪶 Hafif — Tek bağımlılık (socket.io-client)

📥 Kurulum

npm install altinapi
# veya
yarn add altinapi
# veya
pnpm add altinapi
# veya
bun add altinapi

⚡ Hızlı Başlangıç

REST API — Anlık Fiyat Sorgusu

import { AltinapiClient } from 'altinapi';

const client = new AltinapiClient({ apiKey: 'hapi_API_KEYINIZ' });

// Tüm fiyatlar (Harem Altın ile aynı veri)
const tumu = await client.getAllPrices();
console.log(tumu.data);

// Kategori bazlı — sadece döviz
const doviz = await client.getPricesByCategory('DOVIZ');
console.log(doviz.data); // USDTRY, EURTRY, GBPTRY, CHFTRY, ...

// Tek sembol — gram altın
const altin = await client.getPrice('ALTIN');
console.log(`Altın: ${altin.bid} – ${altin.ask} TL/gram`);

// Sarrafiye — çeyrek altın
const ceyrek = await client.getPrice('CEYREK_YENI');
console.log(`Çeyrek altın: ${ceyrek.bid} – ${ceyrek.ask} TL`);

WebSocket — Gerçek Zamanlı Akış

import { AltinapiClient } from 'altinapi';

const client = new AltinapiClient({ apiKey: 'hapi_API_KEYINIZ' });

client.connect();

client.on('connect', () => {
  console.log('✅ Bağlandı');
  client.subscribe(['USDTRY', 'ALTIN', 'CEYREK_YENI']);
});

client.on('prices:snapshot', (fiyatlar) => {
  console.log('İlk snapshot:', fiyatlar);
});

client.on('prices:update', (guncellemeler) => {
  for (const f of guncellemeler) {
    // Harem Altın değişir değişmez sen de bilirsin
    console.log(`${f.symbol}: ${f.bid} / ${f.ask}`);
  }
});

client.on('data:stale', () => console.log('⚠️  Kaynak bağlantısı koptu'));
client.on('data:live', () => console.log('✅ Kaynak bağlantısı geri geldi'));

🏷️ Sembol Kategorileri

| Kategori | Açıklama | Örnekler | |---|---|---| | DOVIZ | Döviz kurları | USDTRY, EURTRY, GBPTRY, CHFTRY | | MADEN | Değerli metaller | ALTIN, XAUUSD, GUMUSD, PLATIN, PALADYUM | | GRAM ALTIN | Ağırlığa göre altın | 5 GR GRAM ALTIN, 10 GR GRAM ALTIN, ... | | SARRAFIYE | Türk sarrafiye altınları | CEYREK_YENI, YARIM_YENI, TEK_YENI, ATA_YENI, AYAR22 | | PARITE | Uluslararası pariteler | EURUSD, GBPUSD, USDJPY |

Tüm sembol listesi →

📚 Kullanım Senaryoları

altinapi şu senaryolarda kullanılır:

• Fintech uygulamaları — Anlık altın ve döviz fiyatlarını kullanıcıya göstermek
• Kuyumcu yazılımları — Stok yönetiminde gerçek zamanlı altın fiyatı kullanmak
• Mobil uygulamalar — Altın takip uygulamaları, döviz çevirici, portföy takipçisi
• Otomatik ticaret botları — Algorithmic trading için anlık fiyat akışı
• Karşılaştırma siteleri — Altın, döviz ve değerli metal fiyatlarını listelemek
• Dashboard'lar — Finansal panoda canlı veri göstermek
• WhatsApp / Telegram botları — Kullanıcılara güncel altın/döviz fiyatı bildirimi
• WordPress siteleri — Haber ve finans sitelerinde canlı fiyat widget'ı

📖 API Referansı

new AltinapiClient(options)

| Parametre | Tip | Varsayılan | Zorunlu | |---|---|---|---| | apiKey | string | — | ✅ | | baseUrl | string | https://altinapi.com/api/v1 | | | socketUrl | string | https://altinapi.com | | | timeout | number (ms) | 10000 | |

REST Metotları

| Metot | Dönüş | Açıklama | |---|---|---| | getAllPrices() | Promise<PricesResponse> | Tüm sembolleri getirir | | getPricesByCategory(category) | Promise<PricesResponse> | Kategori bazlı filtre | | getPrice(symbol) | Promise<Price> | Tek sembol fiyatı |

WebSocket Metotları

| Metot | Açıklama | |---|---| | connect() | Socket.io bağlantısı açar | | disconnect() | Bağlantıyı kapatır | | subscribe(symbols) | Belirli sembollere abone olur | | unsubscribe(symbols) | Aboneliği iptal eder | | on(event, handler) | Sunucu eventlerini dinler | | off(event, handler?) | Dinleyiciyi kaldırır | | isConnected() | Bağlantı durumunu döner |

WebSocket Eventleri

| Event | Veri | Ne zaman | |---|---|---| | connect | — | Bağlantı kuruldu | | disconnect | — | Bağlantı kapandı | | prices:snapshot | Price[] | Bağlantı anında — tüm güncel fiyatlar | | prices:update | Price[] | Fiyat değişiminde | | data:stale | — | Kaynak bağlantısı koptu (veri eski) | | data:live | — | Kaynak yeniden bağlandı | | connect_error | Error | Bağlantı hatası |

⚠️ Hata Yönetimi

import { AltinapiClient, AltinapiError } from 'altinapi';

try {
  await client.getPrice('GECERSIZ_SEMBOL');
} catch (err) {
  if (err instanceof AltinapiError) {
    console.error(`[${err.statusCode}] ${err.message}`);
  }
}

| Kod | Anlamı | |---|---| | 401 | API key eksik veya geçersiz | | 403 | Abonelik aktif değil | | 404 | Sembol veya kategori bulunamadı | | 429 | Rate limit aşıldı | | 503 | Kaynak bağlantısı kesildi (eski veri) |

💰 Plan Limitleri

| Plan | REST | WebSocket bağlantı | |---|---|---| | Ücretsiz Deneme | 30 / ay | — | | Starter | 30 / dakika | — | | Pro | 60 / dakika | 3 | | Enterprise | Özel | 10 |

Fiyatlandırma →

🔧 TypeScript Desteği

Tüm tipler paketle birlikte gelir:

import type { Price, PricesResponse, Category } from 'altinapi';

const fiyatIsle = (f: Price) => {
  // f.symbol, f.category, f.bid, f.ask, f.timestamp
};

const kategori: Category = 'DOVIZ'; // autocomplete çalışır

📂 Örnekler

Çalıştırılabilir örnekler /examples klasöründe:

• rest.ts — REST API kullanımı
• websocket.ts — gerçek zamanlı akış

tsx ile çalıştır:

ALTINAPI_KEY=hapi_xxx npx tsx examples/rest.ts

❓ Sık Sorulan Sorular

Bu Harem Altın'ın resmi API'si mi?

Hayır. altinapi bağımsız bir servistir. Harem Altın ile ortaklığı, iştiraki veya organik bir bağı yoktur. Fiyatlar birebir örtüşür çünkü aynı veri sağlayıcısından beslenir — bu teknik bir tesadüf değil, kullandığımız upstream data feed'in Harem Altın'ın kullandığı feed ile aynı kaynaktan gelmesi sebebiyledir.

"Harem Altın API'si" arıyorum, bu uygun mu?

altinapi, "Harem Altın API'si" arayan geliştiriciler için bağımsız bir alternatif olarak konumlandırılır. Harem Altın'ın kendisi geliştiricilere açık resmi bir API sunmadığı için, aynı fiyat verisine ihtiyaç duyan uygulamalar altinapi'yi kullanır.

SDK'yı kullanmak için ödeme yapmam gerek mi?

Hayır. Ücretsiz deneme planı 30 istek/ay sunar — entegrasyonu test etmek için yeterli. WebSocket erişimi Pro+ planlarda mevcut.

Veri ne kadar günceldir?

Fiyat değişikliklerinin sunucumuza ulaşması ile size iletilmesi arasındaki gecikme 1 saniyenin altındadır. WebSocket kullanırsanız yeni fiyat anında push edilir; REST kullanırsanız her sorguda son fiyatı alırsınız.

Tarayıcıda çalışır mı?

Evet. Paket modern tarayıcılarda, Edge runtime'larda (Vercel Edge, Cloudflare Workers), Bun ve Deno'da çalışır.

React Native ile çalışır mı?

Evet — RN projesinde npm install altinapi ile direkt kullanılabilir.

TCMB resmi kurları da var mı?

Şu an feed'imizde TCMB resmi kurları yer almıyor. İhtiyacınıza göre custom plan talep edebilirsiniz: [email protected]

🏷️ Bu Paketin Aranabilirliği

altinapi paketi şu aramalar için tasarlanmıştır:

altın fiyat API · altın fiyatları API · gram altın API · çeyrek altın API · sarrafiye API · döviz kuru API · döviz fiyat API · USDTRY API · EURTRY API · gerçek zamanlı altın fiyat · canlı altın fiyat API · Türkiye altın API · ons altın API · gümüş fiyat API · platin fiyat API · paladyum fiyat API · kuyumcu yazılımı API · altın takip uygulaması · Harem Altın benzeri API · Harem Altın alternatif API · Harem API · Türkiye finans API · Node.js altın API · TypeScript gold API · Turkish gold price API · websocket altın akışı

🤝 Katkıda Bulunma

Issue ve pull request'leriniz için: github.com/altinapi/altinapi-node

📄 Lisans

MIT © altinapi

🔗 Bağlantılar

• 🌐 Web sitesi: altinapi.com
• 📖 API Dokümantasyonu: altinapi.com/docs
• 🔑 Dashboard: altinapi.com/dashboard
• 📊 Durum: altinapi.com/status
• 💬 Destek: [email protected]

Yasal Bildirim: altinapi bağımsız bir hizmettir. "Harem Altın" tescilli bir markadır ve bu pakette yalnızca veri kaynağının aynılığını belirtmek amacıyla — karşılaştırma ve bilgilendirme amaçlı (nominative fair use) — kullanılmıştır. Marka sahibi ile herhangi bir ortaklık, iştirak veya destekleme ilişkisi yoktur.