DOKÜMANTASYON · API v3

Geliştirici Dokümantasyonu

Tek bir API ile küresel merkeziyetsiz GPU ağına erişin. Python, Node.js, Go ve Rust SDK'larıyla dakikalar içinde başlayın.

💡 Yeni misiniz? En hızlı yol, aşağıdaki Hızlı Başlangıç rehberini izleyip 5 dakika içinde ilk işinizi göndermektir. Mainnet ücretsiz $50 test kredisi ile başlatılır.

Kurulum

SDK'lar standart paket yöneticileri üzerinden dağıtılır:

Python

bash$ pip install bitality-sdk
# Veya geliştirme sürümü için:
$ pip install bitality-sdk[dev]
            

Node.js

bash$ npm install @bitality/sdk
# veya
$ yarn add @bitality/sdk
            

Go

bash$ go get github.com/bitality/sdk-go

Rust

bash$ cargo add bitality-sdk

⚠️ Sürüm Uyumluluğu: Bu doc, SDK v3.x içindir. v2.x kullanıcıları için v2 to v3 migration guide'a bakın.

Hızlı Başlangıç

İlk AI eğitim işinizi 5 dakika içinde gönderin:

1. API Anahtarı Alın

app.bitality.com.tr üzerinden ücretsiz bir hesap açın ve sk_live_... formatında API anahtarınızı alın. İlk kayıt $50 hesaplama kredisiyle gelir.

2. SDK'yı Yapılandırın

pythonimport bitality as bt
import os

client = bt.Client(
    api_key=os.environ.get("BITALITY_API_KEY"),
    network="mainnet"  # veya "testnet"
)

# Bağlantıyı test edin
print(client.ping())
# >> {'status': 'ok', 'block': 872431, 'latency_ms': 9}
            

3. İlk İşinizi Gönderin

python# Hazır bir modeli ince ayar yapın
job = client.compute.submit(
    model="llama-3-8b-base",
    task="fine-tune",
    dataset="./training_data.jsonl",
    config={
        "epochs": 3,
        "batch_size": 32,
        "learning_rate": 2e-5,
    },
    privacy=True,           # ZK encryption etkin
    max_cost_bty=100,        # Maksimum bütçe
)

print(f"Job ID: {job.id}")
print(f"Tahmini süre: {job.estimated_seconds}s")
print(f"Tahmini maliyet: {job.estimated_cost_bty} BTY")
            

4. İşin Tamamlanmasını Bekleyin

python# Senkron bekleme (polling)
result = job.wait(timeout=3600)

# Veya callback ile
job.on_complete(lambda r: print(f"Bitti: {r.model_url}"))

# Sonuç doğrulaması
print(result.btc_anchor_block)  # Bitcoin'e çapa atılan blok
print(result.witness_signatures)  # BLS toplama imzaları
print(result.cost_bty)            # Gerçek maliyet
            

Authentication

Tüm API çağrıları Bearer token ile doğrulanır. Anahtarınızı asla client-side kodda veya public repository'de bulundurmayın.

httpGET /v3/jobs/123 HTTP/1.1
Host: api.bitality.com.tr
Authorization: Bearer sk_live_4a8f...e2d1
Content-Type: application/json
            

🔒 Güvenlik: Eğer anahtarınız sızdırıldıysa, app.bitality.com.tr/keys üzerinden derhal döndürün. Devre dışı bırakılmış anahtarlar 30 saniye içinde tüm node'larda geçersiz kılınır.

Compute Jobs

Bir job, ağa gönderilen herhangi bir hesaplama birimidir. Üç temel tür vardır:

training — Sıfırdan veya checkpoint'ten model eğitimi
fine-tune — Hazır bir modelin uyarlanması
inference — Modelden çıkarım (batch veya stream)

Job Lifecycle

Bir iş aşağıdaki durumlardan geçer:

queued — Scheduler'a alındı, atama bekliyor
assigned — Madencilere paylaştırıldı
computing — Aktif olarak hesaplanıyor
verifying — Şahid komitesi doğruluyor
anchoring — Bitcoin'e çapa atılıyor
complete — Tamamlandı, sonuç indirilebilir
failed — Hata oluştu (refund tetiklenir)

Compute API

POST/v3/compute/submit

Yeni bir hesaplama işi gönderir. İş queue'ya alınır ve hemen job_id döner.

Request Body

Alan	Tip	Açıklama
model required	string	Model ID veya custom model hash. Liste için `GET /v3/models`
task required	enum	"training" \| "fine-tune" \| "inference"
dataset	string \| object	Dataset URI veya inline data. IPFS, S3, HTTP destekli.
config	object	Hyperparameters (epochs, batch_size, lr, vb.)
privacy	boolean	ZK encryption (default: `false`). Maliyeti %15-25 artırır.
max_cost_bty	number	Maksimum bütçe (BTY). Aşılırsa iş iptal edilir.
priority	enum	"low" \| "normal" \| "high" — Yüksek öncelik %30 daha pahalı.

Response (201 Created)

json{
    "job_id": "job_4a8f2e9b1c3d",
    "status": "queued",
    "estimated_cost_bty": 87.4,
    "estimated_duration_s": 2400,
    "position_in_queue": 3,
    "submitted_at": "2026-05-13T10:24:31Z",
    "webhook_url": null
}
            

GET/v3/compute/jobs/:job_id

Bir işin mevcut durumunu sorgular. Polling için 5 saniyede bir çağrılabilir.

DELETE/v3/compute/jobs/:job_id

Bir işi iptal eder. Sadece queued ve assigned durumlarındaki işler iptal edilebilir.

Nodes API

GET/v3/nodes

Aktif madenci node'larının listesi. Filtreleme: ?gpu=rtx_4090&country=TR&min_uptime=0.95

POST/v3/nodes/register

Yeni bir node'u ağa kaydeder. Stake gerektirir (min 1000 BTY).

Rate Limits

API çağrıları, abonelik planına göre sınırlandırılır:

Plan	İstek/dk	İstek/gün	Eş zamanlı Job
Free	60	5,000	3
Developer ($29/ay)	300	50,000	20
Pro ($199/ay)	1,000	250,000	100
Enterprise	Custom	Custom	∞

Limit aşıldığında 429 Too Many Requests yanıtı alınır. Retry-After header'ı saniye cinsinden bekleme süresini içerir.

Hata Kodları

Kod	Açıklama	Çözüm
400	Geçersiz request	Body'yi şemaya göre kontrol et
401	Geçersiz/eksik API anahtarı	Authorization header'ı kontrol et
402	Yetersiz bakiye	Cüzdana BTY ekle veya max_cost düşür
403	Erişim reddi	Plan upgrade'i gerekli olabilir
409	Conflict (iş zaten var)	Idempotency-Key kullan
429	Rate limit aşıldı	Retry-After'ı bekle
500	Sunucu hatası	Status sayfasını kontrol et, tekrar dene
503	Ağ yoğun, geçici	Exponential backoff ile retry

Webhooks

İş durumu değişikliklerinde polling yerine webhook kullanın:

pythonjob = client.compute.submit(
    ...,
    webhook_url="https://yourapp.com/bitality-webhook",
    webhook_events=["complete", "failed"],
)
            

Webhook payload'u:

json{
    "event": "job.complete",
    "job_id": "job_4a8f2e9b1c3d",
    "timestamp": "2026-05-13T11:04:17Z",
    "data": {
        "model_url": "ipfs://Qm...",
        "cost_bty": 84.2,
        "btc_anchor_tx": "abc123...def"
    },
    "signature": "sha256=..."
}
            

İmzayı doğrulayın (HMAC-SHA256 ile webhook secret):

pythonimport hmac, hashlib

def verify_signature(payload: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(secret.encode(), payload, hashlib.sha256).hexdigest()
    return hmac.compare_digest(f"sha256={expected}", signature)
            

Changelog

v3.2.0 — 28 Nisan 2026

NEW: Multimodal model desteği (vision + text)
NEW: Streaming inference API (/v3/inference/stream)
FIX: Webhook retry mekanizması iyileştirildi

v3.1.0 — 14 Mart 2026

BREAKING: /v2/* endpoints kaldırıldı
NEW: Cross-chain bridge desteği (Ethereum, Solana)
IMPROVED: ZK proof generation %40 daha hızlı

v3.0.0 — 1 Aralık 2025

MAJOR: API v3 yayınlandı
NEW: Rust SDK lansmanı

Yardıma mı ihtiyacın var?

Discord'da geliştirici kanalına katıl veya support@bitality.com.tr'ye yaz.

DISCORD GITHUB