Zincir üstü veri API'si: balina transferleri, borsa akışları ve token kilit açılımları
Kısaca
- Zincir üstü veri API'si, çözülmüş blokzincir olaylarını döndürür: hangi token, kimden kime ve kaç dolarlık hareket etti. Ham veri node'lardan gelir, indexer'lar onu tablolara çevirir, adres etiketleri ise yanlış olabilecek birer atıf olarak kalır.
- Trader'lar borsa girişlerini ve çıkışlarını, büyük transferleri, ekip cüzdanı hareketlerini, perp DEX pozisyonlarını, kilit açılımlarını, claim'leri, hack'leri ve büyük DEX swap'larını izler. Borsaya yapılan bir yatırım her zaman satışla sonuçlanmaz.
- Genesis API'de dokuz zincir üstü bölüm Start planından itibaren açıktır; DEX swap'ları, analitik ve coin özeti için Pro veya Max gerekir. Bölümlerde zaman parametresi olmadığı için pencereyi ve akış toplamlarını kodunuz hesaplar.
Zincir üstü veri API'si, daha önce toplanmış, dolara çevrilmiş ve etiketlenmiş blokzincir olaylarına açılan bir HTTP arayüzüdür: hangi token, hangi adresten hangi adrese ve hangi işlemle hareket etti. Böyle bir API ile kendi node'unuzu veya indexer'ınızı çalıştırmadan balina transferlerini, borsa girişlerini, token kilit açılımlarını ve DEX üzerindeki büyük swap'ları izleyebilirsiniz. Burada balina, transferleri piyasayı oynatacak kadar coin tutan adrestir.
Zincir üstü veri nereden gelir
Veri üç katmandan geçer: node blokları saklar, indexer bunları olay satırlarına çevirir, etiket veritabanı ise adreslere isim verir.
Node: bloklar ve log'lar
Blokzincir node'u blokları saklar ve JSON-RPC üzerinden sunar. Ethereum'da ve uyumlu zincirlerde bir ERC-20 token transferi, işlem log'una Transfer(address indexed _from, address indexed _to, uint256 _value) olayı olarak yazılır; standart, yeni token basıldığında aynı olayın gönderen olarak 0x0 ile yayımlanmasını önerir (EIP-20).
eth_getLogs yöntemi bir filtreye uyan log'ları döndürür: fromBlock ve toBlock blok aralığı, bir sözleşme address'i ve olay topics'i (Ethereum JSON-RPC). Bir log adresleri, blok numarasını, işlem hash'ini ve tutarı token'ın en küçük birimleriyle içerir. Blokta dolar fiyatı, sahip adı ve borsa işareti yoktur.
Indexer: log'lardan tablolara
Indexer blokları sırayla okur, olayları çözer ve tablolara dağıtır: transferler, swap'lar, havuz değişiklikleri. Tutarı token'ın decimals değerinin 10 üssüne böler (sekiz ondalıkta bu, 100.000.000'a bölmek demektir) ve blok anındaki fiyatla çarpar; sonuç dolar değeridir.
Ardından eşikler gelir: akış belirli bir tutarın üzerindeki transferleri tutar, tek bir adrese giden küçük transfer serileri tek satırda birleştirilir. Birkaç zincir için böyle bir hat kurmak başlı başına bir projedir; zincir üstü veri API'si bunun çıktısını tek istekte döndürür.
Adres etiketleri: adresin arkasında kim var
Etiket, bir adrese bağlanan bir isimdir: "Binance", "proje hazinesi", "piyasa yapıcı". Kanıtlara göre atanır: adres coin'leri bilinen bir borsa cüzdanına yönlendirir, proje adreslerini kendisi yayımlamıştır, adres bir vesting sözleşmesinden token almıştır. Bunların hiçbirini sahip onaylamaz; bu yüzden etiket eski kalmış veya yanlış olabilir.
Kanıtı olmayan adres isimsiz kalır: Genesis API dokümantasyonundaki örneklerde böyle bir gönderen kısaltılmış adresle görünür, 0xec01…d1a5.
Trader'lar için hangi zincir üstü olaylar önemli
Varsayımsal bir örnek: bir sabah içinde bir projenin 2.000.000 $ değerinde coin'i borsalara gitti ve ekip cüzdanından 500.000 $ bir piyasa yapıcının adresine çıktı. Her olay tek başına az şey söyler; birlikte fiyatı, açık pozisyonu ve kilit açılımı takvimini kontrol etmek için bir nedendir.
| Olay | Ne görürsünüz | Genelde nasıl okunur |
|---|---|---|
| Borsaya yatırma | Coin'ler bir borsa adresine gelir | Olası satış, teminat veya yer değiştirme |
| Borsadan çekme | Coin'ler harici bir adrese çıkar | Saklama, DeFi veya başka bir borsa |
| Büyük transfer | Adresler arasında eşiğin üzerinde bir transfer | Bir balina pozisyonunu taşır |
| Ekip cüzdanı | Vakıf, hazine veya kurucu adreslerinden hareketler | Borsaya yatırma, iç hareketten daha ağırdır |
| Perp DEX pozisyonu | Long veya short: boyut, fiyat, platform | Bir balinanın bahsi ve likidasyon riski |
| Kilit açılımı | Serbest bırakmanın tarihi, payı ve değeri | Coin'in yeni arzı |
| Claim | Airdrop, vesting veya ödüllerden gelen token'lar | Alıcılar hemen satabilir |
| Mint ve köprü | Token basımı, zincirler arası hareket | Stablecoin basımı, para girişi demektir |
| Hack | Protokol, kayıplar, saldırı tekniği | Token ve bağlı zincirler için risk |
| DEX swap | Yön, tutar, havuz payı, fiyat hareketi | Borsalar tepki vermeden önce fiyat kayması |
Sürekli vadeli işlemler için merkezsiz borsalardaki pozisyonlar, yani perp DEX'ler, görünür çünkü bu platformlar verilerini açık tutar. Hyperliquid'de POST https://api.hyperliquid.xyz/info info endpoint'i, clearinghouseState isteğiyle herhangi bir adresin açık pozisyonlarını ve marjinini anahtarsız döndürür (Hyperliquid dokümanları). CEX'ler diğer trader'ların pozisyonlarını yayımlamaz; açık pozisyon gibi toplu rakamlar verir.
Kilit açılımı, ekip, yatırımcı veya vakıf token'larının, belirli bir takvimle dilimler halinde dağıtan vesting planı uyarınca serbest bırakılmasıdır. Tarih önceden bilindiği için piyasa satışı olaydan önce fiyatlayabilir.
Bir DEX swap'ı havuz fiyatını aynı blokta oynatır. Varsayımsal bir örnek: 1.200.000 $ likiditeli bir havuzda 150.000 $'lık alım, havuzun 150.000 / 1.200.000 × 100 = %12,5'ini alır. Havuz fiyatı belirgin biçimde kayar, borsalarda ise hareket daha geç görünür ya da hiç görünmez. DEX ve CEX fiyatlarının karşılaştırması DEX API makalesinde anlatılıyor.
Hack zincir üstünde, bir protokolün sözleşmesinden çıkan transferler olarak görünür. Köprüler diğer protokollerden daha sık saldırıya uğrar çünkü sözleşmeleri büyük tutarlar tutar: önemli vakalar blokzincir köprüleri makalesinde, bir borsadan yapılan hırsızlık ise Bybit hack'i incelemesinde yer alıyor.
Gecikme ve onay
Bir işlemle kodunuzdaki satır arasında saniyelerden dakikalara kadar süre geçer; bu veri gecikmesidir. Günlük akış özeti için pek önemli değildir, ancak tek bir büyük yatırmaya veya swap'a tepki verdiğinizde sonucu belirler.
Ağ onayı
Ethereum'da yeni bir blok her slot'ta, yani 12 saniyede bir çıkabilir ve yaklaşık 15 dakika sonra kesinleşir (ethereum.org). Kesinleşmiş bir blok, çok büyük miktarda ETH kaybedilmedikçe değiştirilemez. Yalnızca oturmuş görüntüye ihtiyaç duyan bir indexer, node'un son kesinleşmiş bloğa verdiği ad olan finalized etiketine kadar blok okuyabilir.
Borsa, işlem asgari ağ onayı sayısına ulaştığında yatırmayı hesaba geçirir; örneğin Binance'te bu asgari sayı her coin için farklıdır (Binance SSS). Yani bir borsaya yapılan yatırma, sahibi o coin'leri satabilmeden önce zincir üstünde görünür.
Veri gecikmesi
Genesis API dokümantasyonundaki swap örneğinde ts = 1794675511 swap zamanı, published_at = 1794675523 ise yayın zamanıdır: 1794675523 − 1794675511 = 12 saniye fark. Bunun üstüne meta.freshness_sec içindeki planınızın veri tazeliği (Start'ta 30 saniye, Pro'da 10, Max'te 5) ve polling aralığınız eklenir.
| Aşama | Ne kadar sürer | Ne anlama gelir |
|---|---|---|
| Ethereum bloğu | 12 sn slot | İşlem görünür ama kesin değil |
| Ethereum finality | yaklaşık 15 dk | Blok artık değişmez |
| Borsada hesaba geçme | borsanın onay asgarisi | Her coin için farklı |
| Swap yayını | örnekte 12 sn | Kayıt henüz final değil |
final durumu | swap'tan en erken 5 dk sonra | 30 sn ve 5 dk sonraki fiyat bilinir |
| Genesis API teslimi | 30, 10 veya 5 sn | Start, Pro ve Max planları |
Swap'lar için doğrulanmamış kayıtlı period=live akışı daha hızlıdır, ancak swap bir likidite yer değiştirmesi çıkarsa kayıt kaybolabilir. final=true parametresi yalnızca doğrulanmış swap'ları tutar; bunlar en az 5 dakika geç gelir.
Genesis API'de zincir üstü veri
Genesis API, Genesis OnChain bölümünün akışlarını döndürür: transfer satırları gönderen ve alıcı etiketlerini, dolar ve token cinsinden tutarı, işlem hash'ini ve explorer bağlantısını zaten içerir. İstekler, anahtarın X-API-Key başlığında gönderildiği HTTP GET'tir ve yanıt, data alanı ve meta bloğu olan JSON'dur.
| Endpoint | Ne döndürür | Planlar |
|---|---|---|
/onchain/{section} | 9 zincir üstü bölümden biri | Start, Pro, Max |
/onchain | 9 bölümün tamamı tek nesnede | Start, Pro, Max |
/onchain/dex-swaps | Büyük DEX swap'ları | Pro, Max |
/onchain/analytics | 24h veya 7d toplamları | Pro, Max |
/onchain/coin/{symbol} | 7 günlük coin özeti | Pro, Max |
Bölümler akışların adını taşır: large-transfers, cex-flows, mint-bridge, team-wallets, perp-positions, unlocks, claims, hacks ve bir coin'in tek bir hedefe giden transfer serilerini tutan coin-traffic. Filtreler min_usd ve coin'dir; kilit açılımları için ayrıca upcoming veya past değerli when vardır. Zaman parametresi yoktur, bu yüzden pencere ts alanından hesaplanır.
1.000.000 $'dan büyük yaklaşan token kilit açılımları için bir istek:
curl -G "https://api.genesisarbitrage.com/v1/onchain/unlocks" \
-d when=upcoming -d min_usd=1000000 \
-H "X-API-Key: gns_live_XXXXXXXXXXXXXXXX"
Bir kilit açılımı satırında unlock_percent ve unlock_value_usd (pay ve değer), hours_left (olaya kalan saat) ve allocations (alıcıya göre dağılım) bulunur.
Pro ve Max üç endpoint daha ekler. /onchain/dex-swaps, büyük swap'ları havuz likiditesi payı, tahmini fiyat etkisi ve 30 saniye ile 5 dakika sonraki fiyat hareketiyle döndürür (dokümanlarda DEX genel bakış). /onchain/analytics, 24h veya 7d için toplamları hesaplar: kpi.cex_in, kpi.cex_out, kpi.cex_net ve borsa bazında akışlar (OnChain analitiği). /onchain/coin/{symbol}, bir coin'in 7 günlük olaylarını, swap'larını ve kilit açılımlarını CEX fiyatı, OI'si ve funding'iyle birlikte toplar (OnChain coin).
Yalnızca 200 yanıtı kotadan düşer ve Trial'da zincir üstü endpoint'ler 403 plan_restricted döndürür. Start ayda 50 $ ile 2M çağrı, Pro 100 $ ile 5M, Max 200 $ ile 10M çağrıdır (Genesis API fiyatları). Her parametre ve alan, yanıt örnekleriyle birlikte zincir üstü endpoint'leri rehberinde yer alıyor.
Kod yazmadan aynı akışlar Genesis OnChain panosunda, swap'lar DEX genel bakışta, günlük ve haftalık toplamlar ise OnChain analitiğinde bulunur.
Python: bir coin'in pencere içindeki borsa girişleri
Varsayımsal bir örnek: 6 saat içinde beş ARB transferi borsalara ulaştı: 640.000 $, 520.000 $, 410.000 $, 330.000 $ ve 150.000 $. Toplam 640.000 + 520.000 + 410.000 + 330.000 + 150.000 = 2.050.000 olur, yani 2.000.000 $ eşiği aşılır. İlk transfer 6 saatten eski olunca pencereden düşer: 2.050.000 − 640.000 = 1.410.000 ve toplam yeniden eşiğin altına iner.
cex-flows içinde direction alanı yoktur, bu yüzden yön etiketlerden çıkar: to_name içindeki borsa yatırma, from_name içindeki borsa çekmedir. Yanıt bölümün güncel akışıdır; bu yüzden betik yatırmaları tx_hash ile saklar ve eskileri kendisi atar. Böylece pencere toplamı, sorgular arasında iki kez sayılmaz.
import os
import time
import requests
API = "https://api.genesisarbitrage.com/v1"
HEADERS = {"X-API-Key": os.environ["GENESIS_API_KEY"]}
COIN, MIN_USD = "ARB", 50_000
WINDOW = 6 * 3600 # pencere, saniye
ALERT_USD = 2_000_000 # uyarıyı tetikleyen yatırma toplamı
CEX = ("binance", "okx", "bybit", "coinbase", "kraken")
deposits = {} # tx_hash -> (ts, usd)
alerted = False
def to_exchange(row):
label = (row.get("to_name") or "").lower()
return any(name in label for name in CEX)
while True:
r = requests.get(f"{API}/onchain/cex-flows", headers=HEADERS,
params={"coin": COIN, "min_usd": MIN_USD},
timeout=15)
if r.status_code in (429, 503): # rate limit veya yeniden oluşturma
time.sleep(int(r.headers.get("Retry-After", "5")))
continue
r.raise_for_status()
body = r.json()
for row in body["data"]:
if row.get("tx_hash") and to_exchange(row):
deposits[row["tx_hash"]] = (row.get("ts") or 0,
row.get("usd") or 0)
start = time.time() - WINDOW
deposits = {h: v for h, v in deposits.items() if v[0] >= start}
total = sum(usd for _, usd in deposits.values())
print(f"{COIN}: 6 saatte borsalara ${total:,.0f}, "
f"transfer {len(deposits)}")
if total >= ALERT_USD and not alerted:
print("Eşik aşıldı: fiyatı, OI'yi ve funding'i kontrol edin")
alerted = total >= ALERT_USD
time.sleep(body["meta"]["freshness_sec"])
CEX demeti etiket alt dizelerini tutar; coin'in işlem gördüğü borsaları ekleyin. Betik yalnızca sayar ve yazdırır: Genesis API emir vermez, işlem kararı sizde kalır.
coin ve min_usd içeren bir isteğin yanıtı ETag olmadan gelir, bu yüzden her sorgu bir çağrı harcar. Start'ta 30 saniyelik bekleme ile 30 günde 2.592.000 / 30 = 86.400 çağrı eder, yani 2M kotanın %4,32'si. Bir düzine coin için /onchain/cex-flows akışını filtresiz çekin ve kendiniz ayırın: tam set ETag ile gelir ve veri değişmediyse If-None-Match ile yapılan tekrar, kotadan düşmeden 304 döndürür.
min_usd altındaki transferler sayılmaz: bir coin'in tek bir borsaya giden küçük transfer serileri coin-traffic içinde, direction, total_usd, count ve window_hours alanlarıyla gruplanır.
Borsaya yatırma nasıl okunur
6 saat içinde borsalara ulaşan aynı 2.050.000 $'lık ARB; satışa hazırlık, vadeli işlem teminatı veya sahibin kendi hesapları arasında bir hareket olabilir. Akıştaki tek bir satır hangisi olduğunu söylemez.
| Senaryo | Başka ne görürsünüz | Nasıl kontrol edilir |
|---|---|---|
| Satışa hazırlık | DEX'te satışlar, fiyat zayıflar | side=sell ile /onchain/dex-swaps |
| Vadeli işlem teminatı | Açık pozisyon artar, fonlama oranı değişir | /market/open-interest, /funding/rates |
| İç yer değiştirme | Aynı borsadan eşleşen bir çekme | cex-flows içinde from_name, explorer |
| Ekip veya fon satışı | Gönderen bir ekip cüzdanıdır | team-wallets, unlocks |
Bir coin üzerindeki birkaç olay tek bir olaydan daha ağırdır: borsaya yatırma, ekip cüzdanından transfer ve yaklaşan bir kilit açılımı. Bunları tek bir /onchain/coin/{symbol} yanıtında görebilirsiniz; olaylar oi_usd ve funding_8h içeren cex bloğunun yanındadır. Tablodaki /market/open-interest ve /funding/rates endpoint'leri Trial'dan itibaren kullanılabilir.
Diğer piyasa verileri ve bir görev için kaynak seçimi, kripto API genel bakışında ele alınıyor.
Sorular ve cevaplar
Zincir üstü verideki adres etiketleri ne kadar doğru?
Etiketler kanıtlara göre atanır ve adres sahibi onları doğrulamaz; bu yüzden tam doğruluk mümkün değildir. Bir adresi bilinen bir cüzdana ne kadar çok transfer bağlarsa sonuç o kadar güvenilir olur; yeni adresler daha sık isimsiz kalır. Her büyük olayı explorer bağlantısı üzerinden kontrol edin.
Genesis API'de zincir üstü geçmiş var mı?
Derin bir arşiv yoktur. En uzun pencereler 7 gündür: swap'lar ve analitik için period=7d ile 7 günlük coin özeti; geçmiş kilit açılımları ise when=past ile gelir. Uzun geçmişi, her sorguda kayıtları tx_hash veya id ile kaydederek kendiniz oluşturun.
DEX swap'larında pending ve final durumları ne anlama gelir?
Bu, kaydın doğrulama durumu olan facts alanıdır. pending, swap'ın yayımlandığı ve sonrasındaki fiyatın hâlâ beklendiği anlamına gelir; publish ve 30s ara aşamalardır; final, kaydın doğrulandığı ve 30 saniye ile 5 dakika sonraki fiyatın bilindiği anlamına gelir; unavailable, gerçeklerin toplanamadığı demektir. Durum final olana kadar kayıt kaybolabilir, bu yüzden swap'ları id ile saklayın veya final=true isteyin.
Balinaları API ile ücretsiz izleyebilir miyim?
Ham veriyi kendi node'unuzdan veya JSON-RPC üzerinden herkese açık bir endpoint'ten alabilirsiniz; ancak o zaman etiketleri, dolar tutarlarını ve eşikleri kendiniz kurmanız gerekir. Genesis API'de ücretsiz plan yoktur: zincir üstü bölümler ayda 50 $'lık Start planıyla, DEX swap'ları ve analitik ise 100 $'lık Pro ile başlar.