Kripto ile ilgili bir uygulama yazmaya başlayanların ilk karıştırdığı şey, iki farklı veri dünyasının varlığıdır. Bir tarafta fiyatlar vardır — borsalardan gelen, sürekli değişen piyasa verisi. Diğer tarafta zincirin kendisi vardır — cüzdanlar, işlemler, bloklar.
Bunlar farklı kaynaklardan gelir ve farklı sorunları çözer. Bitcoin'in fiyatını göstermek istiyorsanız piyasa verisi API'sine ihtiyacınız var; bu konuyu kripto piyasa verisi API'leri yazısında ele aldık. Bir kullanıcının cüzdanına ödeme geldiğini anlamak istiyorsanız on-chain API'ye ihtiyacınız var — bu yazının konusu odur.
Hızlı karşılaştırma
| Servis | Zincirler | Kimlik doğrulama | Öne çıkan yeteneği |
|---|---|---|---|
| BlockCypher | Bitcoin ve türevleri | Ücretsiz token | Webhook desteği |
| Blockchair | Çok zincirli | Kısıtlı kullanımda gerekmiyor | Gelişmiş sorgu ve arama |
| Helius | Solana | Ücretsiz anahtar | Zenginleştirilmiş işlem verisi |
| Solana JSON-RPC | Solana | Genel uç noktalarda gerekmiyor | Doğrudan zincir erişimi |
| TRON | TRON | Ücretsiz anahtar | Düşük ücretli stablecoin transferi |
| CryptAPI | Çoklu | Gerekmiyor | Ödeme yönlendirme |
Önce doğru soruyu sorun
On-chain API seçimi, zincir seçiminden sonra gelir. Hangi zincirle çalışacağınıza karar vermediyseniz API karşılaştırması yapmanın anlamı yoktur, çünkü çoğu sağlayıcı belirli zincirlerde uzmanlaşmıştır.
Zincir kararını genellikle şu belirler: kullanıcılarınız hangi ağda para tutuyor ve işlem ücreti ne kadar tolere edilebilir. Türkiye'de yaygın kullanım göz önüne alındığında, stablecoin transferleri için düşük ücretli ağlar pratikte öne çıkar; Bitcoin ise değer saklama ve tanınırlık açısından tercih edilir.
İkinci soru, verinin ne kadar derinine ineceğinizdir. Sadece bakiye okumak ile akıllı sözleşme durumunu çözümlemek arasında ciddi karmaşıklık farkı vardır ve bu, sağlayıcı seçiminizi değiştirir.
BlockCypher — Bitcoin tarafında webhook
BlockCypher, Bitcoin ve benzeri zincirler için adres, işlem ve blok verisi sunar. Ücretsiz bir token ile başlanabilir.
Ayrıştığı özellik webhook desteğidir ve bu, mimarinizi doğrudan etkiler. Bir adresi izlemek için iki yol vardır: düzenli aralıklarla sorgulamak veya olay olduğunda bildirim almak.
Sorgulama basittir ama iki maliyeti vardır. Gecikme — kullanıcı ödemesini yaptıktan sonra bir sonraki sorguya kadar bekler. Ve kota — hiçbir şey olmasa bile sürekli istek atarsınız. Yüz cüzdanı dakikada bir sorgulamak, günde yüz kırk dört bin istek eder ve bunların neredeyse tamamı boş döner.
Webhook bu iki sorunu da çözer. Adresi kaydedersiniz, para geldiğinde size bildirim gelir. Karşılığında dışarıdan erişilebilir bir uç nokta çalıştırmanız ve gelen bildirimlerin gerçekten sağlayıcıdan geldiğini doğrulamanız gerekir. Bu doğrulamayı atlamak ciddi bir güvenlik açığıdır: doğrulanmamış bir webhook uç noktası, sahte "ödeme alındı" bildirimleri göndermeye açıktır.
Blockchair — çok zincirli ve sorgulanabilir
Blockchair, birden fazla zinciri tek ve tutarlı bir arayüz üzerinden sunar. Farklı zincirlerde aynı sorguyu yapmak için ayrı entegrasyonlar yazmanız gerekmez.
Asıl gücü sorgulama yeteneğidir. Basit "bu adresin bakiyesi ne" sorusunun ötesine geçer; filtreleme, sıralama ve toplulaştırma yapabilirsiniz. Analiz veya raporlama yapan bir uygulamada bu, veriyi çekip kendi tarafınızda işlemenize kıyasla büyük tasarruf sağlar.
Kısıtlı kullanımda anahtar gerektirmemesi, keşif ve prototip aşamasını hızlandırır. Ciddi hacim için ücretli plana geçmeniz beklenir; ücretsiz kullanımın sınırlarını dokümantasyondan doğrulayın.
Solana: JSON-RPC ve Helius
Solana tarafında iki farklı yaklaşım vardır ve ikisi birbirini tamamlar.
Solana JSON-RPC, zincirin standart arayüzüdür. Genel uç noktalar üzerinden anahtarsız erişilebilir. Ham ve doğrudandır: hesap durumu, işlem detayı, blok bilgisi. Standart olduğu için sağlayıcı değiştirmek kolaydır — aynı çağrılar farklı bir uç noktada da çalışır.
Sınırı da ham olmasıdır. Solana işlemleri, okunması zor bir yapıda döner; bir token transferinin kimden kime ne kadar olduğunu anlamak için talimatları çözümlemeniz gerekir. Genel uç noktalar ayrıca oran sınırlıdır ve üretim yükü için tasarlanmamıştır.
Helius tam bu boşluğu doldurur. Ham işlemi çözümleyip anlaşılır bir yapıya dönüştürür: "şu cüzdandan şu cüzdana şu kadar USDC gönderildi". Kendi çözümleme katmanınızı yazmaktan kurtarır ve bu, Solana entegrasyonunda en çok zaman alan kısımdır.
Pratik yaklaşım şudur: standart RPC çağrılarını kullanın ki sağlayıcı bağımlılığınız düşük kalsın, ancak işlem çözümleme gibi ağır işlerde zenginleştirilmiş servisten yararlanın.
TRON — stablecoin transferlerinin yoğun olduğu ağ
TRON, düşük işlem ücreti nedeniyle stablecoin transferlerinde yoğun kullanılan bir ağdır. Türkiye'de kullanıcılar arası transferlerde bu ağın tercih edildiği senaryolar yaygındır.
Geliştirici açısından bilinmesi gereken kendine özgü bir kavramı vardır: enerji ve bant genişliği. TRON'da işlem ücreti doğrudan bakiyeden düşülmez; hesabın kaynak kotası üzerinden hesaplanır ve kota yetmediğinde token yakılır. Kullanıcıya "işlem ücreti şu kadar" demeye çalışan bir arayüz kuruyorsanız bu modeli anlamadan doğru sayı gösteremezsiniz.
Adres formatı da farklıdır ve iki gösterimi vardır. Kullanıcıya gösterdiğiniz format ile zincirde kullanılan format arasındaki dönüşümü doğru yapmazsanız, teknik olarak geçerli ama yanlış adrese işlem yapılabilir. Adres doğrulamayı asla atlamayın.
CryptAPI — ödeme almak için ara katman
CryptAPI, diğerlerinden farklı bir işi çözer. Zincir verisi okumak yerine, ödeme almanızı kolaylaştırır.
Çalışma mantığı şudur: her sipariş için geçici bir adres üretirsiniz, müşteri oraya öder, servis parayı sizin asıl adresinize yönlendirir ve size bildirim gönderir. Kendi cüzdan altyapınızı kurmadan kripto ödeme kabul etmenizi sağlar.
Avantajı, adres yönetimi ve ödeme eşleştirme gibi hataya açık işleri devralmasıdır. Her siparişe ayrı adres vermek, ödemeyi siparişle eşleştirmenin en güvenilir yoludur ve bunu elle kurmak sandığınızdan zordur.
Dezavantajı, ödeme akışınıza üçüncü bir taraf eklemenizdir. Para akışının içinde duran bir servisin güvenilirliği, bir veri servisinden çok daha kritik bir konudur. Ticari kullanımda koşullarını, ücretlerini ve sorumluluk sınırlarını dikkatle inceleyin.
Türkiye'de kripto ödeme kabul etmeyi düşünüyorsanız, teknik entegrasyondan önce hukuki tarafı netleştirin. Ödemelerde kripto varlık kullanımına ilişkin düzenlemeler mevcuttur ve bu, teknik olarak mümkün olan her akışın yasal olarak uygulanabilir olmadığı anlamına gelir. Geleneksel ödeme entegrasyonları için Türkiye SaaS ödeme API'leri yazısına bakabilirsiniz.
Onay sayısı ve kesinlik
On-chain uygulamalarda en sık yapılan mantık hatası, bir işlemi zincirde görür görmez tamamlanmış saymaktır.
Bir işlem zincire girdiğinde henüz kesinleşmiş değildir. Yeni bloklar eklendikçe geri dönme olasılığı azalır. Kaç onay bekleyeceğiniz teknik bir sabit değil, bir risk kararıdır: tutar ne kadar yüksekse o kadar çok onay beklemek mantıklıdır.
Uygulamanızda bu eşiği sabit kodlamayın, yapılandırılabilir tutun. Kullanıcı arayüzünde de "bekleyen" ve "onaylanan" durumlarını ayrı gösterin. Kullanıcı parasını gönderdikten sonra hiçbir geri bildirim almazsa ödemeyi tekrarlar; "alındı, onay bekleniyor (2/6)" göstermek bu sorunu tamamen ortadan kaldırır.
Türk Lirası karşılığı ve kayıt tutma
On-chain API'ler size kripto birimi verir — 0.05 BTC, 250 USDT. Türk Lirası karşılığını vermezler. Bu dönüşüm için ayrı bir piyasa verisi kaynağı gerekir.
Burada muhasebe açısından kritik bir ayrıntı vardır: dönüşümü yaptığınız anın kurunu kaydedin. Geçmiş bir işlemi bugünkü kurla göstermek, hem kullanıcıyı yanıltır hem de kayıtlarınızı tutarsız hale getirir. İşlem kaydında kripto tutarı, TL karşılığı ve dönüşümde kullanılan kur ile zaman damgası ayrı alanlar olarak durmalıdır.
TL kuru için kaynak seçimi de önemlidir. Yerel borsa fiyatı ile global fiyat arasında fark olabilir. Kullanıcılarınız Türkiye'deyse yerel piyasayı yansıtan bir kaynak kullanmak daha doğru sonuç verir.
Veri modeli ve dayanıklılık
On-chain veriyle çalışan bir uygulamada veri modelinizin şu alanları ayırması işinizi kolaylaştırır: zincir adı, işlem karması, blok yüksekliği, onay sayısı, gönderen ve alıcı adresleri, ham tutar, token bilgisi ve ham yanıt.
Ham yanıtı saklamak özellikle değerlidir. Sağlayıcı değiştirdiğinizde veya bir hatayı araştırdığınızda, elinizde orijinal veri olması sizi yeniden veri çekmekten kurtarır.
Sağlayıcı bağımlılığını da baştan düşünün. Ücretsiz katmanlar üzerine kurulu bir sistem, sağlayıcı politikasını değiştirdiğinde kırılır. Standart RPC çağrılarını tercih etmek ve sağlayıcıya özgü özellikleri ayrı bir katmanda tutmak, geçiş maliyetini düşük tutar.
Son olarak, işlem karması üzerinde tekillik kısıtı koyun. Aynı işlemi iki kez kaydetmek, özellikle webhook ve sorgulama yöntemlerini birlikte kullandığınızda kolayca olur ve çift ödeme kaydı gibi ciddi sonuçlar doğurur.
Bu yazıdaki erişim ve limit bilgileri yayın tarihindeki resmi dokümantasyona dayanır. Bu kategoride sağlayıcı politikaları görece sık değiştiği için, üretime almadan önce güncel koşulları doğrulayın.
İlgili API Deposu kayıtları
Kaynaklar
Sık Sorulan Sorular
›On-chain API ile piyasa verisi API'si arasındaki fark nedir?
Piyasa verisi API'leri fiyat, hacim ve piyasa değeri gibi borsa kaynaklı bilgileri verir. On-chain API'ler ise zincirin kendisini okur: cüzdan bakiyeleri, işlemler, bloklar ve akıllı sözleşme durumu. Bir coin'in fiyatını göstermek için piyasa verisi, bir kullanıcının cüzdanına para geldiğini anlamak için on-chain gerekir.
›Kendi düğümümü çalıştırmam gerekir mi?
Çoğu uygulama için gerekmez. Barındırılan RPC ve API sağlayıcıları düşük hacimde ücretsiz erişim sunar. Kendi düğümünüz yüksek hacim, düşük gecikme veya üçüncü tarafa bağımlı olmama gerekliliği doğduğunda anlamlı hale gelir; karşılığında ciddi disk, bant genişliği ve bakım maliyeti üstlenirsiniz.
›Cüzdana para geldiğini nasıl anlarım?
İki yöntem vardır. Adresi düzenli aralıklarla sorgulamak basittir ama gecikmelidir ve kota tüketir. Webhook kaydı ise olay gerçekleştiğinde size bildirim gönderir; daha verimlidir fakat dışarıdan erişilebilir bir uç nokta ve doğrulama katmanı gerektirir.
›Bir işlem kaç onay sonrası kesinleşmiş sayılır?
Bu zincire ve tutara göre değişen bir risk kararıdır, teknik bir sabit değil. Düşük tutarlarda az onay kabul edilebilirken, yüksek tutarlarda daha fazla onay beklenir. Uygulamanızda bu eşiği yapılandırılabilir tutun ve kullanıcıya bekleyen/onaylanan durumunu ayrı gösterin.
›Türk Lirası karşılığını nasıl gösteririm?
On-chain API'ler kripto birimini verir, fiyat vermez. TL karşılığı için ayrı bir piyasa verisi kaynağı gerekir ve dönüşümü yaptığınız anın kurunu kaydetmelisiniz. Geçmiş bir işlemi bugünkü kurla göstermek muhasebe açısından yanlış sonuç üretir.