Skip to content

Commit a35295d

Browse files
notmymindnotmymind
committed
Initial release v0.1.0
0 parents  commit a35295d

10 files changed

Lines changed: 2525 additions & 0 deletions

File tree

‎.gitignore‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
# Dependencies
2+
node_modules/
3+
.pnp
4+
.pnp.js
5+
6+
# Build output
7+
dist/
8+
build/
9+
*.tsbuildinfo
10+
11+
# Testing
12+
coverage/
13+
.nyc_output/
14+
15+
# Environment
16+
.env
17+
.env.local
18+
.env.*.local
19+
20+
# Logs
21+
npm-debug.log*
22+
yarn-debug.log*
23+
yarn-error.log*
24+
pnpm-debug.log*
25+
.npm
26+
27+
# Editor
28+
.vscode/
29+
.idea/
30+
*.swp
31+
*.swo
32+
.DS_Store
33+
34+
# OS
35+
Thumbs.db

‎LICENSE‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) 2026 altinapi
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

‎README.md‎

Lines changed: 325 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,325 @@
1+
# altinapi — Türkiye Altın & Döviz Fiyat API'si
2+
3+
[![npm version](https://img.shields.io/npm/v/altinapi.svg)](https://www.npmjs.com/package/altinapi)
4+
[![npm downloads](https://img.shields.io/npm/dm/altinapi.svg)](https://www.npmjs.com/package/altinapi)
5+
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
6+
[![TypeScript](https://img.shields.io/badge/-TypeScript-3178C6?logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
7+
8+
> **[altinapi](https://altinapi.com)** için resmi Node.js / TypeScript SDK
9+
>
10+
> **Gerçek zamanlı altın fiyatları, döviz kurları, gümüş, platin, paladyum ve sarrafiye verisi** — REST API ve WebSocket ile.
11+
12+
---
13+
14+
## 🎯 Harem Altın ile Birebir Aynı Fiyat Verisi
15+
16+
**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**.
17+
18+
> ⚖️ **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.
19+
20+
[🔑 Ücretsiz API key al →](https://altinapi.com)
21+
22+
---
23+
24+
## 🚀 Niye altinapi?
25+
26+
| | altinapi | Diğer altın fiyat API'leri |
27+
|---|---|---|
28+
| **Veri kaynağı** | Harem Altın ile aynı feed | Genelde LBMA / international ons |
29+
| **Sarrafiye desteği** | ✅ Çeyrek, yarım, tam, ata, gremese | ❌ Yok |
30+
| **22/14 ayar** | ✅ Var | ❌ Yok |
31+
| **Gram altın (5/10/20/50/100 gr)** | ✅ Var | ❌ Yok |
32+
| **Türk lirası pariteleri** | ✅ 15+ döviz | ⚠️ Sınırlı |
33+
| **Gecikme** | <1 saniye | 5-60 saniye (REST polling) |
34+
| **WebSocket** | ✅ Socket.io | ⚠️ Genellikle yok |
35+
| **Fiyatlandırma** | $0 - $99/ay | $50 - $500/ay |
36+
37+
---
38+
39+
## 📦 Özellikler
40+
41+
- 🥇 **66+ sembol** — Altın (gram & ons), gümüş, platin, paladyum, sarrafiye, döviz, parite
42+
- ⚡ **<1 saniye gecikme** — Socket.io WebSocket ile anlık güncellemeler
43+
- 🔒 **Type-safe** — Tam TypeScript tip desteği
44+
- 📦 **Evrensel** — Node.js 18+, Bun, Deno, tarayıcı, edge runtime
45+
- 🌐 **REST + WebSocket** — Tek pakette
46+
- 🪶 **Hafif** — Tek bağımlılık (socket.io-client)
47+
48+
---
49+
50+
## 📥 Kurulum
51+
52+
```bash
53+
npm install altinapi
54+
# veya
55+
yarn add altinapi
56+
# veya
57+
pnpm add altinapi
58+
# veya
59+
bun add altinapi
60+
```
61+
62+
---
63+
64+
## ⚡ Hızlı Başlangıç
65+
66+
### REST API — Anlık Fiyat Sorgusu
67+
68+
```ts
69+
import { AltinapiClient } from 'altinapi';
70+
71+
const client = new AltinapiClient({ apiKey: 'hapi_API_KEYINIZ' });
72+
73+
// Tüm fiyatlar (Harem Altın ile aynı veri)
74+
const tumu = await client.getAllPrices();
75+
console.log(tumu.data);
76+
77+
// Kategori bazlı — sadece döviz
78+
const doviz = await client.getPricesByCategory('DOVIZ');
79+
console.log(doviz.data); // USDTRY, EURTRY, GBPTRY, CHFTRY, ...
80+
81+
// Tek sembol — gram altın
82+
const altin = await client.getPrice('ALTIN');
83+
console.log(`Altın: ${altin.bid} – ${altin.ask} TL/gram`);
84+
85+
// Sarrafiye — çeyrek altın
86+
const ceyrek = await client.getPrice('CEYREK_YENI');
87+
console.log(`Çeyrek altın: ${ceyrek.bid} – ${ceyrek.ask} TL`);
88+
```
89+
90+
### WebSocket — Gerçek Zamanlı Akış
91+
92+
```ts
93+
import { AltinapiClient } from 'altinapi';
94+
95+
const client = new AltinapiClient({ apiKey: 'hapi_API_KEYINIZ' });
96+
97+
client.connect();
98+
99+
client.on('connect', () => {
100+
console.log('✅ Bağlandı');
101+
client.subscribe(['USDTRY', 'ALTIN', 'CEYREK_YENI']);
102+
});
103+
104+
client.on('prices:snapshot', (fiyatlar) => {
105+
console.log('İlk snapshot:', fiyatlar);
106+
});
107+
108+
client.on('prices:update', (guncellemeler) => {
109+
for (const f of guncellemeler) {
110+
// Harem Altın değişir değişmez sen de bilirsin
111+
console.log(`${f.symbol}: ${f.bid} / ${f.ask}`);
112+
}
113+
});
114+
115+
client.on('data:stale', () => console.log('⚠️ Kaynak bağlantısı koptu'));
116+
client.on('data:live', () => console.log('✅ Kaynak bağlantısı geri geldi'));
117+
```
118+
119+
---
120+
121+
## 🏷️ Sembol Kategorileri
122+
123+
| Kategori | Açıklama | Örnekler |
124+
|---|---|---|
125+
| `DOVIZ` | Döviz kurları | `USDTRY`, `EURTRY`, `GBPTRY`, `CHFTRY` |
126+
| `MADEN` | Değerli metaller | `ALTIN`, `XAUUSD`, `GUMUSD`, `PLATIN`, `PALADYUM` |
127+
| `GRAM ALTIN` | Ağırlığa göre altın | `5 GR GRAM ALTIN`, `10 GR GRAM ALTIN`, ... |
128+
| `SARRAFIYE` | Türk sarrafiye altınları | `CEYREK_YENI`, `YARIM_YENI`, `TEK_YENI`, `ATA_YENI`, `AYAR22` |
129+
| `PARITE` | Uluslararası pariteler | `EURUSD`, `GBPUSD`, `USDJPY` |
130+
131+
[Tüm sembol listesi →](https://altinapi.com/docs#symbols)
132+
133+
---
134+
135+
## 📚 Kullanım Senaryoları
136+
137+
altinapi şu senaryolarda kullanılır:
138+
139+
- **Fintech uygulamaları** — Anlık altın ve döviz fiyatlarını kullanıcıya göstermek
140+
- **Kuyumcu yazılımları** — Stok yönetiminde gerçek zamanlı altın fiyatı kullanmak
141+
- **Mobil uygulamalar** — Altın takip uygulamaları, döviz çevirici, portföy takipçisi
142+
- **Otomatik ticaret botları** — Algorithmic trading için anlık fiyat akışı
143+
- **Karşılaştırma siteleri** — Altın, döviz ve değerli metal fiyatlarını listelemek
144+
- **Dashboard'lar** — Finansal panoda canlı veri göstermek
145+
- **WhatsApp / Telegram botları** — Kullanıcılara güncel altın/döviz fiyatı bildirimi
146+
- **WordPress siteleri** — Haber ve finans sitelerinde canlı fiyat widget'ı
147+
148+
---
149+
150+
## 📖 API Referansı
151+
152+
### `new AltinapiClient(options)`
153+
154+
| Parametre | Tip | Varsayılan | Zorunlu |
155+
|---|---|---|---|
156+
| `apiKey` | string | — | ✅ |
157+
| `baseUrl` | string | `https://altinapi.com/api/v1` | |
158+
| `socketUrl` | string | `https://altinapi.com` | |
159+
| `timeout` | number (ms) | `10000` | |
160+
161+
### REST Metotları
162+
163+
| Metot | Dönüş | Açıklama |
164+
|---|---|---|
165+
| `getAllPrices()` | `Promise<PricesResponse>` | Tüm sembolleri getirir |
166+
| `getPricesByCategory(category)` | `Promise<PricesResponse>` | Kategori bazlı filtre |
167+
| `getPrice(symbol)` | `Promise<Price>` | Tek sembol fiyatı |
168+
169+
### WebSocket Metotları
170+
171+
| Metot | Açıklama |
172+
|---|---|
173+
| `connect()` | Socket.io bağlantısı açar |
174+
| `disconnect()` | Bağlantıyı kapatır |
175+
| `subscribe(symbols)` | Belirli sembollere abone olur |
176+
| `unsubscribe(symbols)` | Aboneliği iptal eder |
177+
| `on(event, handler)` | Sunucu eventlerini dinler |
178+
| `off(event, handler?)` | Dinleyiciyi kaldırır |
179+
| `isConnected()` | Bağlantı durumunu döner |
180+
181+
### WebSocket Eventleri
182+
183+
| Event | Veri | Ne zaman |
184+
|---|---|---|
185+
| `connect` | — | Bağlantı kuruldu |
186+
| `disconnect` | — | Bağlantı kapandı |
187+
| `prices:snapshot` | `Price[]` | Bağlantı anında — tüm güncel fiyatlar |
188+
| `prices:update` | `Price[]` | Fiyat değişiminde |
189+
| `data:stale` | — | Kaynak bağlantısı koptu (veri eski) |
190+
| `data:live` | — | Kaynak yeniden bağlandı |
191+
| `connect_error` | `Error` | Bağlantı hatası |
192+
193+
---
194+
195+
## ⚠️ Hata Yönetimi
196+
197+
```ts
198+
import { AltinapiClient, AltinapiError } from 'altinapi';
199+
200+
try {
201+
await client.getPrice('GECERSIZ_SEMBOL');
202+
} catch (err) {
203+
if (err instanceof AltinapiError) {
204+
console.error(`[${err.statusCode}] ${err.message}`);
205+
}
206+
}
207+
```
208+
209+
| Kod | Anlamı |
210+
|---|---|
211+
| `401` | API key eksik veya geçersiz |
212+
| `403` | Abonelik aktif değil |
213+
| `404` | Sembol veya kategori bulunamadı |
214+
| `429` | Rate limit aşıldı |
215+
| `503` | Kaynak bağlantısı kesildi (eski veri) |
216+
217+
---
218+
219+
## 💰 Plan Limitleri
220+
221+
| Plan | REST | WebSocket bağlantı |
222+
|---|---|---|
223+
| Ücretsiz Deneme | 30 / ay | — |
224+
| Starter | 30 / dakika | — |
225+
| Pro | 60 / dakika | 3 |
226+
| Enterprise | Özel | 10 |
227+
228+
[Fiyatlandırma →](https://altinapi.com/#fiyatlandirma)
229+
230+
---
231+
232+
## 🔧 TypeScript Desteği
233+
234+
Tüm tipler paketle birlikte gelir:
235+
236+
```ts
237+
import type { Price, PricesResponse, Category } from 'altinapi';
238+
239+
const fiyatIsle = (f: Price) => {
240+
// f.symbol, f.category, f.bid, f.ask, f.timestamp
241+
};
242+
243+
const kategori: Category = 'DOVIZ'; // autocomplete çalışır
244+
```
245+
246+
---
247+
248+
## 📂 Örnekler
249+
250+
Çalıştırılabilir örnekler [`/examples`](./examples) klasöründe:
251+
252+
- [`rest.ts`](./examples/rest.ts) — REST API kullanımı
253+
- [`websocket.ts`](./examples/websocket.ts) — gerçek zamanlı akış
254+
255+
`tsx` ile çalıştır:
256+
257+
```bash
258+
ALTINAPI_KEY=hapi_xxx npx tsx examples/rest.ts
259+
```
260+
261+
---
262+
263+
## ❓ Sık Sorulan Sorular
264+
265+
### Bu Harem Altın'ın resmi API'si mi?
266+
267+
**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.
268+
269+
### "Harem Altın API'si" arıyorum, bu uygun mu?
270+
271+
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.
272+
273+
### SDK'yı kullanmak için ödeme yapmam gerek mi?
274+
275+
Hayır. Ücretsiz deneme planı 30 istek/ay sunar — entegrasyonu test etmek için yeterli. WebSocket erişimi Pro+ planlarda mevcut.
276+
277+
### Veri ne kadar günceldir?
278+
279+
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.
280+
281+
### Tarayıcıda çalışır mı?
282+
283+
Evet. Paket modern tarayıcılarda, Edge runtime'larda (Vercel Edge, Cloudflare Workers), Bun ve Deno'da çalışır.
284+
285+
### React Native ile çalışır mı?
286+
287+
Evet — RN projesinde `npm install altinapi` ile direkt kullanılabilir.
288+
289+
### TCMB resmi kurları da var mı?
290+
291+
Şu an feed'imizde TCMB resmi kurları yer almıyor. İhtiyacınıza göre custom plan talep edebilirsiniz: [support@altinapi.com](mailto:support@altinapi.com)
292+
293+
---
294+
295+
## 🏷️ Bu Paketin Aranabilirliği
296+
297+
altinapi paketi şu aramalar için tasarlanmıştır:
298+
299+
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ışı
300+
301+
---
302+
303+
## 🤝 Katkıda Bulunma
304+
305+
Issue ve pull request'leriniz için: [github.com/altinapi/altinapi-node](https://github.com/altinapi/altinapi-node)
306+
307+
---
308+
309+
## 📄 Lisans
310+
311+
MIT © [altinapi](https://altinapi.com)
312+
313+
---
314+
315+
## 🔗 Bağlantılar
316+
317+
- 🌐 Web sitesi: [altinapi.com](https://altinapi.com)
318+
- 📖 API Dokümantasyonu: [altinapi.com/docs](https://altinapi.com/docs)
319+
- 🔑 Dashboard: [altinapi.com/dashboard](https://altinapi.com/dashboard)
320+
- 📊 Durum: [altinapi.com/status](https://altinapi.com/status)
321+
- 💬 Destek: [support@altinapi.com](mailto:support@altinapi.com)
322+
323+
---
324+
325+
> **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.

0 commit comments

Comments
 (0)