Metadata-Version: 2.4
Name: twap-engine
Version: 0.1.0
Summary: Borsa-agnostik, bağımsız bir TWAP (Time-Weighted Average Price) emir dağıtım motoru. ccxt destekli her borsada çalışır.
Author: Akin Urkmez
License: MIT
Project-URL: Homepage, https://pypi.org/project/twap-engine/
Keywords: twap,trading,crypto,ccxt,algo-trading,execution
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Office/Business :: Financial :: Investment
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: ccxt
Dynamic: license-file

# TWAP Engine (Standalone)

Borsa-agnostik, bağımsız bir **Time-Weighted Average Price (TWAP)** emir
dağıtım motoru. Herhangi bir [ccxt](https://github.com/ccxt/ccxt) destekli
borsada (Binance, Bybit, Kraken, vb.) çalışır. Hiçbir belirli projeye ya da
altyapıya bağımlı değildir.

## Özellikler

- Büyük bir emri N eşit parçaya bölüp zaman aralığına yayar
- **Slippage-abort**: fiyat referans noktasından belirli bir yüzdeden fazla
  kayarsa kalan dilimleri otomatik iptal eder
- **Minimum notional koruması**: borsanın minimum emir tutarının altında
  kalacak dilimleri, hiç başlamadan reddeder

> Bu, **temel (ücretsiz) sürümdür** — mekanik TWAP dağıtımı ve temel
> güvenlik kontrollerini içerir. Eklenebilir/özel risk zekası (RSI, order
> book analizi, haber akışı gibi harici sinyallere göre otomatik karar veren
> katman) ayrı bir gelişmiş sürümün konusudur.

## Kurulum

```bash
pip install twap-engine
```

Kaynak koddan kurmak isterseniz:

```bash
git clone <bu-repo>
cd twap_engine_standalone
pip install -e .
```

## Hızlı Başlangıç

```python
import asyncio
import ccxt.async_support as ccxt
from twap_engine import TWAPEngine

async def main():
    exchange = ccxt.binance({
        "apiKey": "...",
        "secret": "...",
        "enableRateLimit": True,
    })
    exchange.set_sandbox_mode(True)  # ÖNCE TESTNET'TE DENEYİN

    engine = TWAPEngine(
        exchange=exchange,
        symbol="BTC/USDT",
        side="buy",
        total_amount=0.01,
        slices=5,
        interval_s=2.0,
        max_slippage_pct=0.003,   # %0.3
        min_notional_usd=10.0,
        order_type="market",
    )

    result = await engine.run()
    print(result.status, result.slices_sent, "/", result.slices_requested)

    await exchange.close()

asyncio.run(main())
```

Daha fazla örnek için `example.py` dosyasına bakın.

## Sonuç Nesnesi (TWAPResult)

| Alan | Açıklama |
|---|---|
| `status` | `COMPLETED`, `ABORTED_SLIPPAGE`, `REJECTED_MIN_NOTIONAL`, `PARTIAL_ERROR` |
| `slices_sent` / `slices_requested` | Kaç dilim gönderildi / istendi |
| `filled_amount` | Gönderilen toplam miktar (base asset) |
| `aborted_reason` | İptal/red nedeni (varsa) |
| `orders` | Borsadan dönen ham emir yanıtları |
| `errors` | Dilim bazında yakalanan hatalar |

## Testler

Gerçek borsaya bağlanmayan, sahte (fake) exchange ile çalışan hafif testler:

```bash
python test_engine.py
```

## Sınırlamalar / Sorumluluk Reddi

- Bu yazılım **"OLDUĞU GİBİ" (AS-IS)** sunulmaktadır, HİÇBİR GARANTİ VERİLMEZ.
- Finansal kayıplardan yazar sorumlu değildir. Gerçek parayla kullanmadan
  önce mutlaka testnet/sandbox ortamında test edin.
- Bu motor emir GÖNDERMEYİ yönetir; risk yönetimi, pozisyon takibi, kasa
  muhasebesi gibi konular KAPSAM DIŞIDIR — kendi sisteminize entegre ederken
  bunları siz eklemelisiniz.
- Yalnızca "spot" tarzı basit emirler için tasarlanmıştır; kaldıraçlı/vadeli
  işlemler için ek risk kontrolleri (likidasyon, marj) GEREKLİDİR ve bu
  pakette YOKTUR.
- Ticari kullanım/satış öncesi kendi lisans metninizi (MIT, ticari lisans
  vb.) ve yasal sorumluluk reddi maddelerinizi eklemeniz önerilir — bu
  paket bir lisans dosyası içermez.
