OKX API ile algoritmik ticarete giriş: Key almaktan ilk emir betiğine

Büyük ihtimalle buraya şöyle geldin: birkaç algo paylaşımcısının kâr ekran görüntüsünü gördün, heveslendin, OKX panelini açıp işe koyulmaya hazırlandın, ama daha ilk eşikte takıldın — «API yönetimi»ne tıkladın, karşına bir sürü seçenek çıktı: apiKey, Secret, Passphrase, okuma, işlem, çekim, IP beyaz listesi. Tek tek hepsini tanıyorsun ama bir araya gelince ne dolduracağını bilemiyorsun. Sonra sayfayı kapatıp kendine «sonra bakarım» diyorsun.

Bu yazı tam da bu eşiği aşman için. Biz (MeowQuant editör ekibi) sıfırdan API açmaktan Python ile ilk emir betiğini çalıştırmaya kadar tüm süreci birkaç adıma böldük; her adımı bir kez kendimiz yaptık, resmî dokümanın yazmadığı ama büyük olasılıkla başına geleceği tökezlemeler dahil. Okuyunca şunları yapabilmelisin: OKX panelinde güvenli bir API Key'i doğru biçimde oluşturmak, on küsur satır kodla bağlandığını doğrulamak, sonra demo hesapta ilk emrini verip iptal etmek. Programcı olmana gerek yok; kopyala yapıştır yeter.

Önce kendine sor: API'ye gerçekten ihtiyacın var mı?

Çoğu eğitimin atladığı ama aslında en önce düşünülmesi gereken soru bu. API açmanın, betik yazmanın bir bedeli var — ortam kurman, kodu ayarlaman ve elinin kayıp yanlış emir vermemesi için kendini koruman gerekir. İhtiyacın aslında çok basitse, API'ye hiç dokunmadan da işini görebilirsin.

OKX panelindeki «Strateji işlemleri» bölümünde hazır grid botu, DCA (kademeli alım) gibi araçlar var. Web veya uygulamada birkaç tıkla parametreleri ayarlarsın, gerisini o halleder, tek satır kod yazmana gerek kalmaz. Yeni başlayan ve sadece bir programın alış-satış emirlerini onun yerine girmesini isteyen çoğu kişi için yerleşik botlar yeterlidir; üstelik sorun çıktığında bakacak, durduracak bir arayüz var.

Peki ne zaman API açmaya değer? Bize göre şu durumlarda:

• İstediğin strateji mantığını yerleşik bot yapamıyorsa, örneğin bir göstergeye göre dinamik pozisyon ayarlamak ya da birden çok coin'i birbirine bağlamak.
• Geriye dönük test yapacaksan, toplu geçmiş mum verisi çekip işlem simüle etmen gerekiyorsa.
• Aynı anda birkaç strateji çalıştırıp hepsini betikle yönetmek elle tıklamaktan verimli olacaksa.
• Sırf algoyu öğrenmek, borsayı bir alıştırma kumu gibi kullanmak istiyorsan.

Bunlardan biri sana uyuyorsa devam et. Ama aslında derdin «bir grid kurup uyurken dalgalanmadan kazanmak» ise, önce panelde yerleşik bir grid açıp deneyebilirsin; gerçekten yerleşik araçların tavanına çarpınca dönüp API açmak için geç olmaz. Bu yolu seçeceksen, grid botu parametrelerini nasıl ayarlayacağını ayrıca anlattığımız bir yazımız var.

Key açmadan önce bilmen gereken üç şey

Gerçekten Key oluşturmaya başlamadan önce üç şeyi netleştirmen gerekir. Bunları bilmeden «oluştur»a basarsan, büyük olasılıkla ya bağlanamazsın ya da kendine bir güvenlik açığı gömmüş olursun.

① İki değil, üç bilgi alacaksın

Çoğu kişi API'yi «bir hesap bir şifre» sanır; OKX'e gelince donar kalır — sana üç şey verir:

• apiKey: bu Key'in herkese açık kimliği, «kullanıcı adı» gibi.
• secret (Secret Key): isteği imzalamak için kullanılan gizli anahtar, «şifre» gibi, yalnızca oluşturma anında bir kez gösterilir.
• Passphrase: oluştururken kendi belirlediğin bir parola dizisi, OKX'e özgü.

Üçüncüsü, Passphrase, yeni başlayanların en çok tökezlediği yerdir. Bu, OKX'e giriş yaptığın hesap şifren değil; bu Key'i oluştururken ayrıca belirlediğin bir karakter dizisidir. Daha can sıkıcı olansa, Python'ın ccxt kütüphanesinde bu alanın adının passphrase değil password olmasıdır. Bu yüzden sayısız kişi otomatik olarak giriş şifresini yazar, sonra «kimlik doğrulama başarısız» hatasına kafa yorar durur. Tek bir cümleyi aklında tut: ccxt'teki password = Key'i oluştururken belirlediğin Passphrase.

② Yetkiden sadece «İşlem»i işaretle, «Çekim»i asla

Key oluştururken OKX bu Key'in ne yapabileceğini seçtirir; başlıca üç kademe vardır:

• Okuma: fiyat, bakiye, emir sorgulama. En düşük risk.
• İşlem: emir verme, iptal, değiştirme. Strateji çalıştırmak için şart.
• Çekim: coin'i hesaptan dışarı transfer etme.

Burada neredeyse istisnasız bir güvenlik sınırı var: algo çalıştıran Key'de sadece «Okuma» ve «İşlem»i işaretle, «Çekim»i asla işaretleme. Mantığı çok basit — üç bilgin bir gün sızsa bile, Key'in çekim yetkisi yoksa onu ele geçiren kişi en fazla hesabında rastgele emir verir (bu da elbette kötü), ama paranı dışarı çıkaramaz. Çekimi bir kez işaretlersen, sızıntı kasanın anahtarını teslim etmek olur. Otomatik işlem zaten çekim eylemine hiç ihtiyaç duymaz, dolayısıyla bu yetkinin sana sadece zararı vardır, faydası yok.

③ IP beyaz listesi kurulsun mu?

OKX, Key'e IP beyaz listesi bağlamana izin verir — yalnızca belirtilen IP'lerden gelen istekler kabul edilir. Bu çok değerli ek bir sigortadır.

Ölçüt çok basit: betiğin IP'si sabit bir makinede çalışıyorsa (bulut sunucu, evdeki internet sabit genel IP'liyse), o IP'yi beyaz listeye ekle, güvenlik anında bir kademe yükselir. Kendi bilgisayarında çalıştırıyorsan ve evdeki internet IP'si sık değişiyorsa, beyaz liste kurmak IP değiştikçe her gün reddedilmene yol açar, sürekli uğraşırsın. Bu durumda önce kurmayabilirsin ama bilgilerini mutlaka iyi sakla. Betiği sabit IP'li bir sunucuya taşıyıp uzun süre çalıştıracağın zaman beyaz listeyi de ekle.

OKX panelinde API Key başvurusu

Üç şeyi anladıysan, şimdi panele gidip Key oluştur. Aşağıdaki gerçek yoldur, OKX'in güncel paneli esas alınmıştır (arayüz zaman zaman ufak değişir ama mantık aynı kalır):

1. OKX'e giriş yap, fareyi sağ üstteki profil resmine götür, açılır menüde «API» ya da «API yönetimi»ni bul, tıkla.
2. API yönetimi sayfasına girip «API Key oluştur»a tıkla. Kullanım amacını sorarsa, kendi işlemin için olan türü seç, üçüncü taraf entegrasyonu seçme.
3. Bu Key'e bir ad (not) ver, örneğin meow-grid-bot, ileride ne işe yaradığını bir bakışta tanı.
4. Passphrase'i belirle. Bu adımda kendi parola diziini sen oluşturursun, iyi belle — sonra ccxt'te lazım olacak ve sadece bu Key'e bağlı; kaybedersen silip yeniden oluşturmaktan başka çare yok.
5. Yetkileri işaretle: «Okuma» ve «İşlem»i işaretle, «Çekim»i işaretleme. (Bir önceki bölümdeki sınırı hatırla.)
6. Sabit IP'li bir makinede çalıştıracaksan IP beyaz listesini doldur; emin değilsen şimdilik boş bırak.
7. Onayla, iki aşamalı doğrulamadan geç (telefon / e-posta / kimlik doğrulayıcı uygulaması).
8. Sayfa apiKey ve Secret Key'i gösterir. Secret yalnızca bir kez gösterilir, hemen kopyalayıp güvenli bir yere kaydet. Sayfayı kapatınca bir daha göremezsin; kaybedersen Key'i silip yeniden oluşturmaktan başka yol yok.

Bu adıma geldiğinde elinde üç şey olmalı: apiKey, Secret ve az önce kendin belirlediğin Passphrase. Bunları yerel, senkronize edilip yüklenmeyecek bir dosyaya kaydet — ekran görüntüsü alıp mesajla atma, hiçbir çevrimiçi nota yapıştırma. Sonraki adımda bu üç bilgiyle bağlanacağız.

Python + ccxt ile bağlan, çalıştığını doğrula

Bilgiler elinde, sırada bunların gerçekten çalıştığını doğrulamak var. ccxt kütüphanesini kullanıyoruz — yüzlerce borsanın API'sini tek bir arayüzde toplar, OKX'in ham imza ayrıntılarını kurcalamana gerek kalmadan birkaç satırla bakiye sorgular, emir verirsin.

Önce kütüphaneyi kur. Terminali (komut satırı) aç ve şunu yaz:

pip install ccxt

Kurulunca okx_check.py adında yeni bir dosya oluştur, aşağıdakini içine kopyala ve üç tırnak içindeki yer tutucuları kendi bilgilerinle değiştir:

import ccxt

# Üç bilgi: apiKey, secret, password (=Passphrase)
okx = ccxt.okx({
    'apiKey':   'senin_apiKey',
    'secret':   'senin_secret',
    'password': 'senin_Passphrase',   # OKX'e özgü, yeni başlayanın en çok atladığı şey
})

# Hesap bakiyesini çek, kimlik doğrulamanın geçtiğini doğrula
balance = okx.fetch_balance()
print('USDT kullanılabilir:', balance['USDT']['free'])
print('USDT toplam:', balance['USDT']['total'])

Kaydet, terminalde python okx_check.py çalıştır. USDT bakiyeni (sıfır bile olsa) yazdırırsa, tebrikler, kimlik doğrulama geçti, API bağlandı. Hata verirse paniğe kapılma — büyük olasılıkla üç bilgiden biri yanlış ya da eksik girilmiştir; yazının «Yeni başlayanların en sık düştüğü tuzaklar» bölümüne bak, orada her hatanın nedeni listeli.

Bilgilerin saklanması konusunda bir not daha: yukarıda anlatmak için bilgileri doğrudan koda yazdık, ama bu sadece yerel tek seferlik test içindir. Betik uzun süre çalışacak, hatta bir sunucuya konacaksa bilgileri koda gömme — ortam değişkeni ya da ayrı bir yapılandırma dosyası kullan ve bu dosyanın senkronize edilmediğinden, kod deposuna yüklenmediğinden emin ol. Hesabın çalınma olasılığını en aza indiren temel alışkanlık budur.

İlk emir betiği: emir ver ve iptal et

Bakiye sorgulayabilmen okuma yetkisinin çalıştığını gösterir; şimdi işlem yetkisini dene — bir emir ver, sonra iptal et. Burada piyasa emri değil limit emri kullanıyoruz, çünkü limit emrinde fiyatı sen belirlersin; fiyatı piyasadan çok uzağa koyarsan hemen gerçekleşmez, böylece gerçekten para harcamadan emir verme ve iptali çalışırsın.

Emir vermeden önce iki ufak şeyi anlaman gerekir:

symbol (işlem çifti) nasıl yazılır. ccxt'te spot işlem çiftleri tek tip temel/değerleme biçiminde yazılır; örneğin Bitcoin'in USDT karşılığı BTC/USDT, Ethereum'un USDT karşılığı ETH/USDT. Dikkat: düz eğik çizgi ve büyük harf. Biçimi yanlış yazmak bir başka sık hata kaynağıdır.

Emir parametreleri. ccxt'in emir verme yöntemi create_order(symbol, type, side, amount, price); beş parametre sırasıyla: işlem çifti, emir türü (limit limit / market piyasa), yön (buy al / sell sat), miktar, fiyat.

Aşağıdaki kod, bilerek gerçekleşmeyecek düşük fiyatlı bir limit alış emri verir, emir numarasını alıp hemen iptal eder. Mutlaka önce demo hesapta çalıştır (sonraki bölüm demo hesaba nasıl bağlanılacağını anlatıyor):

import ccxt, time

okx = ccxt.okx({
    'apiKey':   'senin_apiKey',
    'secret':   'senin_secret',
    'password': 'senin_Passphrase',
})

symbol = 'BTC/USDT'

# Bilerek gerçekleşmeyen bir limit alış emri: fiyat piyasanın çok altında
order = okx.create_order(
    symbol=symbol,
    type='limit',
    side='buy',
    amount=0.0001,     # Miktar küçük, en düşük emir miktarını esas al
    price=20000,       # Güncel BTC piyasasının çok altında, asılı kalır gerçekleşmez
)
order_id = order['id']
print('Emir verildi, emir no:', order_id)

time.sleep(2)

# Az önceki emri iptal et
canceled = okx.cancel_order(order_id, symbol)
print('Emir iptal edildi:', canceled['id'])

Çalıştırınca iki satır çıktı görürsün: önce emir numarası, iki saniye sonra iptal onayı. Bu, betiğinin artık eksiksiz biçimde «emir ver — iptal et» yapabildiğini gösterir; algonun en temel iki eylemi tamamlandı. Geri kalan stratejiler — grid, kademeli alım, hedge — özünde bu iki eylemin üzerine karar mantığı ve döngü eklemekten ibarettir.

amount (miktar) hakkında: her işlem çiftinin bir en düşük emir miktarı ve hassasiyet sınırı vardır; çok küçük girersen borsa reddeder. «Miktar kurala uymuyor» hatası alırsan, önce okx.load_markets() ile bu çiftin limits ve precision değerlerine bakıp istenen en düşük değere göre doldur.

Önce demo hesap: sahte parayla çalıştır

Yukarıdaki tüm kodu, gerçek paraya geçmeden önce mutlaka demo hesapta çalıştırmanı şiddetle öneririz. Demo hesap sanal sermaye kullanır; yanlış emir vermek, mantığı yanlış yazmak sana gerçek para kaybettirmez — bu giriş aşamasının en kârlı adımıdır, atlamak için neredeyse hiçbir gerekçe yok.

OKX'in demo hesabı Demo Trading (demo işlem) adını taşır, hem uygulamada hem web'de geçiş yapabilirsin. İyi yanı: gerçek hesabınla aynı API Key'i paylaşır, demo için ayrı Key oluşturmana gerek kalmaz. ccxt'in isteği gerçek hesaba değil demo hesaba göndermesi için, başlatmadan sonra sandbox anahtarını açman yeter:

import ccxt

okx = ccxt.okx({
    'apiKey':   'senin_apiKey',
    'secret':   'senin_secret',
    'password': 'senin_Passphrase',
})

# Anahtar satır: demo hesaba (Demo Trading) geç
okx.set_sandbox_mode(True)

# Bundan sonra tüm istekler demo hesaba gider, sanal sermaye kullanılır
balance = okx.fetch_balance()
print('Demo USDT kullanılabilir:', balance['USDT']['free'])

Bazı sürümler yapılandırmada 'options': {'sandboxMode': True} yazmayı da destekler, etkisi aynıdır; çalışan birini seç. Demo hesaba geçtikten sonra az önceki emir-iptal betiğini gönül rahatlığıyla tekrar tekrar çalıştırabilirsin: elin kayıp fiyatı piyasaya yakın yazsan ve emir gerçekten gerçekleşse bile harcanan sanal USDT olur.

Bizim alışkanlığımız şu: her yeni strateji, her değiştirilen kod önce demo hesapta bir süre kesintisiz çalışır; emir geri çağrısı, iptal, bakiye değişimi beklediğimiz gibi mi diye doğrularız, sonra o set_sandbox_mode(True) satırını kaldırıp gerçeğe geçer, ilk gerçek denemede de çok küçük bir tutar kullanırız. Bu sıra bizi birkaç kez kurtardı — birkaç mantık hatası tam da demo aşamasında ortaya çıktı; doğrudan gerçek parayla gitseydik bedel sadece para olmazdı.

Yeni başlayanların en sık düştüğü tuzaklar

Bu bölüm yazının en çok kaydedilesi kısmı. Aşağıdaki her madde ya kendi başımıza geldi ya da toplulukta defalarca gördüğümüz bir hata; karşılaştırarak baktığında sana saatler kazandırır.

Passphrase eksik / yanlış (en sık)

Hata genellikle kimlik doğrulama türündedir («Invalid sign» ya da «passphrase incorrect» gibi). ccxt'teki password alanına Key'i oluştururken belirlediğin Passphrase'i mi yazdığını kontrol et — giriş şifresi değil, secret de değil. Bu madde yeni başlayanların kimlik doğrulama hatalarının yarısından fazlasını kapsar.

Zaman damgası hatası / istek süresi dolmuş

OKX, istek zaman damgasına bir tolerans tanır; bilgisayarının ya da sunucunun sistem saati doğru değilse (birkaç on saniyeden fazla saparsa), imza zaman damgası dolduğu için reddedilir. Çözüm, sistem saatini doğru ağ saatine senkronize etmek (NTP otomatik saat ayarını açmak). Bulut sunucular genelde varsayılan açıktır, yerel makineler ara sıra kayar.

Yetki yetersiz

Bakiye sorgulayabilip emir veremiyorsan, neredeyse kesin Key'i oluştururken sadece «Okuma» işaretlenmiş, «İşlem» işaretlenmemiştir. API yönetimine dönüp bu Key'e işlem yetkisini ekle yeter, yeniden oluşturmaya gerek yok.

İstek sınırına (Rate Limit) takılma

Döngüde çılgınca fiyat sorgular ya da emir verip iptal edersen API istek sınırına çarpar, «Too Many Requests» gibi hata alırsın. En kolay çözüm, başlatırken ccxt'in hız sınırlamasını açmaktır: ccxt.okx({..., 'enableRateLimit': True}); istekler arasına otomatik aralık koyar. Hiçbir gecikme koymadan while True ile API'yi dövme.

symbol yanlış yazılmış

BTC/USDT'yi BTCUSDT, btc/usdt diye yazmak ya da spot emrinde vadeli işlem biçimi kullanmak «işlem çifti bulunamadı» hatası verir. Spot çiftin BÜYÜK/BÜYÜK ve eğik çizgili olduğunu unutma; emin değilsen önce print(okx.load_markets().keys()) ile mevcut çiftlerin tam olarak nasıl göründüğüne bak.

IP beyaz listede değil

Beyaz liste kurmuş biri, ağ ortamını değiştirince (örneğin proxy açınca ya da internet IP'si değişince) reddedilir. Mevcut çıkış IP'nin hâlâ o Key'in beyaz listesinde olduğunu doğrula, değilse panele girip listeyi güncelle.

Risk yönetimi ve zihniyet: algo kesin kazanç demek değil

Betik çalıştırabilir hale geldin; şimdi sana bir kova soğuk su dökmemiz lazım. İşlemi programa devretmek seni otomatik zengin etmez — yalnızca kararlarını daha hızlı ve daha az duygu katarak uygular. Stratejin zaten zarardaysa, otomasyon sadece daha hızlı ve daha istikrarlı kaybetmeni sağlar.

Üstelik API otomasyonunun kendine özgü bir riski var: program insan gibi tereddüt etmez. Yanlış yazılmış bir döngü, ters çevrilmiş bir alış-satış yönü, virgülü eksik kalmış bir miktar — elle çalışırken onay tuşuna basmadan önce fark edebileceğin şeyleri, betik sadakatle, art arda onlarca kez uygular. Demo aşamasında, yazdığımız bir döngünün ters bir koşul yüzünden saniyeler içinde, asılması gerekmeyen bir dizi emir astığına bizzat şahit olduk. Gerçek hesapta olsaydı, gerçek para kaybı olurdu.

Yeni başlayana birkaç somut öneri:

• Önce küçük tutar. Gerçek hesaba ilk çıkışta, tamamını kaybetsen bile üzülmeyeceğin bir tutar kullan. Onu eğitim parası say, anapara değil.
• Pozisyon üst sınırı koy. Betiğe tek seferlik ve toplam pozisyon üst sınırını gömerek programın tüm sermayeni bir kerede sokmasına fırsat verme.
• Zarar durdur bırak. Strateji ne kadar iyi görünürse görünsün, ona net bir zarar durdur ya da maksimum geri çekilme çizgisi koy, tetiklenince dursun.
• Vadeli işlem ve kaldıraçtan uzak dur. Bu yazı baştan sona spot anlatır. Kaldıraçlı vadeli işlem çok kısa sürede anaparanı sıfırlayabilir; yeni başlangıç aşamasında yalnızca spot yapmanı, akışı ve zihniyeti oturttuktan sonra konuşmanı şiddetle öneririz.
• Bir süre izle. Yeni strateji gerçek hesaba çıktığı ilk birkaç gün gerçekten elini çekme, başında dur, davranışının demo hesapta gördüğünle aynı olduğunu doğrula.

Sık sorulan sorular

API eşiğini aştıktan sonra muhtemelen alıştırma yapmak için somut bir strateji arayacaksın. En anlaşılır olan grid botundan başlamanı, ya da önce küçük araçlarla parametreleri ve komisyonu hesaplayıp öyle işe koyulmanı öneririz. Hangi yolu seçersen seç, bugünkü yazının sırasını unutma: önce demo hesap, sonra küçük tutarla gerçek hesap, önce ayakta kal, sonra kazancı konuş.