Kripto portföy risk paneli, salt okunur API: örnek senaryo

Bu sayfa gerçek bir müşteri projesini değil, Fincode'un bu tür bir projede izlediği yaklaşımı gösteren örnek bir senaryoyu anlatır. Teknik ayrıntılar resmi kaynaklara dayanır; kapsam, süre ve fiyat her projede ayrıca belirlenir.

Proje özeti
Kim için	Birden fazla platformda hesabı bulunan bireysel yatırımcı (örnek senaryo)
Hizmet	Borsa API entegrasyonu
Platformlar	Okuma yetkili API anahtarı sunan kripto varlık platformları; Türkiye'de yerleşik kullanıcı için SPK'nın Faaliyette Bulunanlar Listesi'ndeki platformlar
Teknolojiler	REST ve WebSocket API'leri, ilişkisel veritabanı, şifreli gizli bilgi kasası, web paneli
Teslim	Bağlayıcılar, anahtar yetki doğrulaması, mutabakat işleri, risk paneli, alarm kuralları, güvenlik dokümantasyonu

İhtiyaç

Senaryodaki yatırımcının bakiyeleri ve pozisyonları birkaç platforma dağılmış durumda. Her platformun arayüzü yalnızca kendi hesabını gösterdiği için bir varlığa toplam maruziyet, toplam kâr/zarar ve en riskli pozisyon tek bakışta görülemiyor.

Panelin sınırı baştan çizilir: yalnızca okuma yetkili anahtarlarla çalışır, emir vermez, para çekmez ve yatırım önerisi üretmez. Vadeli pozisyon modülü yalnızca kullanıcının tabi olduğu mevzuatın ve platform koşullarının bu ürünlere izin verdiği durumlarda devreye girer. Türkiye'de faaliyet gösteren platformlarda III-35/B.2 sayılı Tebliğ'in 14. maddesine göre listelenen kripto varlıklar kaldıraçlı alınıp satılamaz ve türev sözleşmelere konu edilemez; 6362 sayılı Kanun'un 99/A maddesine göre de yurt dışında yerleşik platformların Türkiye'de yerleşik kişilere yönelik faaliyeti izinsiz kripto varlık hizmet sağlayıcılığı sayılır. Türkiye'de yerleşik bir kullanıcı için panel bu nedenle SPK'nın Faaliyette Bulunanlar Listesi (yeni sekmede açılır)'ndeki ve API sunan platformlardaki spot bakiyelerle sınırlı kurgulanır; listede yer almak yetkilendirme anlamına gelmez. Aşağıda geçen BtcTurk ve Paribu ayrıntıları, bu listedeki iki platformun resmi dokümanlarından alınmış örneklerdir; platform önerisi değildir.

Çözüm mimarisi ve veri modeli

Sistem üç katmandan oluşur: platform bağlayıcıları, normalleştirilmiş bir veri deposu ve web paneli.

Anahtarın salt okunur olduğunun doğrulanması

Kullanıcı bir anahtar eklediğinde bağlayıcı, platform bir yetki sorgulama uç noktası sunuyorsa önce anahtarın yetkilerini bu uç noktadan sorgular; okuma dışında yetkisi olan anahtar kaydedilmez. Yetkilerin yalnızca anahtar oluşturma ekranında belirlendiği durumlarda seçilecek izinler kurulum adımlarında gösterilir ve seçim için kullanıcıdan teyit alınır.

Platform	Kontrol	Kabul koşulu
Yetki sorgulama uç noktası sunan platform	Anahtar eklenirken yetki sorgusu	Yalnızca okuma yetkisi açık; işlem, transfer ve para çekme yetkisi veren tüm alanlar kapalı
Paribu	Anahtar oluşturma ekranı	Read-only izin seti; dokümana göre bu set hesap ve piyasa verisini okur, emir gönderemez
BtcTurk	Anahtar oluşturma ekranı	Toplam Varlık ve Hesap izinleri; açık emirleri okumak da emir göndermek de aynı Al-Sat iznine bağlı olduğu için bu izin verilmez

Veri modeli

Varlık	Temel alanlar
Hesap	Platform, alt hesap, anahtar referansı (anahtarın kendisi değil), son senkronizasyon zamanı
Bakiye görüntüsü	Varlık, serbest ve kilitli miktar, zaman damgası
Pozisyon	Enstrüman, yön, miktar, giriş fiyatı, işaret fiyatı, tasfiye fiyatı, marj modu, kaldıraç
Hareket	Gerçekleşmeler, ücretler, fonlama ödemeleri, transferler
Mutabakat kaydı	Karşılaştırma zamanı, bulunan fark, sonuç

Anlık değişiklikler, platform sunuyorsa özel WebSocket akışlarından alınır: BtcTurk'te kullanıcının gerçekleşmeleri UserTrade (423) mesajıyla gelir; Paribu'nun beta durumundaki özel akışı wss://api.paribu.com/v1/wapi/user adresindedir ve API anahtarıyla doğrulanır. Bunlara ek olarak düzenli REST anlık görüntüleri alınır.

Risk ölçütleri nasıl hesaplanır?

Maruziyet: Her varlığın tüm platformlardaki spot bakiyesi ile vadeli pozisyonlarının yönlü toplamı ve toplam portföy içindeki payı.
Kâr/zarar: Gerçekleşen kâr/zarar hareket kayıtlarından ve ortalama maliyetten, gerçekleşmemiş kâr/zarar güncel fiyattan hesaplanır; vadeli pozisyonlarda platformun bildirdiği değer ayrıca gösterilir.
Tasfiye fiyatına uzaklık: |işaret fiyatı − tasfiye fiyatı| ÷ işaret fiyatı.

Tasfiye fiyatı panelde yeniden hesaplanmaz, platformun bildirdiği değer kullanılır; çünkü marj kuralları platformdan platforma değişir. Bu değer bazı platformlarda tahminidir, bazı marj modlarında boş dönebilir; bu durumda panel tasfiye uzaklığı yerine hesap düzeyindeki marj bilgisini gösterir. Bu ölçütler yalnızca mevzuatı vadeli ürünlere izin veren kullanıcılar için açılan modülde geçerlidir; Türkiye'de yerleşik kullanıcı için kullanılmaz. Kavramlar kaldıraç ve likidasyon yazısında anlatılıyor.

Varsayımsal örnek
Kalem	Değer
İşaret fiyatı	50.000
Platformun bildirdiği tasfiye fiyatı	42.500
Tasfiye fiyatına uzaklık	(50.000 − 42.500) ÷ 50.000 = %15

Kullanıcının belirlediği eşik %20 ise bu varsayımsal pozisyon için alarm üretilir. Uzaklık son işlem fiyatına göre değil, işaret fiyatına göre hesaplanır.

Mutabakat ve güvenlik kontrolleri

Mutabakat

WebSocket olayları kaçırılabileceği için bakiyeler belirli aralıklarla REST anlık görüntüsüyle karşılaştırılır; BtcTurk'te GET /api/v1/users/balances free ve locked, Paribu'da GET /user/assets available ve locked alanlarını döndürür. Fark varsa REST değeri esas alınır ve olay kaydedilir.
Bir platformdan çıkıp diğerine henüz ulaşmamış transferler "yolda" olarak ayrı tutulur; aksi hâlde toplam portföy geçici olarak eksik görünür.
Senkronizasyonu belirlenen süreden uzun başarısız olan hesap panelde bayat olarak işaretlenir.
İstek limitleri gözetilir: Paribu kalan ağırlığı X-Quota-Remaining başlığında bildirir; BtcTurk ve Paribu limit aşımında 429 ve Retry-After başlığını döndürür.

Güvenlik

Anahtarlar kaynak kodda veya veritabanında düz metin olarak tutulmaz; şifreli bir gizli bilgi kasasında saklanır, erişim yalnızca bağlayıcı servise verilir ve her erişim kaydedilir. OWASP Secrets Management Cheat Sheet en az yetki, düzenli yenileme, süre sonu tanımlama ve sızıntıda hemen iptal ilkelerini önerir.
Platform destekliyorsa anahtarlar sunucu IP'leriyle sınırlandırılır; Paribu dokümanı IP izin listesini güvenlik için önerir. Platform anahtar için bir son kullanma tarihi bildiriyorsa panel bu tarih yaklaşınca kullanıcıyı uyarır.
Panel girişi iki faktörlü doğrulamayla korunur; anahtarlar günlük kayıtlarına yazılmaz. Fincode para çekme yetkisi talep etmez.

Test ve canlıya geçiş

Demo ortam: Ekranlar, platformun demo ortamı varsa orada, yoksa platformun belgelediği yanıtları taklit eden yerel bir sahte API ile üretilen örnek verilerle sınanır.
Karşılaştırma: Paneldeki bakiye, pozisyon, tasfiye fiyatı ve marj değerleri aynı anda platform arayüzündeki değerlerle karşılaştırılır.
Hata senaryoları: WebSocket kopması, fazla yetkili anahtar, süresi dolan anahtar, istek limiti aşımı ve platform bakımı yapay olarak üretilir.
Canlıya geçiş: Kullanıcının canlı hesaplarına okuma yetkili anahtarlarla bağlanılır; ilk aşamada mutabakat raporları düzenli olarak birlikte incelenir.

Teslim edilenler

Platform bağlayıcıları ve anahtar yetki doğrulaması
Normalleştirilmiş veri modeli ve mutabakat işleri
Bakiye, pozisyon, kâr/zarar, maruziyet ve tasfiye uzaklığı ekranlarını içeren web paneli
Eşikleri kullanıcının belirlediği alarm kuralları: tasfiye uzaklığı, marj oranı, varlık yoğunlaşması, bayat veri, anahtar süresi
Güvenlik dokümantasyonu, test raporu ve işletim kılavuzu

Panel mevcut bir uygulamaya bağlanacaksa entegrasyon bağımsız bir servis olarak kurulur; kapsam borsa API entegrasyonu sayfasında anlatılıyor. Anahtar ayarlarının ayrıntısı API anahtarı yazısında yer alıyor.

Başarı nasıl ölçülür?

Panelin başarısı, gösterdiği verinin platformlarla tutarlılığı ve güvenlik ilkelerine uyumuyla değerlendirilir; panel yatırım kararı vermez. Ölçütler şunlardır:

Test hesaplarında bakiye ve pozisyonların platform arayüzüyle eşleşmesi
Her mutabakat farkının kaydedilip açıklanabilmesi
Yetkileri API üzerinden sorgulanabilen platformlarda okuma dışında yetkisi olan hiçbir anahtarın sisteme kabul edilmemesi
Bayat veya eksik verinin kullanıcıya açıkça gösterilmesi
Alarmların tanımlı eşiklerde tetiklendiğinin test edilmiş olması

Sık sorulan sorular

Panel emir verebilir mi?

Hayır. Panel yalnızca okuma yetkili API anahtarlarıyla çalışır. Platform destekliyorsa anahtar eklenirken yetkileri API üzerinden sorgulanır ve işlem ya da para çekme yetkisi olan anahtarlar kabul edilmez.

Tasfiye fiyatı neden platformdakinden farklı görünebilir?

Panel tasfiye fiyatını yeniden hesaplamaz, platformun bildirdiği değeri kullanır. Fark çoğunlukla verinin alındığı an ile ekranın yenilendiği an arasındaki zamandan kaynaklanır; bazı hesap modlarında platform yalnızca tahmini bir değer verir veya hiç vermez.

Türkiye'de yerleşik kullanıcılar vadeli pozisyon modülünü kullanabilir mi?

Türkiye'de faaliyet gösteren platformlarda listelenen kripto varlıklar kaldıraçlı alınıp satılamaz ve türev sözleşmelere konu edilemez; yurt dışı platformların Türkiye'de yerleşik kişilere yönelik faaliyeti de 6362 sayılı Kanun'un 99/A maddesine göre izinsiz sayılır. Bu nedenle Türkiye'de yerleşik bir kullanıcı için panel spot bakiyelerle sınırlı kurgulanır.

API anahtarları nerede saklanır?

Şifreli bir gizli bilgi kasasında saklanır; kaynak kodda, veritabanında düz metin olarak veya günlük kayıtlarında yer almaz. Erişim yalnızca bağlayıcı servise verilir ve kayıt altına alınır.

Kaynaklar

Benzer bir proje mi planlıyorsunuz?

Kullanılan platformu, kapsamı ve takvimi kısa formla iletin; ön değerlendirmenin ardından yazılı teklif sunulur. Fincode bir yazılım geliştirme şirketidir; yatırım danışmanlığı, portföy yönetimi veya kripto varlık hizmet sağlayıcılığı yapmaz.

Hizmeti inceleyin Proje formunu doldurun