borsapy 0.8.4

Turkish financial markets data library - yfinance-like API for BIST stocks, forex, crypto, and more

borsapy

Sorumluluk Reddi / Disclaimer

Bu kütüphane yalnızca kişisel kullanım ve eğitim amaçlıdır. Ticari yazılım ürünleri geliştirmek, ticari hizmetlerde kullanmak veya herhangi bir ticari amaçla kullanılamaz. Ticari kullanım için uygun bir lisans satın almak üzere Borsa İstanbul ile iletişime geçmelisiniz.

This library is for personal and educational use only. It cannot be used for developing commercial software products, commercial services, or any commercial purposes. For commercial use, you must contact Borsa Istanbul to purchase an appropriate license.

Türk finansal piyasaları için Python veri kütüphanesi. BIST hisseleri, döviz, kripto, yatırım fonları ve ekonomik veriler için yfinance benzeri API.

Kurulum

pip install borsapy

# Twitter/X tweet arama için (optional)
pip install borsapy[twitter]

Hızlı Başlangıç

import borsapy as bp

# Hisse senedi verisi
hisse = bp.Ticker("THYAO")
print(hisse.info)                    # Anlık fiyat ve şirket bilgileri
print(hisse.history(period="1ay"))   # Geçmiş OHLCV verileri
print(hisse.balance_sheet)           # Bilanço

# Çoklu hisse
data = bp.download(["THYAO", "GARAN", "AKBNK"], period="1ay")
print(data)

# Döviz
usd = bp.FX("USD")
print(usd.current)                   # Güncel kur
print(usd.history(period="1ay"))     # Geçmiş veriler

# Kripto
btc = bp.Crypto("BTCTRY")
print(btc.current)                   # Güncel fiyat

# Yatırım fonu
fon = bp.Fund("AAK")
print(fon.info)                      # Fon bilgileri

# Enflasyon
enf = bp.Inflation()
print(enf.latest())                  # Son TÜFE verileri

Komut Satırı Arayüzü (CLI)

borsapy, terminal üzerinden hızlı veri erişimi için kapsamlı bir CLI sunar:

# Fiyat sorgula
borsapy price THYAO GARAN ASELS

# Geçmiş verileri CSV'ye kaydet
borsapy history THYAO --period 1y --output csv > thyao.csv

# Teknik sinyaller
borsapy signals THYAO --interval 1h

# Canlı izleme
borsapy watch THYAO GARAN --interval 0.5

# Teknik tarama
borsapy scan "rsi < 30 and volume > 1000000" --index XU100

# Temel tarama
borsapy screen --template high_dividend --index XU030

CLI Dokümantasyonu → | 25+ komut: fiyat, geçmiş, teknik analiz, mali tablolar, tarama ve daha fazlası.

---

Ticker (Hisse Senedi)

Ticker sınıfı, BIST hisse senetleri için kapsamlı veri erişimi sağlar.

Temel Kullanım

import borsapy as bp

hisse = bp.Ticker("THYAO")

# Hızlı fiyat bilgisi (cache'den, API çağrısı yapmaz)
print(hisse.fast_info["last_price"])     # Son fiyat
print(hisse.fast_info["previous_close"]) # Önceki kapanış
print(hisse.fast_info["volume"])         # Hacim
print(hisse.fast_info["market_cap"])     # Piyasa değeri
print(hisse.fast_info["pe_ratio"])       # F/K oranı
print(hisse.fast_info["free_float"])     # Halka açıklık oranı
print(hisse.fast_info["foreign_ratio"])  # Yabancı oranı

# Detaylı bilgiler (tüm verileri yükler)
print(hisse.info["last"])           # Son fiyat
print(hisse.info["marketCap"])      # Piyasa değeri
print(hisse.info["trailingPE"])     # F/K oranı
print(hisse.info["dividendYield"])  # Temettü verimi

Fiyat Geçmişi

💡 TradingView Veri Kaynağı: BIST fiyat verileri TradingView WebSocket API üzerinden sağlanır. Varsayılan olarak ~15 dakika gecikmeli. Gerçek zamanlı veri için TradingView Kimlik Doğrulama bölümüne bakın.

# Dönem bazlı
df = hisse.history(period="1ay")    # Son 1 ay
df = hisse.history(period="3ay")    # Son 3 ay
df = hisse.history(period="1y")     # Son 1 yıl
df = hisse.history(period="max")    # Tüm geçmiş

# Tarih aralığı
df = hisse.history(start="2024-01-01", end="2024-06-30")

# Split-unadjusted (gerçek) fiyatlar
df = hisse.history(period="max", adjust=False)

# Farklı zaman dilimleri (interval)
df = hisse.history(period="1g", interval="1m")   # 1 dakikalık mumlar
df = hisse.history(period="1g", interval="3m")   # 3 dakikalık mumlar
df = hisse.history(period="1g", interval="5m")   # 5 dakikalık mumlar
df = hisse.history(period="1g", interval="15m")  # 15 dakikalık mumlar
df = hisse.history(period="1g", interval="30m")  # 30 dakikalık mumlar
df = hisse.history(period="1g", interval="45m")  # 45 dakikalık mumlar
df = hisse.history(period="5g", interval="1h")   # Saatlik mumlar
df = hisse.history(period="1ay", interval="1d")  # Günlük mumlar (varsayılan)

Finansal Tablolar

# Yıllık tablolar (sınai şirketler için)
print(hisse.balance_sheet)          # Bilanço (70 satır)
print(hisse.income_stmt)            # Gelir tablosu (43 satır)
print(hisse.cashflow)               # Nakit akış (34 satır)

# Çeyreklik tablolar
print(hisse.quarterly_balance_sheet)
print(hisse.quarterly_income_stmt)
print(hisse.quarterly_cashflow)

# TTM (Son 12 ay)
print(hisse.ttm_income_stmt)
print(hisse.ttm_cashflow)

# Daha fazla dönem çek (last_n parametresi)
print(hisse.get_income_stmt(last_n=10))                  # 10 yıllık gelir tablosu
print(hisse.get_balance_sheet(quarterly=True, last_n=20)) # 20 çeyreklik bilanço
print(hisse.get_cashflow(last_n="all"))                   # Tüm mevcut dönemler

# Bankalar için (UFRS formatı — sadece bilanço ve gelir tablosu)
banka = bp.Ticker("AKBNK")
print(banka.get_balance_sheet(financial_group="UFRS"))  # 130 satır
print(banka.get_income_stmt(financial_group="UFRS"))    # 62 satır

# Banka çeyreklik tablolar
print(banka.get_balance_sheet(quarterly=True, financial_group="UFRS"))
print(banka.get_income_stmt(quarterly=True, financial_group="UFRS"))

# Banka TTM
print(banka.get_ttm_income_stmt(financial_group="UFRS"))

Not: Sınai şirketler varsayılan olarak XI_29 formatını kullanır. Bankalar için financial_group="UFRS" parametresi gereklidir.

UFRS banka formatında nakit akış tablosu (get_cashflow) bulunmamaktadır. get_cashflow(financial_group="UFRS") çağrısı DataNotAvailableError fırlatır.

last_n parametresi: None (varsayılan 5 dönem), int (tam sayı kadar dönem), "all" (tüm mevcut dönemler). 5'ten fazla dönem istendiğinde otomatik olarak birden fazla API çağrısı yapılır.

Temettü ve Sermaye Artırımları

print(hisse.dividends)              # Temettü geçmişi
print(hisse.splits)                 # Sermaye artırımları
print(hisse.actions)                # Tüm kurumsal işlemler

# Geçmiş verilerde temettü ve split
df = hisse.history(period="1y", actions=True)

Ortaklık Yapısı

print(hisse.major_holders)          # Ana ortaklar

Analist Verileri

print(hisse.analyst_price_targets)  # Hedef fiyatlar
print(hisse.recommendations_summary) # AL/TUT/SAT dağılımı
print(hisse.recommendations)        # Detaylı tavsiyeler

KAP Bildirimleri

print(hisse.news)                   # Son bildirimler
print(hisse.calendar)               # Beklenen açıklamalar
print(hisse.earnings_dates)         # Finansal rapor tarihleri

Diğer Bilgiler

print(hisse.isin)                   # ISIN kodu
print(hisse.info["sector"])         # Sektör
print(hisse.info["industry"])       # Alt sektör
print(hisse.info["website"])        # Web sitesi
print(hisse.info["longBusinessSummary"])  # Faaliyet konusu

ETF Sahipliği

Uluslararası ETF'lerin hisse pozisyonlarını görüntüleme.

import borsapy as bp

stock = bp.Ticker("ASELS")

# ETF holder listesi (DataFrame)
holders = stock.etf_holders
print(holders)
#    symbol exchange                                      name  market_cap_usd  holding_weight_pct           issuer
# 0    IEMG     AMEX  iShares Core MSCI Emerging Markets ETF    118225730.76            0.090686  BlackRock, Inc.
# 1     VWO     AMEX     Vanguard FTSE Emerging Markets ETF     85480000.00            0.060000     Vanguard Inc

print(f"Total ETFs: {len(holders)}")
print(f"Top holder: {holders.iloc[0]['name']}")
print(f"Total weight: {holders['holding_weight_pct'].sum():.2f}%")

DataFrame Sütunları:

Sütun	Açıklama
symbol	ETF sembolü (IEMG, VWO, TUR)
exchange	Borsa (AMEX, NASDAQ, LSE, XETR)
name	ETF tam adı
market_cap_usd	ETF'in bu hissedeki pozisyon değeri (USD)
holding_weight_pct	Ağırlık yüzdesi (0.09 = %0.09)
issuer	İhraççı (BlackRock, Vanguard, vb.)
expense_ratio	Gider oranı
aum_usd	Toplam varlık (USD)

---

Tickers ve download (Çoklu Hisse)

Birden fazla hisse için toplu veri çekme.

Tickers Sınıfı

import borsapy as bp

# Birden fazla hisse
hisseler = bp.Tickers(["THYAO", "GARAN", "AKBNK"])

# Her hissenin bilgilerine erişim
for sembol in hisseler.symbols:
    ticker = hisseler.tickers[sembol]
    print(f"{sembol}: {ticker.info['last']}")

download Fonksiyonu

# Basit kullanım
df = bp.download(["THYAO", "GARAN", "AKBNK"], period="1ay")

# Ticker bazlı gruplama
df = bp.download(["THYAO", "GARAN"], period="1ay", group_by="ticker")

# Sütun bazlı gruplama (varsayılan)
df = bp.download(["THYAO", "GARAN"], period="1ay", group_by="column")

---

Index (Endeksler)

BIST endekslerine erişim - 79 endeks, bileşen listeleri dahil.

💡 TradingView Veri Kaynağı: Endeks fiyat verileri TradingView WebSocket API üzerinden sağlanır. Varsayılan olarak ~15 dakika gecikmeli. Gerçek zamanlı veri için TradingView Kimlik Doğrulama bölümüne bakın.

Temel Kullanım

import borsapy as bp

# Mevcut endeksler (33 popüler endeks)
print(bp.indices())
# ['XU100', 'XU050', 'XU030', 'XKTUM', 'XK100', 'XK030', 'XBANK', ...]

# Detaylı liste (bileşen sayısı ile)
print(bp.indices(detailed=True))
# [{'symbol': 'XU100', 'name': 'BIST 100', 'count': 100}, ...]

# Tüm BIST endeksleri (79 endeks)
print(bp.all_indices())
# [{'symbol': 'X030C', 'name': 'BIST 30 Capped', 'count': 30}, ...]

# Endeks verisi
xu100 = bp.Index("XU100")
print(xu100.info)                    # Güncel değer, değişim
print(xu100.history(period="1ay"))   # OHLCV geçmişi

Endeks Bileşenleri

# Endeks içindeki hisseler
xu030 = bp.Index("XU030")
print(xu030.components)              # [{'symbol': 'AKBNK', 'name': 'AKBANK'}, ...]
print(xu030.component_symbols)       # ['AKBNK', 'ASELS', 'BIMAS', ...]
print(len(xu030.components))         # 30

# Katılım endeksleri
xk030 = bp.Index("XK030")            # BIST Katılım 30
print(xk030.components)              # Faizsiz finans uyumlu 30 hisse
print(xk030.component_symbols)

xktum = bp.Index("XKTUM")            # BIST Katılım Tüm
print(len(xktum.components))         # 218 hisse

Desteklenen Endeksler

Kategori	Endeksler
Ana	XU100, XU050, XU030, XUTUM
Katılım	XKTUM, XK100, XK050, XK030, XKTMT
Sektör	XBANK, XUSIN, XUMAL, XUTEK, XGIDA, XHOLD, ...
Tematik	XSRDK, XKURY, XYLDZ, XSPOR, XGMYO, ...
Şehir	XSIST, XSANK, XSIZM, XSBUR, ...

---

FX (Döviz ve Emtia)

Döviz kurları ve emtia fiyatları. 65 döviz desteği.

Döviz Kurları

import borsapy as bp

usd = bp.FX("USD")
print(usd.current)                  # Güncel kur
print(usd.history(period="1ay"))    # Geçmiş veriler (günlük)

# Majör dövizler
eur = bp.FX("EUR")
gbp = bp.FX("GBP")
chf = bp.FX("CHF")
jpy = bp.FX("JPY")
cad = bp.FX("CAD")
aud = bp.FX("AUD")

# Diğer dövizler (65 döviz destekleniyor)
rub = bp.FX("RUB")    # Rus Rublesi
cny = bp.FX("CNY")    # Çin Yuanı
sar = bp.FX("SAR")    # Suudi Riyali
aed = bp.FX("AED")    # BAE Dirhemi
inr = bp.FX("INR")    # Hindistan Rupisi
# ... ve daha fazlası

Dakikalık/Saatlik Veri (TradingView)

Bazı döviz çiftleri için intraday (dakikalık/saatlik) veri TradingView üzerinden sağlanır.

💡 Gerçek Zamanlı Veri: TradingView verileri varsayılan olarak ~15 dakika gecikmeli. Gerçek zamanlı veri için TradingView Kimlik Doğrulama bölümüne bakın.

import borsapy as bp

usd = bp.FX("USD")

# Dakikalık veri
df = usd.history(period="1g", interval="1m")    # Son 1 gün, 1 dakikalık
df = usd.history(period="1g", interval="5m")    # 5 dakikalık
df = usd.history(period="1g", interval="15m")   # 15 dakikalık
df = usd.history(period="1g", interval="30m")   # 30 dakikalık

# Saatlik veri
df = usd.history(period="5g", interval="1h")    # Son 5 gün, saatlik
df = usd.history(period="1ay", interval="4h")   # Son 1 ay, 4 saatlik

# Günlük ve üstü (varsayılan, canlidoviz kullanır)
df = usd.history(period="1ay", interval="1d")   # Günlük
df = usd.history(period="1ay")                  # Günlük (varsayılan)

İntraday Destekleyen Dövizler (TradingView):

Döviz	Symbol	Not
USD/TRY	USD	FX:USDTRY
EUR/TRY	EUR	FX:EURTRY
GBP/TRY	GBP	PEPPERSTONE:GBPTRY
TRY/JPY	JPY	FX:TRYJPY (ters çift)

İntraday Destekleyen Emtialar (TradingView):

Emtia	Symbol	Not
Altın (Ons/USD)	ons-altin veya XAU	OANDA:XAUUSD
Gümüş (Ons/USD)	XAG	OANDA:XAGUSD
Platin (USD)	XPT	OANDA:XPTUSD
Paladyum (USD)	XPD	OANDA:XPDUSD
Brent Petrol	BRENT	TVC:UKOIL
WTI Petrol	WTI	TVC:USOIL

Not: Diğer dövizler (CHF, CAD, AUD, vb.) için TradingView'da TRY çifti bulunmadığından sadece günlük veri mevcuttur (canlidoviz.com). İntraday desteklenmeyen bir döviz için interval belirtilirse hata verir.

Desteklenen Dövizler

Kategori	Dövizler
Majör	USD, EUR, GBP, CHF, JPY, CAD, AUD, NZD
Avrupa	DKK, SEK, NOK, PLN, CZK, HUF, RON, BGN, HRK, RSD, BAM, MKD, ALL, MDL, UAH, BYR, ISK
Ortadoğu & Afrika	AED, SAR, QAR, KWD, BHD, OMR, JOD, IQD, IRR, LBP, SYP, EGP, LYD, TND, DZD, MAD, ZAR, ILS
Asya & Pasifik	CNY, INR, PKR, LKR, IDR, MYR, THB, PHP, KRW, KZT, AZN, GEL, SGD, HKD, TWD
Amerika	MXN, BRL, ARS, CLP, COP, PEN, UYU, CRC
Diğer	RUB, DVZSP1 (Sepet Kur)

Banka Kurları

import borsapy as bp

usd = bp.FX("USD")

# Tüm bankaların kurları
print(usd.bank_rates)               # DataFrame: bank, buying, selling, updated
#          bank  buying  selling              updated
# 0      Akbank   34.85    35.15  2024-01-15 10:30:00
# 1    Garanti   34.82    35.12  2024-01-15 10:28:00
# ...

# Tek banka kuru
print(usd.bank_rate("akbank"))      # {'buying': 34.85, 'selling': 35.15, ...}
print(usd.bank_rate("garanti"))

# Desteklenen bankalar
print(bp.banks())                   # ['akbank', 'garanti', 'isbank', ...]

Altın ve Emtialar

# Altın (TRY)
gram_altin = bp.FX("gram-altin")
ceyrek = bp.FX("ceyrek-altin")
yarim = bp.FX("yarim-altin")
tam = bp.FX("tam-altin")
cumhuriyet = bp.FX("cumhuriyet-altin")
ata = bp.FX("ata-altin")

# Diğer değerli metaller (TRY)
gumus = bp.FX("gram-gumus")
ons_altin = bp.FX("ons-altin")
platin = bp.FX("gram-platin")

# Emtia (USD)
brent = bp.FX("BRENT")           # Brent Petrol
silver = bp.FX("XAG-USD")        # Gümüş Ons
platinum = bp.FX("XPT-USD")      # Platin Spot
palladium = bp.FX("XPD-USD")     # Paladyum Spot

print(gram_altin.current)
print(gram_altin.history(period="1ay"))

Kurum Fiyatları (Kuyumcu/Banka)

# Değerli metal kurum fiyatları
gold = bp.FX("gram-altin")

# Tüm kurumların fiyatları
print(gold.institution_rates)
#       institution institution_name       asset      buy     sell  spread
# 0     altinkaynak      Altınkaynak  gram-altin  6315.00  6340.00    0.40
# 1          akbank           Akbank  gram-altin  6310.00  6330.00    0.32

# Tek kurum fiyatı
print(gold.institution_rate("kapalicarsi"))
print(gold.institution_rate("akbank"))

# Desteklenen emtialar
print(bp.metal_institutions())
# ['gram-altin', 'gram-gumus', 'ons-altin', 'gram-platin']

Kurum Bazlı Geçmiş (Metal + Döviz)

# Metal geçmişi
gold = bp.FX("gram-altin")
gold.institution_history("akbank", period="1mo")       # Akbank 1 aylık
gold.institution_history("kapalicarsi", period="3mo")  # Kapalıçarşı 3 aylık

# Döviz geçmişi
usd = bp.FX("USD")
usd.institution_history("akbank", period="1mo")        # Akbank USD 1 aylık
usd.institution_history("garanti-bbva", period="5d")   # Garanti 5 günlük

# 27 kurum destekleniyor (bankalar + kuyumcular)
# Kuyumcular (kapalicarsi, harem, altinkaynak) OHLC verir
# Bankalar (akbank, garanti) sadece Close verir

---

Crypto (Kripto Para)

BtcTurk üzerinden kripto para verileri.

import borsapy as bp

# Mevcut çiftler
print(bp.crypto_pairs())

# Bitcoin/TRY
btc = bp.Crypto("BTCTRY")
print(btc.current)                  # Güncel fiyat
print(btc.history(period="1ay"))    # OHLCV geçmişi

# Ethereum/TRY
eth = bp.Crypto("ETHTRY")
print(eth.current)

---

Fund (Yatırım ve Emeklilik Fonları)

TEFAS üzerinden yatırım fonu ve emeklilik fonu verileri.

Temel Kullanım

import borsapy as bp

# Fon arama
print(bp.search_funds("banka"))

# Yatırım Fonu (YAT) - varsayılan
fon = bp.Fund("AAK")
print(fon.info)                     # Fon bilgileri
print(fon.history(period="1mo"))    # Fiyat geçmişi
print(fon.performance)              # Performans verileri

# Emeklilik Fonu (EMK) - explicit
emk = bp.Fund("KJM", fund_type="EMK")
print(emk.info)                     # Emeklilik fonu bilgileri
print(emk.history(period="1mo"))    # Fiyat geçmişi

# Auto-detection: fund_type belirtilmezse otomatik algılanır
emk = bp.Fund("KJM")                # Otomatik olarak EMK algılanır
print(emk.fund_type)                # "EMK"

Fon Tipleri

Kod	Açıklama	Örnek
YAT	Yatırım Fonları (Investment Funds)	bp.Fund("AAK")
EMK	Emeklilik Fonları (Pension Funds)	bp.Fund("KJM", fund_type="EMK")

Not: fund_type belirtilmezse otomatik algılama yapılır (önce YAT, sonra EMK denenir).

Varlık Dağılımı

# Portföy varlık dağılımı
print(fon.allocation)               # Son 7 günlük dağılım
print(fon.allocation_history(period="3ay"))  # Son 3 ay (max ~100 gün)
#         date     asset_type    asset_name  weight
# 0 2024-01-15   Hisse Senedi        Stocks   45.2
# 1 2024-01-15      Ters-Repo  Reverse Repo   30.1
# ...

# info içinde de mevcut (ekstra API çağrısı yok)
print(fon.info['allocation'])
print(fon.info['isin'])             # ISIN kodu
print(fon.info['daily_return'])     # Günlük getiri
print(fon.info['weekly_return'])    # Haftalık getiri
print(fon.info['category_rank'])    # Kategori sırası (örn: 20/181)

Fon Tarama

# Yatırım fonlarını filtrele (varsayılan)
df = bp.screen_funds(fund_type="YAT", min_return_1y=50)   # >%50 1Y getiri
df = bp.screen_funds(min_return_1m=5)                     # Son 1 ayda >%5

# Emeklilik fonlarını filtrele
df = bp.screen_funds(fund_type="EMK")                     # Tüm emeklilik fonları
df = bp.screen_funds(fund_type="EMK", min_return_ytd=20)  # >%20 YTD getiri
df = bp.screen_funds(fund_type="EMK", min_return_1y=30)   # >%30 1Y getiri

# Fon tipleri: "YAT" (yatırım - varsayılan), "EMK" (emeklilik)

Fon Karşılaştırma

# Birden fazla fonu karşılaştır (max 10)
result = bp.compare_funds(["AAK", "TTE", "AFO"])

print(result['funds'])              # Fon detayları listesi
print(result['rankings'])           # Sıralamalar
#   by_return_1y: ['AFO', 'TTE', 'AAK']
#   by_size: ['AFO', 'TTE', 'AAK']
#   by_risk_asc: ['AAK', 'TTE', 'AFO']

print(result['summary'])            # Özet
#   fund_count: 3
#   total_size: 23554985554.72
#   avg_return_1y: 53.65
#   best_return_1y: 100.84
#   worst_return_1y: 28.15

Yönetim Ücretleri

import borsapy as bp

# Tüm yatırım fonu yönetim ücretleri
df = bp.management_fees()
print(df)
#   fund_code                              name  applied_fee  prospectus_fee  max_expense_ratio  annual_return
# 0       AAK  ATA PORTFÖY ÇOKLU VARLIK DEĞİ...          1.0             2.2               3.65           45.5

# Emeklilik fonu ücretleri
df_emk = bp.management_fees(fund_type="EMK")

# Kurucu filtresi
df_akp = bp.management_fees(founder="AKP")

# Tek fon için
fon = bp.Fund("AAK")
print(fon.management_fee)
# {'applied_fee': 1.0, 'prospectus_fee': 2.2, 'max_expense_ratio': 3.65, 'annual_return': 45.5}

DataFrame Sütunları:

Sütun	Açıklama
fund_code	TEFAS fon kodu
name	Fon tam adı
fund_category	Fon kategorisi
founder_code	Kurucu şirket kodu
applied_fee	Uygulanan yıllık yönetim ücreti (%)
prospectus_fee	İzahname yönetim ücreti (%)
max_expense_ratio	Azami toplam gider kesinti oranı (%)
annual_return	Yıllık getiri (%)

Risk Metrikleri

fon = bp.Fund("YAY")

# Sharpe oranı (10Y tahvil faizi ile)
print(fon.sharpe_ratio())              # 1Y Sharpe
print(fon.sharpe_ratio(period="3y"))   # 3Y Sharpe

# Tüm risk metrikleri
metrics = fon.risk_metrics(period="1y")
print(metrics['annualized_return'])     # Yıllık getiri (%)
print(metrics['annualized_volatility']) # Yıllık volatilite (%)
print(metrics['sharpe_ratio'])          # Sharpe oranı
print(metrics['sortino_ratio'])         # Sortino oranı (downside risk)
print(metrics['max_drawdown'])          # Maksimum düşüş (%)

# Uzun dönem desteği
fon.history(period="3y")   # 3 yıllık veri
fon.history(period="5y")   # 5 yıllık veri
fon.history(period="max")  # Tüm veri (5 yıla kadar)

Stopaj Oranları (Withholding Tax)

Gelir Vergisi Kanunu geçici 67. madde kapsamında fon stopaj oranlarını sorgulama.

import borsapy as bp

# Tek fon için stopaj oranı
fon = bp.Fund("AAK")
print(fon.tax_category)                           # "degisken_karma_doviz"
print(fon.withholding_tax_rate("2025-06-01"))      # 0.15 (15%)
print(fon.withholding_tax_rate("2025-08-01"))      # 0.175 (17.5%)

# Pay senedi yoğun fon → her zaman %0
hisse_fon = bp.Fund("TTE")
print(hisse_fon.tax_category)                      # "pay_senedi_yogun"
print(hisse_fon.withholding_tax_rate("2025-08-01")) # 0.0 (0%)

# Standalone fonksiyon (fund kodu ile)
print(bp.withholding_tax_rate("AAK", "2025-06-01"))  # 0.15

# Referans tablo
print(bp.withholding_tax_table())
#   tax_category          description              <23.12.2020  ...  >=09.07.2025
# 0  degisken_karma_doviz  Degisken, karma, ...         10.0  ...         17.5
# 1  pay_senedi_yogun      Pay senedi yogun fon          0.0  ...          0.0
# ...

Vergi Kategorileri:

Kategori	Açıklama	>=09.07.2025
degisken_karma_doviz	Değişken, karma, eurobond, dış borçlanma, yabancı, serbest + döviz	%17.5
pay_senedi_yogun	Pay senedi yoğun fon	%0
borclanma_para_maden	Borçlanma araçları, para piyasası, kıymetli maden, katılım	%17.5
gsyf_gyf_uzun	GSYF/GYF (>2 yıl)	%0
gsyf_gyf_kisa	GSYF/GYF (<2 yıl)	%17.5

---

Portfolio (Portföy Yönetimi)

Çoklu varlık portföylerini yönetme, performans takibi ve risk metrikleri.

Temel Kullanım

import borsapy as bp
from datetime import date

# Portföy oluşturma
portfolio = bp.Portfolio()

# Varlık ekleme (4 tip destekleniyor)
portfolio.add("THYAO", shares=100, cost=280.0)          # Hisse - adet + maliyet
portfolio.add("GARAN", shares=200)                       # Hisse - güncel fiyattan
portfolio.add("gram-altin", shares=10, asset_type="fx")  # Emtia/Döviz (FX)
portfolio.add("USD", shares=1000, asset_type="fx")       # Döviz
portfolio.add("BTCTRY", shares=0.5)                      # Kripto (auto-detect)
portfolio.add("YAY", shares=1000, asset_type="fund")     # Yatırım Fonu

# Alım tarihi ile ekleme (getiri hesaplamaları için)
portfolio.add("ASELS", shares=50, cost=120.0, purchase_date="2024-01-15")  # String format
portfolio.add("BIMAS", shares=30, cost=150.0, purchase_date=date(2024, 6, 1))  # date objesi

# Benchmark ayarlama (Index karşılaştırması için)
portfolio.set_benchmark("XU100")                         # XU030, XK030 da olabilir

# Portföy durumu
print(portfolio.holdings)     # DataFrame: symbol, shares, cost, value, weight, pnl, purchase_date, holding_days
print(portfolio.value)        # Toplam değer (TL)
print(portfolio.cost)         # Toplam maliyet
print(portfolio.pnl)          # Kar/zarar (TL)
print(portfolio.pnl_pct)      # Kar/zarar (%)
print(portfolio.weights)      # {'THYAO': 0.45, 'GARAN': 0.35, ...}

Alım Tarihi (purchase_date)

Holdinglere alım tarihi eklenerek daha isabetli getiri hesaplamaları yapılabilir:

import borsapy as bp
from datetime import date

portfolio = bp.Portfolio()

# Farklı tarihlerde alınmış hisseler
portfolio.add("THYAO", shares=100, cost=280.0, purchase_date="2024-01-15")
portfolio.add("GARAN", shares=200, cost=45.0, purchase_date=date(2024, 6, 1))
portfolio.add("ASELS", shares=50, cost=120.0)  # Tarih verilmezse bugün

# Holdings DataFrame'de purchase_date ve holding_days sütunları
print(portfolio.holdings[['symbol', 'cost', 'purchase_date', 'holding_days']])
#   symbol  cost purchase_date  holding_days
# 0  THYAO   280    2024-01-15           380
# 1  GARAN    45    2024-06-01           242
# 2  ASELS   120    2026-01-29             0

# Risk metrikleri artık holding bazlı tarih kullanır
# Her holding için sadece purchase_date sonrası veriler dahil edilir
metrics = portfolio.risk_metrics(period="1y")

Desteklenen Tarih Formatları:

Format	Örnek	Açıklama
str	"2024-01-15"	ISO format (YYYY-MM-DD)
date	date(2024, 1, 15)	Python date objesi
datetime	datetime(2024, 1, 15)	Sadece tarih kısmı kullanılır
None	-	Bugünün tarihi varsayılan

Desteklenen Varlık Tipleri

Tip	Sınıf	Otomatik Algılama	Örnekler
stock	Ticker	Varsayılan	THYAO, GARAN, ASELS
fx	FX	✅ 65 döviz + metaller + emtia	USD, EUR, gram-altin, BRENT
crypto	Crypto	✅ *TRY pattern (6+ karakter)	BTCTRY, ETHTRY
fund	Fund	❌ asset_type="fund" gerekli	AAK, TTE, YAY

Not: Index'ler (XU100, XU030) satın alınamaz, benchmark olarak kullanılır.

Performans ve Geçmiş

# Geçmiş performans (mevcut pozisyonlarla)
hist = portfolio.history(period="1y")
print(hist)
#                   Value  Daily_Return
# Date
# 2024-01-02  150000.00           NaN
# 2024-01-03  152300.00      0.0153
# ...

# Performans özeti
print(portfolio.performance)
# {'total_return': 25.5, 'total_value': 187500.0, 'total_cost': 150000.0, 'total_pnl': 37500.0}

Risk Metrikleri

# Tüm risk metrikleri
metrics = portfolio.risk_metrics(period="1y")
print(metrics)
# {'annualized_return': 18.2,
#  'annualized_volatility': 22.5,
#  'sharpe_ratio': 0.65,
#  'sortino_ratio': 0.82,
#  'max_drawdown': -15.3,
#  'beta': 1.12,
#  'alpha': 2.5,
#  'risk_free_rate': 28.0,
#  'trading_days': 252}

# Kısa yollar
print(portfolio.sharpe_ratio())           # Sharpe oranı
print(portfolio.sortino_ratio())          # Sortino oranı
print(portfolio.beta())                   # Benchmark'a göre beta (varsayılan: XU100)
print(portfolio.beta(benchmark="XU030"))  # Farklı benchmark

# Korelasyon matrisi
corr = portfolio.correlation_matrix(period="1y")
print(corr)
#          THYAO    GARAN  gram-altin
# THYAO     1.00     0.75       0.15
# GARAN     0.75     1.00       0.12
# gram-altin 0.15    0.12       1.00

Varlık Yönetimi

# Varlık güncelleme
portfolio.update("THYAO", shares=150, cost=290.0)

# Varlık kaldırma
portfolio.remove("GARAN")

# Portföyü temizle
portfolio.clear()

# Method chaining
portfolio.add("THYAO", shares=100, cost=280).add("GARAN", shares=200, cost=50).set_benchmark("XU030")

Portföy Dengeleme (Rebalancing)

import borsapy as bp

p = bp.Portfolio()
p.add("THYAO", shares=100, cost=280)
p.add("GARAN", shares=200, cost=50)
p.add("gram-altin", shares=5, asset_type="fx")

# Hedef ağırlıklar belirle (0-1 ölçeği, toplam ~1.0)
p.set_target_weights({"THYAO": 0.50, "GARAN": 0.30, "gram-altin": 0.20})

# Sapma analizi
print(p.drift())
#    symbol  current_weight  target_weight   drift  drift_pct
# 0   GARAN          0.2500         0.3000 -0.0500      -5.00
# 1   THYAO          0.7000         0.5000  0.2000      20.00
# 2   gram-altin     0.0500         0.2000 -0.1500     -15.00

# Dengeleme planı (eşik: %2 altındaki sapmalar yoksayılır)
plan = p.rebalance_plan(threshold=0.02)
print(plan)  # symbol, current_shares, target_shares, delta_shares, delta_value, action

# Dengelemeyi uygula
p.rebalance(threshold=0.02)

# Dry run (sadece plan, uygulama yok)
plan = p.rebalance(threshold=0.02, dry_run=True)

Import/Export

# Dict olarak export (target_weights dahil)
data = portfolio.to_dict()
print(data)
# {'benchmark': 'XU100', 'holdings': [
#     {'symbol': 'THYAO', 'shares': 100, 'cost_per_share': 280.0,
#      'asset_type': 'stock', 'purchase_date': '2024-01-15'},
#     ...
# ]}

# Dict'ten import (purchase_date korunur)
portfolio2 = bp.Portfolio.from_dict(data)

# JSON'a kaydetme
import json
with open("portfolio.json", "w") as f:
    json.dump(portfolio.to_dict(), f)

# JSON'dan yükleme
with open("portfolio.json") as f:
    portfolio3 = bp.Portfolio.from_dict(json.load(f))

Teknik Analiz (TechnicalMixin)

Portfolio sınıfı TechnicalMixin'den miras aldığı için teknik göstergeleri de kullanabilir:

# Portfolio history üzerinde teknik analiz
portfolio.rsi()                    # RSI
portfolio.sma()                    # SMA
portfolio.macd()                   # MACD
portfolio.bollinger_bands()        # Bollinger Bands

---

Teknik Analiz

Tüm varlık sınıfları için teknik analiz göstergeleri (Ticker, Index, Crypto, FX, Fund).

💡 TradingView Entegrasyonu: Teknik göstergeler (RSI, MACD, BB, ADX, ATR, Stochastic) TradingView Scanner API üzerinden hesaplanır. Bu sayede TradingView'daki değerlerle birebir uyumlu sonuçlar alırsınız. Varsayılan olarak ~15 dakika gecikmeli veri kullanılır. Gerçek zamanlı veri için TradingView Kimlik Doğrulama bölümüne bakın.

Tekil Değerler

import borsapy as bp

hisse = bp.Ticker("THYAO")

# RSI (Relative Strength Index)
print(hisse.rsi())                    # 65.2 (son değer)
print(hisse.rsi(rsi_period=7))        # 7 periyotluk RSI

# Hareketli Ortalamalar
print(hisse.sma())                    # 20 günlük SMA
print(hisse.sma(sma_period=50))       # 50 günlük SMA
print(hisse.ema(ema_period=12))       # 12 günlük EMA

# MACD
print(hisse.macd())
# {'macd': 2.5, 'signal': 1.8, 'histogram': 0.7}

# Bollinger Bands
print(hisse.bollinger_bands())
# {'upper': 310.2, 'middle': 290.5, 'lower': 270.8}

# Stochastic
print(hisse.stochastic())
# {'k': 75.2, 'd': 68.5}

# ATR (Average True Range)
print(hisse.atr())                    # 4.25

# OBV (On-Balance Volume)
print(hisse.obv())                    # 1250000

# VWAP (Volume Weighted Average Price)
print(hisse.vwap())                   # 285.5

# ADX (Average Directional Index)
print(hisse.adx())                    # 32.5

TechnicalAnalyzer ile Tam Seriler

import borsapy as bp

hisse = bp.Ticker("THYAO")

# TechnicalAnalyzer oluştur
ta = hisse.technicals(period="1y")

# Tüm göstergelerin son değerleri
print(ta.latest)
# {'sma_20': 285.5, 'ema_12': 287.2, 'rsi_14': 65.2, 'macd': 2.5, ...}

# Tek tek seriler (pd.Series)
print(ta.rsi())                       # 252 değerlik RSI serisi
print(ta.sma(20))                     # 20 günlük SMA serisi
print(ta.ema(12))                     # 12 günlük EMA serisi

# DataFrame döndürenler
print(ta.macd())                      # MACD, Signal, Histogram sütunları
print(ta.bollinger_bands())           # BB_Upper, BB_Middle, BB_Lower
print(ta.stochastic())                # Stoch_K, Stoch_D

DataFrame ile Tüm Göstergeler

import borsapy as bp

hisse = bp.Ticker("THYAO")

# OHLCV + tüm göstergeler tek DataFrame'de
df = hisse.history_with_indicators(period="3ay")
print(df.columns)
# ['Open', 'High', 'Low', 'Close', 'Volume', 'SMA_20', 'EMA_12',
#  'RSI_14', 'MACD', 'Signal', 'Histogram', 'BB_Upper', 'BB_Middle',
#  'BB_Lower', 'ATR_14', 'Stoch_K', 'Stoch_D', 'OBV', 'VWAP', 'ADX_14']

# Sadece belirli göstergeler
df = hisse.history_with_indicators(period="1ay", indicators=["sma", "rsi", "macd"])

Tüm Varlık Sınıflarında Çalışır

import borsapy as bp

# Hisse
bp.Ticker("THYAO").rsi()

# Endeks
bp.Index("XU100").macd()

# Kripto
bp.Crypto("BTCTRY").bollinger_bands()

# Döviz (Volume gerektiren göstergeler NaN döner)
bp.FX("USD").rsi()

# Yatırım Fonu
bp.Fund("AAK").stochastic()

# Altın
bp.FX("gram-altin").sma()

Standalone Fonksiyonlar

import borsapy as bp
from borsapy.technical import (
    calculate_sma, calculate_ema, calculate_rsi, calculate_macd,
    calculate_bollinger_bands, calculate_atr, calculate_stochastic,
    calculate_obv, calculate_vwap, calculate_adx, calculate_supertrend,
    calculate_tilson_t3, calculate_hhv, calculate_llv, calculate_mom,
    calculate_roc, calculate_wma, calculate_dema, calculate_tema,
    add_indicators
)

# Herhangi bir DataFrame üzerinde kullanım
df = bp.download("THYAO", period="1y")

# Tekil göstergeler
rsi = calculate_rsi(df, period=14)
macd_df = calculate_macd(df, fast=12, slow=26, signal=9)
bb_df = calculate_bollinger_bands(df, period=20, std_dev=2.0)

# Tüm göstergeleri ekle
df_with_indicators = add_indicators(df)
df_with_indicators = add_indicators(df, indicators=["sma", "rsi"])  # Sadece belirli göstergeler

Desteklenen Göstergeler

Gösterge	Metod	Açıklama
SMA	sma()	Basit Hareketli Ortalama
EMA	ema()	Üstel Hareketli Ortalama
RSI	rsi()	Göreceli Güç Endeksi (0-100)
MACD	macd()	Hareketli Ortalama Yakınsama/Iraksama
Bollinger Bands	bollinger_bands()	Üst/Orta/Alt bantlar
ATR	atr()	Ortalama Gerçek Aralık
Stochastic	stochastic()	Stokastik Osilatör (%K, %D)
OBV	obv()	Denge Hacmi (Volume gerektirir)
VWAP	vwap()	Hacim Ağırlıklı Ortalama Fiyat (Volume gerektirir)
ADX	adx()	Ortalama Yön Endeksi (0-100)
Supertrend	supertrend()	Trend takip göstergesi (ATR-tabanlı)
Tilson T3	tilson_t3()	Triple-smoothed EMA (düşük gecikme)
HHV	hhv()	En Yüksek Değer (MetaStock)
LLV	llv()	En Düşük Değer (MetaStock)
MOM	mom()	Momentum (MetaStock)
ROC	roc()	Değişim Oranı (MetaStock)
WMA	wma()	Ağırlıklı Hareketli Ortalama (MetaStock)
DEMA	dema()	Çift Üstel Hareketli Ortalama (MetaStock)
TEMA	tema()	Üçlü Üstel Hareketli Ortalama (MetaStock)

MetaStock Göstergeleri

Klasik MetaStock teknik göstergeleri.

import borsapy as bp

stock = bp.Ticker("THYAO")

# Mixin kısayolları (son değer)
stock.hhv()    # 14-period en yüksek High
stock.llv()    # 14-period en düşük Low
stock.mom()    # 10-period momentum (Close - Close[N])
stock.roc()    # 10-period değişim oranı (%)
stock.wma()    # 20-period ağırlıklı ortalama
stock.dema()   # 20-period çift EMA
stock.tema()   # 20-period üçlü EMA

# Pure fonksiyonlar
df = stock.history(period="1y")
hhv = bp.calculate_hhv(df, period=52, column="Close")   # 52-hafta yüksek
llv = bp.calculate_llv(df, period=52, column="Low")
mom = bp.calculate_mom(df, period=10)
roc = bp.calculate_roc(df, period=10)
wma = bp.calculate_wma(df, period=20)
dema = bp.calculate_dema(df, period=20)
tema = bp.calculate_tema(df, period=20)

# add_indicators ile toplu ekleme
df = bp.add_indicators(df, ["hhv", "llv", "mom", "roc", "wma", "dema", "tema"])

Gösterge	Fonksiyon	Varsayılan	Formül
HHV	calculate_hhv(df, period, column)	14, High	Rolling max
LLV	calculate_llv(df, period, column)	14, Low	Rolling min
MOM	calculate_mom(df, period)	10	Close - Close[N]
ROC	calculate_roc(df, period)	10	((C - C[N]) / C[N]) × 100
WMA	calculate_wma(df, period)	20	Lineer ağırlıklı ortalama
DEMA	calculate_dema(df, period)	20	2×EMA - EMA(EMA)
TEMA	calculate_tema(df, period)	20	3×EMA - 3×EMA(EMA) + EMA(EMA(EMA))

Supertrend

ATR-tabanlı trend takip göstergesi.

import borsapy as bp

stock = bp.Ticker("THYAO")

# Son değerler
st = stock.supertrend()
print(st['value'])       # 282.21 (Supertrend çizgisi)
print(st['direction'])   # 1 (bullish) veya -1 (bearish)
print(st['upper'])       # 303.69 (üst band)
print(st['lower'])       # 282.21 (alt band)

# Custom parametreler
st = stock.supertrend(period="6mo", atr_period=7, multiplier=2.0)

# TechnicalAnalyzer ile tüm seriler
ta = stock.technicals(period="1y")
st_df = ta.supertrend()  # DataFrame: Supertrend, Direction, Upper, Lower

# Pure function
df = stock.history(period="1y")
st_df = bp.calculate_supertrend(df, atr_period=10, multiplier=3.0)

Supertrend Yorumlama:

• direction = 1: Bullish trend (fiyat Supertrend üzerinde)
• direction = -1: Bearish trend (fiyat Supertrend altında)
• Trend değişimi: direction'ın işaret değiştirmesi

Tilson T3

Triple-smoothed EMA ile düşük gecikmeli hareketli ortalama.

import borsapy as bp

stock = bp.Ticker("THYAO")

# Son değer
t3 = stock.tilson_t3()              # 296.24
t3 = stock.tilson_t3(t3_period=8)   # Farklı period

# TechnicalAnalyzer ile
ta = stock.technicals(period="1y")
t3_series = ta.tilson_t3(period=5, vfactor=0.7)

# Pure function
df = stock.history(period="1y")
t3_series = bp.calculate_tilson_t3(df, period=5, vfactor=0.7)

Tilson T3 Parametreleri:

• period: T3 periyodu (varsayılan 5)
• vfactor: Volume faktörü (varsayılan 0.7)
  • 0.5 = daha responsive (hızlı tepki)
  • 0.7 = Tilson'ın önerisi
  • 0.9 = daha smooth (pürüzsüz)

Heikin Ashi Charts

Alternatif mum grafiği hesaplama yöntemi.

import borsapy as bp

stock = bp.Ticker("THYAO")

# Pure function ile
df = stock.history(period="1y")
ha_df = bp.calculate_heikin_ashi(df)
# Sütunlar: HA_Open, HA_High, HA_Low, HA_Close, Volume

# Convenience method
ha_df = stock.heikin_ashi(period="1y")

# TechnicalAnalyzer ile
ta = stock.technicals(period="1y")
ha_df = ta.heikin_ashi()

Heikin Ashi Formülü:

HA_Close = (Open + High + Low + Close) / 4
HA_Open  = (Prev_HA_Open + Prev_HA_Close) / 2  (ilk satır: (O+C)/2)
HA_High  = max(High, HA_Open, HA_Close)
HA_Low   = min(Low, HA_Open, HA_Close)

TradingView TA Sinyalleri

TradingView Scanner API ile teknik analiz sinyalleri (AL/SAT/TUT).

💡 Gerçek Zamanlı Veri: Varsayılan olarak ~15 dakika gecikmeli. Gerçek zamanlı sinyaller için TradingView Kimlik Doğrulama bölümüne bakın.

import borsapy as bp

stock = bp.Ticker("THYAO")

# Tek timeframe (varsayılan: günlük)
signals = stock.ta_signals()
print(signals['summary']['recommendation'])  # "STRONG_BUY", "BUY", "NEUTRAL", "SELL", "STRONG_SELL"
print(signals['summary']['buy'])             # 12 (AL sinyali veren gösterge sayısı)
print(signals['oscillators']['compute']['RSI'])  # "BUY", "SELL", "NEUTRAL"
print(signals['moving_averages']['values']['EMA20'])  # 285.5

# Belirli timeframe
signals_1h = stock.ta_signals(interval="1h")   # Saatlik
signals_4h = stock.ta_signals(interval="4h")   # 4 saatlik
signals_1w = stock.ta_signals(interval="1W")   # Haftalık

# Tüm timeframe'ler tek seferde
all_signals = stock.ta_signals_all_timeframes()
print(all_signals['1h']['summary']['recommendation'])
print(all_signals['1d']['summary']['recommendation'])
print(all_signals['1W']['summary']['recommendation'])

# Diğer varlık sınıfları için de çalışır
bp.Index("XU100").ta_signals()
bp.FX("USD").ta_signals()
bp.Crypto("BTCTRY").ta_signals()

Desteklenen Timeframe'ler: 1m, 5m, 15m, 30m, 1h, 2h, 4h, 1d, 1W, 1M

Sinyal Çıktı Formatı:

{
    "symbol": "THYAO",
    "exchange": "BIST",
    "interval": "1d",
    "summary": {
        "recommendation": "BUY",  # STRONG_BUY, BUY, NEUTRAL, SELL, STRONG_SELL
        "buy": 12, "sell": 5, "neutral": 9
    },
    "oscillators": {
        "recommendation": "NEUTRAL",
        "buy": 2, "sell": 2, "neutral": 7,
        "compute": {"RSI": "NEUTRAL", "MACD": "SELL", ...},
        "values": {"RSI": 48.95, "MACD.macd": 3.78, ...}
    },
    "moving_averages": {
        "recommendation": "BUY",
        "buy": 10, "sell": 3, "neutral": 2,
        "compute": {"EMA10": "BUY", "SMA20": "BUY", ...},
        "values": {"EMA10": 285.5, "SMA20": 284.2, ...}
    }
}

---

Gerçek Zamanlı Veri Akışı (TradingView Streaming)

Düşük gecikmeli, yüksek verimli gerçek zamanlı veri akışı. Persistent WebSocket bağlantısı ile anlık fiyat ve mum verisi.

⚠️ Önemli: Varsayılan olarak TradingView verileri ~15 dakika gecikmeli. Gerçek zamanlı BIST verisi için TradingView Pro hesabı ve BIST veri paketi gerekir. Detaylar için TradingView Kimlik Doğrulama bölümüne bakın.

Temel Kullanım

import borsapy as bp

# Stream oluştur ve bağlan
stream = bp.TradingViewStream()
stream.connect()

# Sembollere abone ol
stream.subscribe("THYAO")
stream.subscribe("GARAN")
stream.subscribe("ASELS")

# Anlık fiyat al (cached, <1ms)
quote = stream.get_quote("THYAO")
print(quote['last'])           # 299.0
print(quote['bid'])            # 298.9
print(quote['ask'])            # 299.1
print(quote['volume'])         # 12345678
print(quote['change_percent']) # 2.5

# İlk quote için bekle (blocking)
quote = stream.wait_for_quote("THYAO", timeout=5.0)

# Callback ile real-time updates
def on_price_update(symbol, quote):
    print(f"{symbol}: {quote['last']} ({quote['change_percent']:+.2f}%)")

stream.on_quote("THYAO", on_price_update)

# Tüm semboller için callback
stream.on_any_quote(lambda s, q: print(f"{s}: {q['last']}"))

# Bağlantıyı kapat
stream.disconnect()

Context Manager Kullanımı

import borsapy as bp

with bp.TradingViewStream() as stream:
    stream.subscribe("THYAO")
    quote = stream.wait_for_quote("THYAO", timeout=5.0)
    print(quote['last'])

Chart Verileri (OHLCV Streaming)

Gerçek zamanlı mum grafiği verisi.

import borsapy as bp

stream = bp.TradingViewStream()
stream.connect()

# Mum grafiği aboneliği
stream.subscribe_chart("THYAO", "1m")   # 1 dakikalık mumlar
stream.subscribe_chart("GARAN", "5m")   # 5 dakikalık mumlar
stream.subscribe_chart("ASELS", "1h")   # Saatlik mumlar

# Callback ile mum güncellemeleri
def on_candle(symbol, interval, candle):
    print(f"{symbol} {interval}: O={candle['open']} H={candle['high']} L={candle['low']} C={candle['close']}")

stream.on_candle("THYAO", "1m", on_candle)

# Tüm mumlar için callback
stream.on_any_candle(lambda s, i, c: print(f"{s} {i}: {c['close']}"))

# Cached mum verisi al
candle = stream.get_candle("THYAO", "1m")
candles = stream.get_candles("THYAO", "1m")  # Tüm mumlar (list)

# İlk mum için bekle
candle = stream.wait_for_candle("THYAO", "1m", timeout=10.0)

stream.disconnect()

Desteklenen Timeframe'ler: 1m, 5m, 15m, 30m, 1h, 4h, 1d, 1wk, 1mo

TradingView Kimlik Doğrulama (Gerçek Zamanlı Veri)

Varsayılan olarak TradingView verileri ~15 dakika gecikmeli. Gerçek zamanlı BIST verisi için TradingView'da aşağıdaki aboneliklere ihtiyacınız var:

1. Essential veya üzeri plan (Pro, Pro+, Premium)
2. BIST Real-time Market Data paketi (ek ücretli)

TradingView hesabınızda: Profil → Hesap ve Faturalama → Piyasa Verileri Abonelikleri → "Borsa Istanbul" ekleyin.

import borsapy as bp

# Yöntem 1: Username/Password ile login
bp.set_tradingview_auth(
    username="[e-mail]",
    password="mypassword"
)

# Yöntem 2: Mevcut session token ile
bp.set_tradingview_auth(
    session="abc123...",          # sessionid cookie
    session_sign="xyz789..."      # sessionid_sign cookie
)

# Artık gerçek zamanlı veri
stream = bp.TradingViewStream()
stream.connect()
stream.subscribe("THYAO")
quote = stream.wait_for_quote("THYAO")
print(quote['last'])  # Gerçek zamanlı fiyat

# Logout
bp.clear_tradingview_auth()

Session süresi: ~30 gün (remember=on ile)

Chrome DevTools ile Cookie Alma:

1. TradingView'a giriş yapın (tradingview.com)
2. F12 veya Ctrl+Shift+I ile DevTools'u açın
3. Application sekmesine gidin
4. Sol menüden Cookies → https://www.tradingview.com seçin
5. Aşağıdaki cookie'leri bulun ve değerlerini kopyalayın:
   • sessionid → session parametresi
   • sessionid_sign → session_sign parametresi

bp.set_tradingview_auth(
    session="kopyaladığınız_sessionid_değeri",
    session_sign="kopyaladığınız_sessionid_sign_değeri"
)

Quote Alanları (46 alan)

Kategori	Alanlar
Fiyat	last, change, change_percent, bid, ask, bid_size, ask_size, volume
OHLC	open, high, low, prev_close
Temel	market_cap, pe_ratio, eps, dividend_yield, beta
52 Hafta	high_52_week, low_52_week
Meta	description, currency, timestamp

Performans Karşılaştırması

Metrik	Eski (get_quote)	Yeni (TradingViewStream)
Gecikme	~7000ms	~50-100ms
Throughput	0.1 req/s	10-20 req/s
Bağlantı	Her istekte yeni	Tek persistent
Cached Quote	N/A	<1ms

Teşekkür: Bu TradingView entegrasyonu Mathieu2301/TradingView-API projesinden ilham alınarak geliştirilmiştir.

---

Sembol Arama (Search)

TradingView symbol search API ile çoklu piyasada sembol arama.

import borsapy as bp

# Basit arama
bp.search("banka")           # ['AKBNK', 'GARAN', 'ISCTR', ...]
bp.search("enerji")          # ['AKSEN', 'ODAS', 'ZOREN', ...]
bp.search("THY")             # ['THYAO']

# Tip filtreleme
bp.search("gold", type="forex")     # Altın pariteleri
bp.search("BTC", type="crypto")     # Kripto
bp.search("XU", type="index")       # Endeksler
bp.search("F_XU030", type="futures") # Vadeli kontratlar

# Exchange filtresi
bp.search("GARAN", exchange="BIST")  # Sadece BIST

# Detaylı sonuç
results = bp.search("THYAO", full_info=True)
# [{'symbol': 'THYAO', 'exchange': 'BIST', 'description': 'TURK HAVA YOLLARI', ...}]

# Kısa yol fonksiyonları
bp.search_bist("banka")      # Sadece BIST hisseleri
bp.search_crypto("ETH")      # Sadece kripto
bp.search_forex("USD")       # Sadece forex
bp.search_index("XU")        # Sadece endeksler

Desteklenen Tipler: stock, forex, crypto, index, futures, bond, fund

---

Replay Mode (Backtesting için Tarihsel Oynatma)

Backtesting için tarihsel veriyi candle-by-candle oynatma.

import borsapy as bp

# Basit replay
session = bp.create_replay("THYAO", period="6mo", speed=5.0)

for candle in session.replay():
    print(f"{candle['timestamp']}: Close={candle['close']}")
    # Trading logic...

# Callback ile
def on_candle(c):
    print(f"Progress: {c['_index']}/{c['_total']} ({c['_progress']:.1%})")

session.on_candle(on_candle)
list(session.replay())  # Callback'ler otomatik çalışır

# Tarih filtresi ile
for candle in session.replay_filtered(
    start_date="2024-01-01",
    end_date="2024-06-01"
):
    # Sadece belirlenen tarih aralığı
    pass

# İstatistikler
print(session.stats())
# {'symbol': 'THYAO', 'total_candles': 252, 'progress': 0.5, ...}

Candle Formatı:

{
    "timestamp": datetime,
    "open": 285.0,
    "high": 286.5,
    "low": 284.0,
    "close": 285.5,
    "volume": 123456,
    "_index": 42,      # Kaçıncı candle
    "_total": 252,     # Toplam candle sayısı
    "_progress": 0.167 # İlerleme (0.0-1.0)
}

---

Backtest Engine

Strateji backtesting framework'ü. Kendi stratejilerinizi geçmiş verilere karşı test edin.

Temel Kullanım

import borsapy as bp

# Strateji tanımla
def rsi_strategy(candle, position, indicators):
    """
    Args:
        candle: {'timestamp', 'open', 'high', 'low', 'close', 'volume'}
        position: 'long' | 'short' | None
        indicators: {'rsi': 48.5, 'sma_20': 285.5, ...}
    Returns:
        'BUY' | 'SELL' | 'HOLD' | None
    """
    if indicators.get('rsi', 50) < 30 and position is None:
        return 'BUY'
    elif indicators.get('rsi', 50) > 70 and position == 'long':
        return 'SELL'
    return 'HOLD'

# Backtest çalıştır
result = bp.backtest(
    "THYAO",
    rsi_strategy,
    period="1y",
    capital=100000,
    commission=0.001,
    indicators=['rsi', 'sma_20']
)

# Sonuçlar
print(result.summary())
print(f"Net Profit: {result.net_profit:.2f} TL")
print(f"Net Profit %: {result.net_profit_pct:.2f}%")
print(f"Win Rate: {result.win_rate:.1f}%")
print(f"Sharpe Ratio: {result.sharpe_ratio:.2f}")
print(f"Max Drawdown: {result.max_drawdown:.2f}%")
print(f"Total Trades: {result.total_trades}")

# DataFrame export
print(result.trades_df)      # Trade history
print(result.equity_curve)   # Equity over time

Backtest Class ile Detaylı Kullanım

import borsapy as bp

bt = bp.Backtest(
    symbol="GARAN",
    strategy=rsi_strategy,
    period="2y",
    capital=50000,
    commission=0.001,
    indicators=['rsi', 'macd', 'bollinger']
)

result = bt.run()

BacktestResult Metrikleri

Metrik	Açıklama
net_profit	Net kar (TL)
net_profit_pct	Net kar yüzdesi
total_trades	Toplam işlem sayısı
winning_trades	Kazançlı işlem sayısı
losing_trades	Kayıplı işlem sayısı
win_rate	Kazanç oranı (%)
profit_factor	Brüt kar / Brüt zarar
sharpe_ratio	Risk-adjusted return
sortino_ratio	Downside risk-adjusted return
max_drawdown	Maksimum düşüş (%)
avg_trade	Ortalama işlem karı
buy_hold_return	Buy & Hold getirisi
vs_buy_hold	Strateji vs Buy & Hold
trades_df	Trade DataFrame (entry, exit, profit, duration)
equity_curve	Portföy değeri zaman serisi

Desteklenen Göstergeler

Gösterge	Format	Açıklama
RSI	rsi, rsi_7, rsi_21	RSI (varsayılan 14)
SMA	sma_20, sma_50, sma_200	Simple Moving Average
EMA	ema_12, ema_26, ema_50	Exponential Moving Average
MACD	macd	MACD, Signal, Histogram
Bollinger	bollinger	Upper, Middle, Lower bands
ATR	atr, atr_20	Average True Range
Stochastic	stochastic	%K, %D
ADX	adx	Average Directional Index

---

Pine Script Streaming Indicators

TradingView'ın Pine Script göstergelerini gerçek zamanlı olarak alın.

💡 Gerçek Zamanlı Veri: Varsayılan olarak ~15 dakika gecikmeli. Gerçek zamanlı gösterge değerleri için TradingView Kimlik Doğrulama bölümüne bakın.

import borsapy as bp

stream = bp.TradingViewStream()
stream.connect()

# Önce chart'a abone ol
stream.subscribe_chart("THYAO", "1m")

# Pine gösterge ekle
stream.add_study("THYAO", "1m", "RSI")           # Varsayılan ayarlar
stream.add_study("THYAO", "1m", "RSI", length=7) # Custom period
stream.add_study("THYAO", "1m", "MACD")
stream.add_study("THYAO", "1m", "BB")            # Bollinger Bands

# Değerleri bekle ve al
rsi = stream.wait_for_study("THYAO", "1m", "RSI", timeout=10)
print(rsi['value'])  # 48.5

# Tüm göstergeleri al
studies = stream.get_studies("THYAO", "1m")
print(studies)
# {
#     'RSI': {'value': 48.5},
#     'MACD': {'macd': 3.2, 'signal': 2.8, 'histogram': 0.4},
#     'BB': {'upper': 296.8, 'middle': 285.0, 'lower': 273.2}
# }

# Callback ile real-time updates
def on_rsi_update(symbol, interval, indicator, values):
    print(f"{symbol} {indicator}: {values}")

stream.on_study("THYAO", "1m", "RSI", on_rsi_update)
stream.on_any_study(lambda s, i, n, v: print(f"{s} {n}: {v}"))

stream.disconnect()

Desteklenen Pine Göstergeler

Gösterge	TradingView ID	Outputs
RSI	STD;RSI	value
MACD	STD;MACD	macd, signal, histogram
BB/Bollinger	STD;BB	upper, middle, lower
EMA	STD;EMA	value
SMA	STD;SMA	value
Stochastic	STD;Stochastic	k, d
ATR	STD;ATR	value
ADX	STD;ADX	adx, plus_di, minus_di
OBV	STD;OBV	value
VWAP	STD;VWAP	value
Ichimoku	STD;Ichimoku%Cloud	conversion, base, span_a, span_b
Supertrend	STD;Supertrend	value, direction
Parabolic SAR	STD;Parabolic%SAR	value
CCI	STD;CCI	value
MFI	STD;MFI	value

Custom Indicator Kullanımı

TradingView auth ile custom/community göstergeler kullanabilirsiniz.

import borsapy as bp

# TradingView auth ayarla
bp.set_tradingview_auth(
    session="sessionid_cookie",
    signature="sessionid_sign_cookie"
)

stream = bp.TradingViewStream()
stream.connect()
stream.subscribe_chart("THYAO", "1m")

# Public community indicator
stream.add_study("THYAO", "1m", "PUB;abc123")

# User's own indicator
stream.add_study("THYAO", "1m", "USER;xyz789")

values = stream.get_study("THYAO", "1m", "PUB;abc123")

---

Inflation (Enflasyon)

TCMB enflasyon verileri.

import borsapy as bp

enf = bp.Inflation()

# Son TÜFE verileri (Tüketici Fiyat Endeksi)
print(enf.latest())
print(enf.tufe())                   # TÜFE geçmişi

# ÜFE verileri (Üretici Fiyat Endeksi)
print(enf.ufe())

# Enflasyon hesaplayıcı
# 100.000 TL'nin 2020-01'den 2024-01'e değeri
sonuc = enf.calculate(100000, "2020-01", "2024-01")
print(sonuc)

---

VIOP (Vadeli İşlem ve Opsiyon)

İş Yatırım üzerinden vadeli işlem ve opsiyon verileri.

Temel Kullanım

import borsapy as bp

viop = bp.VIOP()

# Tüm vadeli işlem kontratları
print(viop.futures)

# Tüm opsiyonlar
print(viop.options)

# Vadeli işlem alt kategorileri
print(viop.stock_futures)      # Pay vadeli
print(viop.index_futures)      # Endeks vadeli
print(viop.currency_futures)   # Döviz vadeli
print(viop.commodity_futures)  # Emtia vadeli

# Opsiyon alt kategorileri
print(viop.stock_options)      # Pay opsiyonları
print(viop.index_options)      # Endeks opsiyonları

# Sembol bazlı arama
print(viop.get_by_symbol("THYAO"))  # THYAO'nun tüm türevleri

VIOP Kontrat Arama ve Listeleme

import borsapy as bp

# Mevcut VIOP kontratlarını listele
contracts = bp.viop_contracts("XU030D")  # BIST30 vadeli kontratları
print(contracts)  # ['XU030DG2026', 'XU030DJ2026', ...]

# Altın vadeli kontratları (D eki yok)
gold_contracts = bp.viop_contracts("XAUTRY")
print(gold_contracts)  # ['XAUTRYG2026', 'XAUTRYJ2026', ...]

# VIOP sembol arama
bp.search_viop("XU030")    # ['XU030D', 'XU030DG2026', ...]
bp.search_viop("gold")     # Altın vadeli kontratları

# Detaylı kontrat bilgisi
contracts = bp.viop_contracts("XU030D", full_info=True)
# [
#     {'symbol': 'XU030DG2026', 'month_code': 'G', 'year': '2026', ...},
#     {'symbol': 'XU030DJ2026', 'month_code': 'J', 'year': '2026', ...},
# ]

VIOP Gerçek Zamanlı Streaming

TradingView WebSocket ile vadeli kontratların gerçek zamanlı fiyatları.

import borsapy as bp

stream = bp.TradingViewStream()
stream.connect()

# Vadeli kontrata abone ol (belirli vade)
stream.subscribe("XU030DG2026")      # BIST30 Şubat 2026
stream.subscribe("XAUTRYG2026")      # Altın TRY Şubat 2026
stream.subscribe("USDTRYG2026")      # Dolar TRY Şubat 2026

# Fiyat al
quote = stream.wait_for_quote("XU030DG2026", timeout=5)
print(f"BIST30 Vadeli: {quote['last']} TL, Değişim: {quote['change_percent']:.2f}%")

# Callback ile
def on_viop_update(symbol, quote):
    print(f"{symbol}: {quote['last']} TL, Vol: {quote['volume']}")

stream.on_quote("XU030DG2026", on_viop_update)

# Chart verileri (OHLCV)
stream.subscribe_chart("XU030DG2026", "1m")
candle = stream.wait_for_candle("XU030DG2026", "1m")
print(f"Open: {candle['open']}, Close: {candle['close']}")

stream.disconnect()

VIOP Kontrat Formatı

Kontrat formatı: Base symbol + Month code + Year (örn: XU030DG2026)

Ay Kodları:

Kod	Ay
F	Ocak
G	Şubat
H	Mart
J	Nisan
K	Mayıs
M	Haziran
N	Temmuz
Q	Ağustos
U	Eylül
V	Ekim
X	Kasım
Z	Aralık

Desteklenen VIOP Kontratları:

Tip	Örnek Base Symbol	Açıklama
Endeks	XU030D, XU100D, XLBNKD	BIST endeks vadeli
Döviz	USDTRYD, EURTRD	Döviz vadeli
Altın	XAUTRY, XAUUSD	Altın vadeli (TRY/USD, D eki yok)
Hisse	THYAOD, GARAND	Pay vadeli

Not: Continuous kontratlar (XU030D1!) TradingView WebSocket'te çalışmıyor. Belirli vade kontratları kullanın (örn: XU030DG2026).

---

Bond (Tahvil/Bono)

Türk devlet tahvili faiz oranları.

import borsapy as bp

# Tüm tahvil faizleri
print(bp.bonds())
#                 name maturity   yield  change  change_pct
# 0   2 Yıllık Tahvil       2Y   26.42    0.40        1.54
# 1   5 Yıllık Tahvil       5Y   27.15    0.35        1.31
# 2  10 Yıllık Tahvil      10Y   28.03    0.42        1.52

# Tek tahvil
bond = bp.Bond("10Y")               # 2Y, 5Y, 10Y
print(bond.yield_rate)              # Faiz oranı (örn: 28.03)
print(bond.yield_decimal)           # Ondalık (örn: 0.2803)
print(bond.change_pct)              # Günlük değişim (%)
print(bond.info)                    # Tüm bilgiler

# Risk-free rate (DCF hesaplamaları için)
rfr = bp.risk_free_rate()           # 10Y faiz oranı (ondalık)
print(rfr)                          # 0.2803

---

TCMB (Merkez Bankası Faiz Oranları)

TCMB politika faizi ve koridor oranları.

import borsapy as bp

tcmb = bp.TCMB()

# Güncel oranlar
print(tcmb.policy_rate)             # 1 hafta repo faizi (%)
print(tcmb.overnight)               # {'borrowing': 36.5, 'lending': 41.0}
print(tcmb.late_liquidity)          # {'borrowing': 0.0, 'lending': 44.0}

# Tüm oranlar (DataFrame)
print(tcmb.rates)
#              type  borrowing  lending
# 0          policy        NaN     38.0
# 1       overnight       36.5     41.0
# 2  late_liquidity        0.0     44.0

# Geçmiş veriler
print(tcmb.history("policy"))           # 1 hafta repo geçmişi (2010+)
print(tcmb.history("overnight"))        # Gecelik faiz geçmişi
print(tcmb.history("late_liquidity", period="1y"))  # Son 1 yıl LON

# Kısa yol fonksiyonu
print(bp.policy_rate())             # Güncel politika faizi

Desteklenen Oranlar

Oran	Açıklama
policy_rate	1 hafta repo faizi (politika faizi)
overnight	Gecelik (O/N) koridor oranları (borrowing/lending)
late_liquidity	Geç likidite penceresi (LON) oranları

---

Eurobond (Türk Devlet Tahvilleri)

Yabancı para cinsinden (USD/EUR) Türk devlet tahvilleri.

import borsapy as bp

# Tüm eurobondlar (38+ tahvil)
df = bp.eurobonds()
print(df)
#            isin   maturity  days_to_maturity currency  bid_price  bid_yield  ask_price  ask_yield
# 0  US900123DG28 2033-01-19              2562      USD     120.26       6.55     122.19       6.24
# ...

# Para birimine göre filtre
df_usd = bp.eurobonds(currency="USD")   # Sadece USD (34 tahvil)
df_eur = bp.eurobonds(currency="EUR")   # Sadece EUR (4 tahvil)

# Tek eurobond (ISIN ile)
bond = bp.Eurobond("US900123DG28")
print(bond.isin)                    # US900123DG28
print(bond.maturity)                # 2033-01-19
print(bond.currency)                # USD
print(bond.days_to_maturity)        # 2562
print(bond.bid_price)               # 120.26
print(bond.bid_yield)               # 6.55
print(bond.ask_price)               # 122.19
print(bond.ask_yield)               # 6.24
print(bond.info)                    # Tüm veriler (dict)

Eurobond Verileri

Alan	Açıklama
isin	Uluslararası tahvil kimlik numarası
maturity	Vade tarihi
days_to_maturity	Vadeye kalan gün
currency	Para birimi (USD veya EUR)
bid_price	Alış fiyatı
bid_yield	Alış getirisi (%)
ask_price	Satış fiyatı
ask_yield	Satış getirisi (%)

---

EconomicCalendar (Ekonomik Takvim)

Ekonomik olaylar ve göstergeler.

import borsapy as bp

cal = bp.EconomicCalendar()

# Bu haftanın olayları
df = cal.events(period="1w")
#         Date   Time  Country Importance                    Event   Actual Forecast Previous
# 0 2024-01-15  10:00  Türkiye       high     İşsizlik Oranı (Kas)     9.2%     9.3%     9.1%
# 1 2024-01-16  14:30      ABD       high  Perakende Satışlar (Ara)    0.6%     0.4%     0.3%

# Filtreleme
df = cal.events(period="1ay", country="TR")              # Sadece Türkiye
df = cal.events(period="1w", importance="high")          # Sadece önemli
df = cal.events(country="TR", importance="high")         # TR + önemli

# Kısayollar
df = cal.today()                    # Bugünkü olaylar
df = cal.this_week()                # Bu hafta
df = cal.this_month()               # Bu ay

# Fonksiyon olarak
df = bp.economic_calendar(period="1w", country="TR")

# Desteklenen ülkeler
# TR (Türkiye), US (ABD), EU (Euro Bölgesi), DE (Almanya),
# GB (İngiltere), JP (Japonya), CN (Çin)

# Önem seviyeleri: high, medium, low

---

Screener (Hisse Tarama)

BIST hisselerini 40+ kritere göre filtreleme (İş Yatırım API).

Hızlı Başlangıç

import borsapy as bp

# Hazır şablonlar
df = bp.screen_stocks(template="high_dividend")    # Temettü verimi > %2
df = bp.screen_stocks(template="low_pe")           # F/K < 10
df = bp.screen_stocks(template="high_roe")         # ROE > %15
df = bp.screen_stocks(template="high_upside")      # Getiri potansiyeli > 0

# Doğrudan filtreler
df = bp.screen_stocks(pe_max=10)                   # F/K en fazla 10
df = bp.screen_stocks(dividend_yield_min=3)        # Temettü verimi min %3
df = bp.screen_stocks(roe_min=20, pb_max=2)        # ROE > %20, PD/DD < 2

# Sektör/endeks ile kombine
df = bp.screen_stocks(sector="Bankacılık", dividend_yield_min=3)
df = bp.screen_stocks(sector="Holding", pe_max=8)

Mevcut Şablonlar

Şablon	Açıklama	Kriter
small_cap	Küçük şirketler	Piyasa değeri < ~43B TL
mid_cap	Orta boy şirketler	Piyasa değeri 43B-215B TL
large_cap	Büyük şirketler	Piyasa değeri > 215B TL
high_dividend	Yüksek temettü	Temettü verimi > %2
low_pe	Düşük F/K	F/K < 10
high_roe	Yüksek ROE	ROE > %15
high_upside	Pozitif potansiyel	Getiri potansiyeli > 0
low_upside	Negatif potansiyel	Getiri potansiyeli < 0
high_volume	Yüksek hacim	3 aylık hacim > $1M
low_volume	Düşük hacim	3 aylık hacim < $0.5M
high_net_margin	Yüksek kar marjı	Net kar marjı > %10
high_return	Haftalık artış	1 hafta getiri > 0
high_foreign_ownership	Yüksek yabancı oranı	Yabancı oranı > %30
buy_recommendation	AL tavsiyesi	Analist tavsiyesi: AL
sell_recommendation	SAT tavsiyesi	Analist tavsiyesi: SAT

Fluent API (Gelişmiş Kullanım)

screener = bp.Screener()

# Değerleme filtreleri
screener.add_filter("pe", max=15)                  # F/K < 15
screener.add_filter("pb", max=2)                   # PD/DD < 2
screener.add_filter("ev_ebitda", max=8)            # FD/FAVÖK < 8

# Temettü filtresi
screener.add_filter("dividend_yield", min=3)       # Temettü verimi > %3

# Karlılık filtreleri
screener.add_filter("roe", min=15)                 # ROE > %15
screener.add_filter("net_margin", min=10)          # Net kar marjı > %10

# Piyasa değeri (TL, milyon)
screener.add_filter("market_cap", min=10000)       # > 10 milyar TL

# Getiri filtreleri
screener.add_filter("return_1w", min=0)            # Haftalık getiri pozitif
screener.add_filter("return_1m", min=5)            # Aylık getiri > %5

# Sektör/endeks/tavsiye
screener.set_sector("Bankacılık")
screener.set_index("BIST 100")
screener.set_recommendation("AL")                  # AL, TUT, SAT

results = screener.run()

Tüm Filtre Kriterleri

Fiyat ve Piyasa Değeri

Kriter	Açıklama
price	Kapanış fiyatı (TL)
market_cap	Piyasa değeri (mn TL)
market_cap_usd	Piyasa değeri (mn $)
float_ratio	Halka açıklık oranı (%)
float_market_cap	Halka açık piyasa değeri (mn $)

Değerleme Çarpanları

Kriter	Açıklama
pe	Cari F/K (Fiyat/Kazanç)
pb	Cari PD/DD (Piyasa Değeri/Defter Değeri)
ev_ebitda	Cari FD/FAVÖK
ev_sales	Cari FD/Satışlar
pe_2025	2025 tahmini F/K
pb_2025	2025 tahmini PD/DD
ev_ebitda_2025	2025 tahmini FD/FAVÖK
pe_hist_avg	Tarihsel ortalama F/K
pb_hist_avg	Tarihsel ortalama PD/DD

Temettü

Kriter	Açıklama
dividend_yield	2024 temettü verimi (%)
dividend_yield_2025	2025 tahmini temettü verimi (%)
dividend_yield_5y_avg	5 yıllık ortalama temettü verimi (%)

Karlılık

Kriter	Açıklama
roe	Cari ROE (%)
roa	Cari ROA (%)
net_margin	2025 net kar marjı (%)
ebitda_margin	2025 FAVÖK marjı (%)
roe_2025	2025 tahmini ROE
roa_2025	2025 tahmini ROA

Getiri (Relatif - Endekse Göre)

Kriter	Açıklama
return_1d	1 gün relatif getiri (%)
return_1w	1 hafta relatif getiri (%)
return_1m	1 ay relatif getiri (%)
return_1y	1 yıl relatif getiri (%)
return_ytd	Yıl başından beri relatif getiri (%)

Getiri (TL Bazlı)

Kriter	Açıklama
return_1d_tl	1 gün TL getiri (%)
return_1w_tl	1 hafta TL getiri (%)
return_1m_tl	1 ay TL getiri (%)
return_1y_tl	1 yıl TL getiri (%)
return_ytd_tl	Yıl başından beri TL getiri (%)

Hacim ve Likidite

Kriter	Açıklama
volume_3m	3 aylık ortalama hacim (mn $)
volume_12m	12 aylık ortalama hacim (mn $)

Yabancı ve Hedef Fiyat

Kriter	Açıklama
foreign_ratio	Yabancı oranı (%)
foreign_ratio_1w_change	Yabancı oranı 1 haftalık değişim (baz puan)
foreign_ratio_1m_change	Yabancı oranı 1 aylık değişim (baz puan)
target_price	Hedef fiyat (TL)
upside_potential	Getiri potansiyeli (%)

Endeks Ağırlıkları

Kriter	Açıklama
bist100_weight	BIST 100 endeks ağırlığı
bist50_weight	BIST 50 endeks ağırlığı
bist30_weight	BIST 30 endeks ağırlığı

Örnek Stratejiler

import borsapy as bp

# Değer Yatırımı: Düşük çarpanlar, yüksek temettü
screener = bp.Screener()
screener.add_filter("pe", max=10)
screener.add_filter("pb", max=1.5)
screener.add_filter("dividend_yield", min=4)
value_stocks = screener.run()

# Büyüme Yatırımı: Yüksek ROE, pozitif momentum
screener = bp.Screener()
screener.add_filter("roe", min=20)
screener.add_filter("return_1m", min=0)
screener.add_filter("market_cap", min=50000)  # Büyük şirketler (>50B TL)
growth_stocks = screener.run()

# Temettü Avcısı: Banka hisseleri, yüksek temettü
df = bp.screen_stocks(
    sector="Bankacılık",
    dividend_yield_min=5,
    pe_max=6
)

# Yabancı Takibi: Yabancıların ilgi gösterdiği hisseler
screener = bp.Screener()
screener.add_filter("foreign_ratio", min=40)
screener.add_filter("foreign_ratio_1m_change", min=1)  # Son 1 ayda artan
foreign_favorites = screener.run()

# Analist Favorileri: AL tavsiyeli, yüksek potansiyel
df = bp.screen_stocks(
    template="buy_recommendation",
    upside_potential_min=20
)

Yardımcı Fonksiyonlar

# Tüm filtre kriterleri (API'den)
print(bp.screener_criteria())
# [{'id': '7', 'name': 'Kapanış (TL)', 'min': '1.1', 'max': '14087.5'}, ...]

# Sektör listesi (53 sektör)
print(bp.sectors())
# ['Bankacılık', 'Holding ve Yatırım', 'Enerji', 'Gıda', ...]

# Endeks listesi
print(bp.stock_indices())
# ['BIST 30', 'BIST 50', 'BIST 100', 'BIST BANKA', ...]

Çıktı Formatı

df = bp.screen_stocks(template="high_dividend")
print(df.columns)
# Index(['symbol', 'name', 'criteria_7', 'criteria_33', ...], dtype='object')
#
# symbol: Hisse kodu (THYAO, GARAN, vb.)
# name: Şirket adı
# criteria_X: İlgili kriter değerleri (X = kriter ID)

---

Teknik Tarama (Technical Scanner)

Teknik göstergelere dayalı hisse tarama. scan() fonksiyonu veya TechnicalScanner class ile kullanılabilir.

💡 TradingView Entegrasyonu: Scanner, TradingView Screener API üzerinden çalışır. Varsayılan olarak ~15 dakika gecikmeli veri kullanır. Gerçek zamanlı tarama için TradingView Kimlik Doğrulama bölümüne bakın.

Basit Kullanım

import borsapy as bp

# Basit tarama (DataFrame döndürür)
df = bp.scan("XU030", "rsi < 30")                # RSI oversold
df = bp.scan("XU100", "price > sma_50")          # SMA50 üzerinde
df = bp.scan("XBANK", "change_percent > 3")      # %3+ yükselenler

# Compound koşullar
df = bp.scan("XU030", "rsi < 30 and volume > 1000000")
df = bp.scan("XU030", "sma_20 crosses_above sma_50")  # Golden cross

# Sonuçları incele
print(f"Bulunan: {len(df)} hisse")
print(df[['symbol', 'price', 'rsi', 'volume']])

Index.scan() Metodu

import borsapy as bp

# Index nesnesi üzerinden tarama
xu030 = bp.Index("XU030")
df = xu030.scan("rsi < 30")
df = xu030.scan("price > sma_50 and rsi > 50")

TechnicalScanner Class

import borsapy as bp

scanner = bp.TechnicalScanner()
scanner.set_universe("XU030")
scanner.add_condition("rsi < 30", name="oversold")
scanner.add_condition("volume > 1000000", name="high_vol")
results = scanner.run()

print(results[['symbol', 'rsi', 'volume', 'conditions_met']])

Desteklenen Koşullar

Kategori	Koşullar	Örnek
Quote	price, volume, change_percent, bid, ask	price > 100
Göstergeler	rsi, sma_N, ema_N, macd, signal, bb_upper/lower, adx, atr, cci, stoch_k/d	rsi < 30
Lokal	supertrend, supertrend_direction, t3	supertrend_direction == 1
Crossover	crosses, crosses_above, crosses_below	sma_20 crosses_above sma_50
Yüzde	above_pct, below_pct	close above_pct sma_50 1.05

Timeframe Desteği

import borsapy as bp

# Günlük (varsayılan)
df = bp.scan("XU030", "rsi < 30")

# Saatlik
df = bp.scan("XU030", "rsi < 30", interval="1h")

# 15 dakikalık
df = bp.scan("XU030", "macd > signal", interval="15m")

# Desteklenen: 1m, 5m, 15m, 30m, 1h, 2h, 4h, 1d, 1W, 1M

Örnek Stratejiler

import borsapy as bp

# Oversold tarama
oversold = bp.scan("XU100", "rsi < 30")

# Golden Cross
golden = bp.scan("XU030", "sma_20 crosses_above sma_50")

# Death Cross
death = bp.scan("XU030", "sma_20 crosses_below sma_50")

# MACD sıfır çizgisini geçiyor
macd_cross = bp.scan("XU100", "macd crosses signal")

# Yüksek hacimli momentum
momentum = bp.scan("XU030", "rsi > 50 and volume > 5000000 and change_percent > 2")

# Fiyat SMA50'nin %5 üzerinde
breakout = bp.scan("XU030", "close above_pct sma_50 1.05")

# Fiyat SMA200'ün %10 altında (potansiyel dip)
dip = bp.scan("XU100", "close below_pct sma_200 0.90")

# Bollinger alt bandına yakın
bb_low = bp.scan("XU030", "close < bb_lower")

# Saatlik RSI oversold
hourly_oversold = bp.scan("XU030", "rsi < 30", interval="1h")

Lokal Hesaplanan Göstergeler (Supertrend, T3)

Supertrend ve Tilson T3 göstergeleri TradingView Scanner API'de bulunmadığı için lokal olarak hesaplanır.

import borsapy as bp

# Supertrend Taramaları
bullish = bp.scan("XU030", "supertrend_direction == 1")   # Yükseliş trendi
bearish = bp.scan("XU030", "supertrend_direction == -1")  # Düşüş trendi
above_st = bp.scan("XU030", "close > supertrend")         # Fiyat supertrend üstünde

# Tilson T3 Taramaları
above_t3 = bp.scan("XU030", "close > t3")                 # Fiyat T3 üstünde
below_t3 = bp.scan("XU030", "close < t3")                 # Fiyat T3 altında

# Kombinasyon: RSI oversold + Supertrend bullish
combo = bp.scan("XU030", "rsi < 30 and supertrend_direction == 1")

# Sonuçları incele
print(bullish[['symbol', 'supertrend', 'supertrend_direction', 'close']])

Desteklenen Lokal Alanlar:

Alan	Açıklama
supertrend	Supertrend değeri
supertrend_direction	1 = yükseliş, -1 = düşüş
supertrend_upper	Üst band
supertrend_lower	Alt band
t3 / tilson_t3	Tilson T3 değeri

---

Twitter/X Tweet Arama

Hisse, fon, döviz ve kripto ile ilgili tweet arama. Twitter/X GraphQL API üzerinden Scweet kütüphanesi ile çalışır.

Optional Dependency: pip install borsapy[twitter] ile yüklenir. Core borsapy kurulumunu etkilemez.

Kurulum ve Kimlik Doğrulama

# Ek bağımlılık yükle
# pip install borsapy[twitter]

import borsapy as bp

# Twitter cookie auth (browser DevTools > Application > Cookies > x.com)
bp.set_twitter_auth(auth_token="abc123...", ct0="xyz789...")

# Alternatif: cookies dict
bp.set_twitter_auth(cookies={"auth_token": "abc123", "ct0": "xyz789"})

# Alternatif: cookies dosyası
bp.set_twitter_auth(cookies_file="cookies.json")

# Auth temizle
bp.clear_twitter_auth()

Standalone Tweet Arama

import borsapy as bp

# Temel arama
df = bp.search_tweets("$THYAO", period="7d")
print(df[['text', 'author_handle', 'likes', 'retweets']])

# Türkçe tweetler, son 1 gün
df = bp.search_tweets("dolar kur", period="1d", lang="tr", limit=50)

# Tarih aralığı ile
df = bp.search_tweets("enflasyon", since="2025-01-01", until="2025-02-01")

Asset Entegrasyonu

Her varlık sınıfı için otomatik sorgu oluşturma:

import borsapy as bp

# Hisse — $THYAO OR #THYAO OR THYAO OR "TURK HAVA YOLLARI"
bp.Ticker("THYAO").tweets(period="7d")

# Fon — #AAK OR AAK OR "AK PORTFOY KISA VADELI BONO"
bp.Fund("AAK").tweets(period="7d")

# Döviz — $USDTRY OR dolar kur OR dolar TL
bp.FX("USD").tweets(period="7d")

# Kripto — $BTC OR #Bitcoin
bp.Crypto("BTCTRY").tweets(period="7d")

# Custom sorgu override
bp.Ticker("THYAO").tweets(query="THY uçak grev")

DataFrame Sütunları

Sütun	Tip	Açıklama
tweet_id	str	Tweet ID
created_at	datetime	Tarih
text	str	Tweet metni
author_handle	str	@kullanıcı
author_name	str	Görünen isim
likes	int	Beğeni
retweets	int	Retweet
replies	int	Yanıt
views	int	Görüntülenme
quotes	int	Alıntı
bookmarks	int	Yer imi
author_followers	int	Takipçi sayısı
author_verified	bool	Doğrulanmış mı
lang	str	Dil kodu
url	str	Tweet linki

Desteklenen Periodlar

Period	Süre
1d	1 gün
3d	3 gün
7d / 1w	7 gün
2w	14 gün
1mo	30 gün
3mo	90 gün

---

Şirket Listesi

BIST şirketlerini listeleme ve arama.

import borsapy as bp

# Tüm şirketler
df = bp.companies()
print(df)

# Şirket arama
sonuc = bp.search_companies("banka")
print(sonuc)

---

Veri Kaynakları

Modül	Kaynak	Açıklama
Ticker	İş Yatırım, TradingView, KAP, hedeffiyat.com.tr, isinturkiye.com.tr	Hisse verileri, finansallar, bildirimler, analist hedefleri, ISIN, ETF sahipliği
Index	TradingView, BIST	BIST endeksleri, bileşen listeleri
FX	canlidoviz.com, doviz.com, TradingView	65 döviz, altın, emtia; banka/kurum kurları; intraday (TradingView)
Crypto	BtcTurk	Kripto para verileri
Fund	TEFAS	Yatırım fonu verileri, varlık dağılımı, tarama/karşılaştırma, stopaj oranları
Inflation	TCMB	Enflasyon verileri
VIOP	İş Yatırım, TradingView	Vadeli işlem/opsiyon; gerçek zamanlı streaming
Bond	doviz.com	Devlet tahvili faiz oranları (2Y, 5Y, 10Y)
TCMB	tcmb.gov.tr	Merkez Bankası faiz oranları (politika, gecelik, LON)
Eurobond	ziraatbank.com.tr	Türk devlet eurobondları (USD/EUR, 38+ tahvil)
EconomicCalendar	doviz.com	Ekonomik takvim (TR, US, EU, DE, GB, JP, CN)
Screener	İş Yatırım	Hisse tarama (İş Yatırım gelişmiş hisse arama)
TradingViewStream	TradingView WebSocket	Gerçek zamanlı fiyat, OHLCV, Pine Script göstergeleri
Search	TradingView	Sembol arama (hisse, döviz, kripto, endeks, vadeli)
Backtest	Yerel	Strateji backtesting engine
Twitter/X	Scweet (optional)	Tweet arama (Twitter GraphQL API, cookie auth)

---

yfinance ile Karşılaştırma

Ortak Özellikler

• Ticker, Tickers sınıfları
• download() fonksiyonu
• info, history(), finansal tablolar
• Temettü, split, kurumsal işlemler
• Analist hedefleri ve tavsiyeler

borsapy'ye Özgü

• TradingViewStream: Gerçek zamanlı WebSocket streaming - quote, OHLCV, Pine Script göstergeleri
• Backtest Engine: Strateji backtesting framework - Sharpe, max drawdown, trade analizi
• Replay Mode: Backtesting için tarihsel candle-by-candle oynatma
• Search: TradingView sembol arama - hisse, döviz, kripto, endeks, vadeli
• TA Signals: TradingView teknik analiz sinyalleri - AL/SAT/TUT (11 oscillator + 17 MA)
• Heikin Ashi: Alternatif mum grafiği hesaplama
• ETF Holders: Uluslararası ETF'lerin hisse pozisyonları
• Portfolio: Çoklu varlık portföy yönetimi + risk metrikleri (Sharpe, Sortino, Beta, Alpha)
• FX: Döviz ve emtia verileri + banka kurları + intraday (TradingView)
• Crypto: Kripto para (BtcTurk)
• Fund: Yatırım fonları + varlık dağılımı + tarama/karşılaştırma + stopaj oranları (TEFAS)
• Inflation: Enflasyon verileri ve hesaplayıcı (TCMB)
• VIOP: Vadeli işlem/opsiyon + gerçek zamanlı streaming + kontrat arama
• Bond: Devlet tahvili faiz oranları + risk_free_rate (doviz.com)
• TCMB: Merkez Bankası faiz oranları - politika, gecelik, LON + geçmiş (tcmb.gov.tr)
• Eurobond: Türk devlet eurobondları - 38+ tahvil, USD/EUR (ziraatbank.com.tr)
• EconomicCalendar: Ekonomik takvim - 7 ülke desteği (doviz.com)
• Screener: Hisse tarama - 50+ kriter, sektör/endeks filtreleme (İş Yatırım)
• Teknik Analiz: 12+ gösterge (SMA, EMA, RSI, MACD, Bollinger, ATR, Stochastic, OBV, VWAP, ADX, Supertrend, Tilson T3, Heikin Ashi)
• Twitter/X: Tweet arama — hisse, fon, döviz, kripto entegrasyonu (Scweet, optional dep)
• KAP Entegrasyonu: Resmi bildirimler ve takvim

---

Katkıda Bulunma

Ek özellik istekleri ve öneriler için GitHub Discussions üzerinden tartışma açabilirsiniz.

---

Sorumluluk Reddi

Bu kütüphane aracılığıyla erişilen veriler, ilgili veri kaynaklarına aittir:

• İş Yatırım (isyatirim.com.tr): Finansal tablolar, hisse tarama, VIOP
• TradingView (tradingview.com): Hisse OHLCV, endeksler, gerçek zamanlı streaming, teknik analiz sinyalleri, sembol arama, ETF sahipliği
• KAP (kap.org.tr): Şirket bildirimleri, ortaklık yapısı
• TCMB (tcmb.gov.tr): Enflasyon verileri, merkez bankası faiz oranları
• BtcTurk: Kripto para verileri
• TEFAS (tefas.gov.tr): Yatırım fonu verileri
• doviz.com: Döviz kurları, banka kurları, ekonomik takvim, tahvil faizleri
• canlidoviz.com: Döviz kurları, emtia fiyatları
• Ziraat Bankası (ziraatbank.com.tr): Eurobond verileri
• hedeffiyat.com.tr: Analist hedef fiyatları
• isinturkiye.com.tr: ISIN kodları
• Twitter/X (x.com): Tweet verileri (Scweet kütüphanesi aracılığıyla, optional dependency)

Kütüphane yalnızca kişisel kullanım amacıyla hazırlanmıştır ve veriler ticari amaçlarla kullanılamaz.

---

Lisans

Apache 2.0