Bürküt Finansal Veri Ekosistemi

Türkiye finansal piyasaları için geliştirici odaklı veri altyapısı ve yapay zeka araçları.
Borsa İstanbul (BIST), TEFAS Fonları, KAP Bildirimleri, Döviz Kurları ve Makroekonomik Göstergeler.

Dokümantasyon • Geliştirici Portalı • MCP Rehberi • Postman Koleksiyonu • ☕ Destek Ol

---

Genel Bakış

Bürküt Finans Ekosistemi; Türkiye sermaye piyasalarında veri çekmek için yıllardır süregelen dengesiz web kazıma (HTML scraping) araçlarına, sürekli IP ban yiyen botlara ve bozuk kütüphanelere modern bir alternatif olarak geliştirilmiştir.

Tüm finansal verileri; yüksek hızlı, önbellek destekli ve tip güvenli (type-safe) bir mimari üzerinden üç ana kanaldan sunar:

Hedef Ortam	Paket	Kurulum / Çalıştırma	Temel Kullanım Amacı
Yapay Zeka (AI / LLM)	burkut-mcp	npx -y burkut-mcp	Claude Desktop, Cursor ve Windsurf ajanlarına canlı borsa bağlama
Python (3.8+)	burkut	pip install burkut	Algoritmik işlemler, kantitatif finans, Pandas ile veri analizi
TypeScript / Node.js (18+)	burkut	npm install burkut	Web servisleri, Discord/Telegram botları, kurumsal entegrasyonlar

---

1. Model Context Protocol (MCP Server)

Türkiye piyasalarını Claude Desktop, Cursor IDE veya Windsurf yapay zeka ajanlarınıza sıfır kurulum zahmetiyle, tek satırda bağlayın.

Claude Desktop Entegrasyonu

Ayar dosyanızı açın:

• Windows: %APPDATA%\Claude\claude_desktop_config.json
• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Aşağıdaki yapılandırmayı ekleyin:

{
  "mcpServers": {
    "burkut": {
      "command": "npx",
      "args": ["-y", "burkut-mcp"],
      "env": {
        "BURKUT_API_KEY": "BURKUT_API_ANAHTARINIZ"
      }
    }
  }
}

Önemli: BURKUT_API_KEY zorunludur. Kotanızı takip etmek ve servisi kullanabilmek için burkutportfoy.com/developer adresinden saniyeler içinde ücretsiz API anahtarınızı oluşturup buraya ekleyin.

Cursor IDE Entegrasyonu

1. Cursor Settings → Features → MCP Servers yolunu izleyin.
2. Add New MCP Server butonuna tıklayın:
   • Name: burkut
   • Type: command
   • Command: npx -y burkut-mcp
   • Env: BURKUT_API_KEY=BURKUT_API_ANAHTARINIZ

Yapay Zekanıza Sorabileceğiniz Örnek Sorular

Entegrasyon tamamlandığında Claude veya Cursor doğrudan canlı piyasa verilerini çekip yorumlayabilir:

"TEFAS'taki hisse senedi fonları arasında son 1 yılda en çok kazandıran 5 fonu ve yıllık getirilerini listele."
"MAC ve TI2 fonlarının risk puanlarını ve son 6 aylık performanslarını karşılaştır."
"Bugün KAP'a düşen önemli şirket bildirimlerini ve yeni iş ilişkilerini özetle."
"Bu ay talep toplayacak halka arzlar hangileri? Dağıtım yöntemleri ve lot fiyatları nedir?"
"FROTO ve TUPRS şirketlerinin temettü verimlerini ve geçmiş ödeme tarihlerini karşılaştırmalı tablo yap."
"TÜİK tarafından açıklanan son yıllık TÜFE enflasyon oranı ile güncel dolar kurunu getir."

Detaylı MCP araç listesi ve parametreleri için mcp/README.md dosyasına göz atın.

---

2. Python SDK

Kurulum

pip install burkut

Hızlı Başlangıç

from burkut import BurkutClient

# API anahtarınız ile istemciyi başlatın (veya BURKUT_API_KEY ortam değişkenini kullanın)
client = BurkutClient(api_key="bk_live_...")

# 1. BIST Hisse Senedi Verisi (15 Dk Gecikmeli Resmi Akış)
thyao = client.stocks.get("THYAO")
print(f"{thyao['symbol']}: {thyao['last_price']} TL")

# 2. Bölünme Düzeltmeli Geçmiş OHLCV Verisi (250 Güne Kadar)
history = client.stocks.get_history("THYAO", days=250)
print(f"Alınan Bar Sayısı: {history['count']}")

# 3. Tek İstekle Tüm BIST Gün Sonu Kapanışları (Kotadan 1 Kredi Düşer)
eod = client.stocks.get_eod(date="2026-10-09")  # İsteğe bağlı geçmiş tarih veya boş bırakılarak son seans
print(f"{eod['date']} Kapanışında {eod['count']} Hisse")

# 4. Kamuyu Aydınlatma Platformu (KAP) Bildirimleri
kap_haberleri = client.kap.list(symbol="THYAO", size=5)
print(f"Son KAP Bildirimi: {kap_haberleri['items'][0]['title']}")

# 5. TEFAS Yatırım Fonu Analizi
mac = client.funds.get("MAC")
print(f"{mac['name']} - 1 Yıllık Getiri: %{mac.get('yield_1y')} | Risk: {mac.get('risk_level')}")

# 6. Döviz ve Altın Kurları
usd = client.forex.get("USD")
altin = client.gold.get("ALTIN")
print(f"USD/TRY: {usd['buying']} | Gram Altın: {altin['buying']} TL")

Pandas ile Kantitatif Analiz ve Tarama (Screening)

Piyasa verilerini tek satırda Pandas DataFrame'ine dönüştürerek analiz yapın:

import pandas as pd
from burkut import BurkutClient

client = BurkutClient()

# Tüm TEFAS fonlarını tek seferde al
funds = pd.DataFrame(client.funds.list())

# 1 yıllık getirisi %60 üzerinde olan hisse senedi fonlarını filtrele
screened = funds[
    (funds["category"].str.contains("Hisse", na=False)) & 
    (funds["yield_1y"] > 60.0)
].sort_values(by="yield_1y", ascending=False)

print(screened[["symbol", "name", "price", "yield_1y"]].head(10))

---

3. TypeScript / Node.js SDK

Kurulum

npm install burkut
# veya
pnpm add burkut

Hızlı Başlangıç

import { BurkutClient } from 'burkut';

const client = new BurkutClient({ 
  apiKey: process.env.BURKUT_API_KEY 
});

async function main() {
  // 1. Hisse anlık fiyatı
  const stock = await client.stocks.get('ASELS');
  console.log(`${stock.symbol}: ${stock.last_price} TL`);

  // 2. Geçmiş OHLCV bar verisi (bölünme düzeltmeli)
  const history = await client.stocks.getHistory('ASELS', { days: 250 });
  console.log(`Son 250 Günlük Mum Sayısı: ${history.count}`);

  // 3. Tek istekle tüm BIST hisselerinin gün sonu kapanışı (1 Kredi)
  const eod = await client.stocks.getEod('2026-10-09');
  console.log(`${eod.date} Kapanışı: ${eod.count} hisse`);

  // 4. Son KAP bildirimleri
  const kap = await client.kap.list({ symbol: 'ASELS', size: 5 });
  console.log(`Son KAP Bildirimi: ${kap.items[0]?.title}`);

  // 5. TEFAS fon listesi
  const funds = await client.funds.list();
  console.log(`Takip Edilen Fon Sayısı: ${funds.length}`);

  // 6. Döviz ve altın kurları
  const usd = await client.forex.get('USD');
  const gold = await client.gold.get('ALTIN');
  console.log(`Dolar: ${usd.buying} TL | Gram Altın: ${gold.buying} TL`);
}


main();

---

Karşılaştırma Tablosu

Kriter	Bürküt Ekosistemi	yfinance	Geleneksel Scraper'lar	Web Arayüz Kazıma
Model Context Protocol (MCP)	Yerleşik (burkut-mcp)	Yok	Yok	Yok
TEFAS Fon Verileri	Eksiksiz REST API	Desteklenmiyor	Kırılgan HTML	IP Ban Riski
BIST Hisse Senetleri	15 Dk Gecikmeli	15 Dk Gecikmeli	Sürekli Değişen Yapı	Oturum Zorunluluğu
KAP Bildirimleri	Yapılandırılmış JSON	Yok	Karmaşık Tablo/PDF	Yok
Dış Bağımlılık (Dependencies)	Sıfır Bağımlılık	10+ Ağır Kütüphane	Selenium / Chromium	Puppeteer / Playwright
Tip Güvenliği (Type Safety)	Tam Type Hints / .d.ts	Zayıf	Yok	Yok
Hizmet Sürekliliği	Bellek Önbelleği & Fail-Safe	Yahoo UI Değişince Patlar	Kaynak Değişince Patlar	Yüksek Bakım Maliyeti

---

Hata Yönetimi

SDK istemcileri, ağ ve kota sınırlarını önceden yakalayan açık hata sınıfları içerir:

from burkut import (
    BurkutClient,
    AuthenticationError,
    RateLimitError,
    QuotaExceededError,
    NotFoundError,
)

client = BurkutClient()

try:
    data = client.stocks.get("THYAO")
except AuthenticationError:
    print("Geçersiz API Anahtarı! burkutportfoy.com/developer adresinden yenisini alın.")
except RateLimitError as e:
    print(f"Dakikalık hız sınırı aşıldı. {e.retry_after} saniye sonra tekrar deneyin.")
except QuotaExceededError:
    print("Aylık kota tükendi. Geliştirici portalından planınızı yükseltin.")
except NotFoundError:
    print("Aranan enstrüman bulunamadı.")

---

Depo Mimarisi

burkut-sdks/
├── assets/               # Marka ve logo görselleri
│   └── logo.png          # Bürküt kartal vektörel logosu
│
├── mcp/                  # Model Context Protocol Server (npx -y burkut-mcp)
│   ├── src/              # TypeScript MCP araçları ve API istemcisi
│   ├── dist/             # Derlenmiş stdio JSON-RPC dağıtımı
│   └── README.md         # MCP kurulum ve ajan entegrasyon kılavuzu
│
├── python/               # Python SDK (pip install burkut)
│   ├── burkut/           # İstemci çekirdeği, modeller ve endpointler
│   ├── tests/            # Birim testleri
│   └── pyproject.toml    # Standart PyPI paket konfigürasyonu
│
├── nodejs/               # Node.js & TypeScript SDK (npm install burkut)
│   ├── src/              # TypeScript kaynak kodları
│   ├── dist/             # CJS & ESM derleme çıktıları (.d.ts)
│   └── package.json      # NPM paket konfigürasyonu
│
└── .github/workflows/    # CI/CD: Çoklu versiyon otomatik test akışı

---

Ücretsiz API Anahtarı Nasıl Alınır?

1. burkutportfoy.com/register adresinden ücretsiz hesap açın.
2. E-posta adresinizi doğrulayın.
3. Geliştirici Portalı üzerinden Yeni Anahtar Oluştur butonuna tıklayın.
4. bk_live_... formatındaki anahtarınızı kopyalayıp projelerinizde kullanın.

---

Veri Sözlüğü & Sıkça Sorulan Sorular (FAQ)

Algoritmik işlem, teknik analiz ve veri saklama modelleri geliştiren geliştiriciler için önemli teknik açıklamalar:

1. Geçmiş fiyatlar ham mı, düzeltilmiş mi? (Splits & Dividends)

• Bölünme & Bedelsiz: history servisindeki OHLC fiyatları hisse bölünmelerine ve bedelsiz sermaye artırımlarına karşı geriye dönük düzeltilmiştir (split-adjusted). Böylece grafiklerinizde ve teknik göstergelerinizde (SMA, RSI vb.) suni fiyat uçurumları oluşmaz.
• Temettü: Nakit temettü düzeltmesi uygulanmamaktadır; fiyatlar bölünme düzeltmeli brüt piyasa kapanışlarıdır.

2. Hacim (Volume) alanlarının birimi nedir?

• Anlık Snapshot (/stocks): Borsa İstanbul anlık seans özetinden gelir ve TL cinsinden toplam işlem tutarıdır (TRY Turnover).
• Geçmiş OHLCV (/history): Uluslararası standartlara uygun olarak günlük el değiştiren pay adedidir (Lot / Share Volume).
• Toplu Gün Sonu (/stocks/eod): Borsa bültenindeki resmi pay işlem tutarını TL cinsinden (TRY) temsil eder. Yanıttaki volume_unit alanı bunu teyit eder.

3. Günlük bar hangi saat dilimindedir ve ne zaman kesinleşir?

• timestamp değeri UTC Unix Epoch saniyesidir (07:00 UTC / 10:00 TSİ referans alınır).
• Seans saatleri içinde (10:00 – 18:10 TSİ) bugünün barı dinamiktir ve anlık son fiyatı close olarak yansıtır.
• BIST kapanış seansı tamamlandıktan sonra, resmi kesinleşmiş gün sonu barı 18:15 – 18:30 (TSİ) arasında sisteme işlenir.

4. Toplu Gün Sonu Servisi (/stocks/eod ve ?date=YYYY-MM-DD)

• Tek bir GET isteğinde tüm BIST paylarının (560+ hisse) tamamlanmış gün sonu OHLCV verisini döner.
• İsteğe bağlı ?date=YYYY-MM-DD parametresiyle kaçırılan geçmiş günlerin veya tatil öncesi seansların verisi topluca çekilebilir.
• Kotadan sadece 1 istek (1 kredi) düşer. 560 hisseyi tek tek çekip kotanızı tüketmek yerine günde 1 istekle tüm piyasayı yerel veritabanınıza senkronize edebilirsiniz.

---

Destek ve İletişim

• Teknik Destek & Geri Bildirim: destek@burkutportfoy.com
• Hata Bildirimi (Issues): github.com/sametakan29/burkut-sdks/issues

---

☕ Projeyi Destekleyin

Bürküt Finansal Veri Ekosistemi (Python SDK, Node.js SDK ve MCP Server), Türkiye sermaye piyasalarında analiz, algoritmik işlem ve yapay zeka modelleri geliştiren topluluk için tamamen açık kaynak ve ücretsiz olarak bir mühendislik öğrencisi tarafından sürdürülmektedir.

Canlı borsa veri akışı, bulut sunucu ve API kota maliyetlerimizin karşılanmasına katkıda bulunarak projenin özgürce yaşamasına destek olmak isterseniz bir kahve ısmarlayabilirsiniz:

• Resmi Destek Sayfası: kreosus.com/burkutportfoy
• Destek ödemeleri, BDDK lisanslı ve TCMB onaylı yerli ödeme geçidi (iyzico / 3D Secure) altyapısıyla güvenle gerçekleştirilmektedir.

---

Yasal Bilgilendirme ve Feragatname

Bu kütüphaneler ve veri servisleri araştırma, kişisel analiz ve yazılım geliştirme amaçlarıyla sunulmaktadır.

• Gecikmeli Veri: Borsa İstanbul (BIST) pay piyasası verileri yasal düzenlemeler uyarınca 15 dakika gecikmelidir.
• Yatırım Tavsiyesi Değildir: Sunulan veriler yatırım danışmanlığı, hisse önerisi veya alım-satım tavsiyesi niteliği taşımaz.
• Hizmet Garantisi: Veriler üçüncü taraf halka açık kaynaklardan derlenmekte olup, kaynak tarafındaki kesintilerde garanti taahhüt edilmez.

---

Lisans

Bu proje MIT Lisansı ile dağıtılmaktadır. Telif Hakkı © 2026 Bürküt Finansal Teknolojiler.