Dexalot Python SDK ile Başlangıç Yapma

Bu rehber, Dexalot Python SDK'sini kurmanıza, borsa ile bağlantı kurmanıza ve ilk işlemlerinizi çalıştırmanıza yardımcı olur. Sonunda; emir defterlerini nasıl okuyacağınızı, emirleri nasıl vereceğinizi ve iptal edeceğinizi, swap nasıl gerçekleştireceğinizi ve bakiyelerinizi nasıl kontrol edeceğinizi — tümünü Python üzerinden — öğreneceksiniz.

Her şeyi pratik tutacağız. Buradaki her örnek, hemen çalıştırabileceğiniz bir şey.

Kurulum

Python 3.12 veya daha üstüne ihtiyacınız var. Bunu kendi platformunuz için python.org üzerinden indirip kurabilirsiniz. Python ortamı kurulumundan sonra Dexalot Python SDK paketini PyPi üzerinden yükleyin.

pip install dexalot-sdk

Ya da daha hızlı bağımlılık yönetimi için uv kullanıyorsanız (bunu öneriyoruz):

uv add dexalot-sdk

Sonraki adımda, bağlanmak istediğiniz ortamla birlikte proje kök dizininizde bir .env dosyası oluşturun:

PARENTENV=fuji-multi

Testnet için bu fuji-multi veya mainnet'e hazır olduğunuzda production-multi. Emir defterlerini ve token listelerini çekme gibi salt okunur işlemler için ihtiyacınız olan tek şey bu. Kısa süre içinde imzalama kimlik bilgilerini ekleyeceğiz. Kullanabileceğiniz değişkenlerin tam listesi için env.example dosyasını inceleyebilirsiniz.

İlk Bağlantınız

SDK asenkron (async) odaklıdır; yani tüm işlemler bir async context içinde çalışır. İşte en basit olası bağlantı — mevcut işlem çiftlerini okuyun ve ilk birkaçını yazdırın:

import asyncio
from dexalot_sdk import DexalotClient

async def main():
    async with DexalotClient() as client:
        await client.initialize_client()

        pairs = await client.get_clob_pairs()
        if pairs.success:
            for pair in pairs.data[:5]:
                print(pair["pair"])
        else:
            print("Error:", pairs.error)

asyncio.run(main())

Dikkat etmeniz gereken birkaç şey var. async with bloğu, HTTP oturumunu sizin için otomatik olarak açma ve kapama işini halleder. initialize_client() çağrısı, borsanın yapılandırmasını — token meta verileri, kontrat adresleri, zincir detayları — yükler; böylece istemci protokolle nasıl konuşacağını bilir. Sonuç, bir Result nesnesi olarak döner: .data erişmeden önce .success değerini kontrol edin ve bir şey ters giderse .errorı okuyun.

Bu desen — sonucu kontrol et, sonra ona göre hareket et — tüm SDK yöntemleri boyunca tutarlıdır. Beklenen hatalar için gizli istisnalar yok.

Emir Defterini Okuma

Bağlandıktan sonra belirli bir işlem çifti için emir defterini almak tek satırdır:

ob = await client.get_orderbook("ALOT/USDC")
if ob.success:
    book = ob.data
    print("En iyi alış:", book["bids"][0])
    print("En iyi satış:", book["asks"][0])

Emir defteri verileri varsayılan olarak bir saniye süreyle önbelleğe alınır; bu da art arda hızlı çağrıların API'yi gereksiz yere zorlamayacağı anlamına gelir. Yüksek frekanslı stratejiler için daha güncel verilere ihtiyacınız varsa, önbellek TTL'sini düşürebilir ya da tamamen devre dışı bırakabilirsiniz (aşağıda daha fazla).

İşlem Yapmak İçin Bir İmzacı Ayarlama

Salt okunur erişim faydalıdır; ancak emir vermek, swap gerçekleştirmek ya da fonları taşımak için bir imzalama cüzdanına ihtiyacınız var. Önerilen yaklaşım, ham özel anahtarınız hiçbir zaman bir yapılandırma dosyasının içinde durmasın diye imzacı (signer) nesnesini doğrudan aktarmaktır:

from eth_account import Account

signer = Account.from_key("0xYOUR_PRIVATE_KEY")

async with DexalotClient(signer=signer) as client:
    await client.initialize_client()
    # Artık işlem yapabilirsin

Üretim senaryoları için SDK ayrıca şifreli bir secrets vault (gizli anahtar kasası) ile birlikte gelir. Anahtarlarını disk üzerinde şifreli bir dosyada saklar — yalnızca anahtar adları görünür, değerler ise depolama sırasında şifrelenmiş durumdadır. Bir kez bir şifreleme anahtarı üretirsin, onu şifre yöneticinde saklarsın ve çalışma anında vault'ın kilidini açmak için kullanırsın:

secrets-vault keygen          # şifreleme anahtarını üret, güvenle kaydet
secrets-vault add PRIVATE_KEY 0xabc123...

Sonra çalışma anında DEXALOT_SECRETS_VAULT_KEY değerini bir ortam değişkeni olarak ayarla ya da SDK'nın sana sormasına izin ver. Bu sayede ham anahtarın tamamen .env dosyalarında ve kaynak kontrolünde görünmez.

Önemli: Özel anahtarları veya vault şifreleme anahtarlarını asla sürüm kontrolüne (version control) commit etme. Üretimde bir şifre yöneticisi ya da AWS Secrets Manager veya HashiCorp Vault gibi bir secrets manager kullan.

İlk Siparişini Verme

İmzacı (signer) bağlandıktan sonra bir limit alış emri (limit buy order) şu şekilde görünür:

result = await client.add_order(
    pair="ALOT/USDC",
    side="BUY",
    amount=100.0,
    price=0.15,
    order_type="LIMIT",
)
if result.success:
    print("Transaction:", result.data["tx_hash"])
    print("Order ID:", result.data["client_order_id"])
else:
    print("Failed:", result.error)

SDK, perde arkasında her şeyi halleder: okunabilir (human-readable) tutarlarını zincir üstündeki atomik formata dönüştürmek, aynı-nonce hatası almaman için işlem nonce'unu yönetmek, gas'ı tahmin etmek, işlemi imzalamak ve göndermek. Sana bir işlem karması (transaction hash) ve daha sonra emri iptal etmek ya da değiştirmek için kullanabileceğin bir istemci sipariş kimliği (client order ID) döner.

İptal etmek mi istiyorsun?

result = await client.cancel_order(order_id="0xabc...")

Her şeyi iptal etmen mi gerekiyor?

result = await client.cancel_all_orders()

Toplu İşlemler: Tek Seferde Birden Fazla Sipariş

Birden fazla pozisyonu yönetiyorsan, SDK birden çok emri tek bir zincir üstü (on-chain) işlem içinde birleştiren toplu işlemleri destekler. Bu hem gas'tan tasarruf sağlar hem de gecikmeyi azaltır:

orders = [
    {"pair": "ALOT/USDC", "side": "BUY", "amount": 50.0, "price": 0.14},
    {"pair": "ALOT/USDC", "side": "BUY", "amount": 75.0, "price": 0.13},
]
result = await client.add_limit_order_list(orders)

Ek olarak atomik bir iptal etme ve yeniden yerleştirme (cancel-and-replace) işlemi de vardır. Mevcut siparişlerini kaldırır ve aynı işlem içinde yeni siparişleri yerleştirir — hedge'siz (hedged) kalacağın bir boşluk yok:

result = await client.cancel_add_list(
    replacements=[
        {
            "order_id": "0xold...",
            "pair": "ALOT/USDC",
            "side": "BUY",
            "amount": 100.0,
            "price": 0.16,
        }
    ],
)

Sürekli fiyat (quote) güncellemesi yapması gereken piyasa yapıcılar için bu bir oyun değiştirici.

Sipariş Defteri Olmadan Hızlı Takaslar

Her ticaret, limit emir hassasiyeti gerektirmez. SDK, istek-teklif (RFQ) fiyatlamasına dayalı basit bir swap akışı içerir. Üç adımda çalışır: gösterge niteliğindeki fiyatı kontrol edin, sabit bir teklifi kilitleyin ve gerçekleştirin.

# Adım 1: Soft quote — fiyatın nasıl göründüğüne bakın, taahhüt yok
soft = await client.get_swap_soft_quote(
    from_token="ALOT", to_token="USDC", amount=100.0
)

# Adım 2: Firm quote — fiyatı 30 saniyeliğine kilitler
firm = await client.get_swap_firm_quote(
    from_token="ALOT", to_token="USDC", amount=100.0
)

# Adım 3: Swap'i gerçekleştir
if firm.success:
    result = await client.execute_rfq_swap(firm.data)

Bu, emir yerleştirme ve dolum (fill) yönetmek zorunda kalmadan doğrudan "A'dan B'ye çevir" arayüzü gerektiren uygulamalar için idealdir.

Bakiye Kontrolü ve Fon Taşıma

SDK, Dexalot portföyünüzdeki bakiyelerinizin yanı sıra bağlı zincir cüzdanlarınız genelinde de size tam görünürlük sağlar:

# Tüm portföy bakiyeleri
result = await client.get_all_portfolio_balances()
if result.success:
    for token, balance in result.data.items():
        print(token, "Toplam:", balance["total"], "Kullanılabilir:", balance["available"])

# Tek bir token
result = await client.get_portfolio_balance(token="USDC")

Fonları içeriye veya dışarıya taşımak için:

# Bağlı bir zincirden depozito
await client.deposit(token="USDC", amount=100.0, source_chain="Avalanche")

# Bir zincire geri çekme
await client.withdraw(token="USDC", amount=50.0, target_chain="Avalanche")

Kullanım Senaryonuza Göre Cache'i Ayarlama

SDK, API yanıtlarını dört seviyede önbelleğe alır; her biri bu verinin ne kadar hızlı değiştiğiyle eşleşir:

• Sabit veriler (ortamlar, zincirler): 1 saat önbelleğe alınır
• Yarı sabit veriler (token'lar, işlem çiftleri): 15 dakika önbelleğe alınır
• Bakiye'ler: 10 saniye önbelleğe alınır
• Emir defteri: 1 saniye önbelleğe alınır

Bu varsayılanlar çoğu uygulama için iyi çalışır. Ancak yüksek frekanslı bir bot geliştiriyorsanız, saniyeden daha kısa süreli emir defteri tazeliği isteyebilirsiniz — 500 milisaniyelik sona erme için cache_ttl_orderbook=0.5 ayarlayın.

client = DexalotClient(
    cache_ttl_orderbook=0.5,   # 500 milisaniye
    cache_ttl_balance=1,       # 1 saniye
)

Anlık veri gerektirmeyen bir dashboard mu oluşturuyorsunuz? TTL'leri yükseltin ve API ayak izinizi dramatik biçimde azaltın. Geliştirme için, önbelleği tamamen enable_cache=False ile devre dışı bırakabilirsiniz.

WebSocket ile Canlı Piyasa Verisi

Emir defteri güncellemeleri için gerçek zamanlı olarak WebSocket yöneticisini etkinleştirin: yapılandırmanızda ws_manager_enabled=True ayarlayın, ardından client.subscribe_to_events() ile olaylara abone olun. "OrderBook/ALOT/USDC" gibi bir konu (topic) dizesi ve her olayı bir sözlük olarak alan bir asenkron geri çağırma fonksiyonu (callback) iletin.

async def on_orderbook_update(event):
    print("Update:", event)

config = DexalotConfig(ws_manager_enabled=True)

async with DexalotClient(config=config, signer=signer) as client:
    await client.initialize_client()
    await client.subscribe_to_events(
        topic="OrderBook/ALOT/USDC",
        callback=on_orderbook_update,
    )
    await asyncio.sleep(60)  # listen for a minute

WebSocket bağlantısı yeniden bağlanmayı otomatik olarak yönetir. Geri çağırma (callback) bir async fonksiyondur ve event loop üzerinde çalışır; böylece diğer trading mantığınızla doğal bir şekilde etkileşime girebilir.

Genel Bakışta Konfigürasyon

Her şey, constructor argümanları, ortam değişkenleri (environment variables) veya bir .env dosyası üzerinden yapılandırılabilir. Constructor argümanları her zaman önceliklidir. En sık ayarlanan seçenekler şunlardır:

Ücretsiz Elde Ettiğiniz Dayanıklılık Özellikleri

SDK'nın otomatik olarak yönettiği ve bilmeye değer birkaç şey:

Backoff ile yeniden deneme. Bir API çağrısı veya RPC isteği geçici bir hata nedeniyle başarısız olursa, SDK üstel backoff ile yeniden dener. Varsayılanlar mantıklıdır (artan gecikmelerle birkaç deneme), ancak toleransınıza uyacak şekilde ayarlayabilirsiniz. Bu da botunuzun tek bir kopma nedeniyle çökmesini engeller.

RPC failover. Her chain için birden fazla RPC sağlayıcı URL'si yapılandırabilirsiniz. Birisi tutarlı şekilde hata vermeye başlarsa SDK otomatik olarak diğerine geçer. Başarısız sağlayıcılar yeniden denenmeden önce bir soğuma (cooldown) süresine girer. Her şey çökerse, çalıştığı son sağlayıcıya geri döner.

Oran limitleme (rate limiting). SDK, token-bucket algoritması kullanarak hem API çağrıları hem de RPC istekleri için oran limitlerini uygular. Varsayılanlar (saniyede 5 API isteği, saniyede 10 RPC çağrısı) sizi tipik sunucu tarafı limitleri içinde tutar. Birden fazla client instance çalıştırıyorsanız, her birinin kendi limiter'ı olduğunu unutmayın — global bir kota paylaşmazlar.

Hata sanitizasyonu. Bir şey ters giderse, result.error içinde gördüğünüz hata mesajları temizlenir — dosya yolu yok, RPC URL'si yok, sızıntı yapan stack trace yok. Production ortamında bu, altyapı detaylarının yanlışlıkla ifşa edilmesini önler. Debugging için log_level'ı DEBUG yaparak loglarınızda tam bağlamı görürsünüz.

Sonrası için Nereye Gitmeli

Bu rehber temel bilgileri kapsar; ancak SDK burada sığdırabildiğimizden daha derin. Tüm resmi görmek için:

• User Guide — her metodu eksiksiz örneklerle kapsar
• Architecture Overview — katkıda bulunanlar için dahili tasarımı açıklar
• Caching Guide — farklı uygulama profilleri için detaylı TTL ayarı
• API Reference — kaynak kodundan otomatik oluşturulan dokümantasyon

SDK açık kaynaklıdır. Bir hata bulursanız, bir özellik talep ederseniz veya bir sorunuz varsa, depoya gitmeniz gereken yer burası.

Testnet’te başlayın, API ile rahat olun ve stratejiniz hazır olduğunda — tek bir ortam değişkenini değiştirerek mainnet’e geçin.

Python SDK | GitHub: github.com/Dexalot/dexalot-sdk-python ⧉

Python SDK | PyPi: pypi.org/project/dexalot-sdk ⧉

İyi geliştirmeler.