Metadata-Version: 2.4
Name: bitflyer-api-client
Version: 0.1.0
Summary: A lightweight bitFlyer API client for Python
Author-email: redmeteor777 <49332536+redmeteor777@users.noreply.github.com>
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: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests
Requires-Dist: websocket-client>=1.0
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: python-dotenv; extra == "dev"
Requires-Dist: mypy; extra == "dev"
Requires-Dist: types-requests; extra == "dev"
Dynamic: license-file

# bitflyer-api-client

[![Python Version](https://img.shields.io/badge/python-3.9%2B-blue)](https://www.python.org/)
[![Test Coverage](https://img.shields.io/badge/coverage-100%25-brightgreen)](https://github.com/redmeteor777/bitflyer-api-client)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

bitFlyer Lightning API (REST / Realtime) を利用するためのPythonクライアントライブラリ。
エラーハンドリング、リトライ処理、レスポンスの整形を担当するサービス層を提供し、堅牢な自動取引システムの構築を提供する。

## 概要

本パッケージは、bitFlyer APIとの通信を抽象化し、型安全な実装を可能にすることを目的としている。
低レイヤーの通信を担う `BitflyerRestAPI` / `BitflyerRealtimeAPI` と、それらを利用して業務ロジックを提供する `BitflyerApiService` の二層構造で構成される。

## 特徴

- **カバレッジ100%**: 全てのロジックがユニットテストで検証済み。
- **完全な型ヒント**: `mypy` 等の静的解析ツールに完全対応。
- **設計品質**: docstringにはNumpyスタイルを採用し、日本語による動作説明を完備。

## 動作環境

- Python 3.9 以上(3.9, 3.12 で動作確認済み)
- OS: 依存パッケージ(requests, websocket-client)はクロスプラットフォーム対応のため、Windows/macOS/Linuxいずれでも動作する想定(本リポジトリでの動作確認はWindows環境のみ)
- 依存パッケージ: `requests`, `websocket-client`

## インストール

```bash
pip install bitflyer-api-client
```
## クイックスタート

```python
import os
from bitflyer_api_client import BitflyerApiService, BitflyerRestAPI, BitflyerApiError

def main() -> None:
    # クライアントの初期化
    api_key = os.getenv("BITFLYER_API_KEY", "")
    api_secret = os.getenv("BITFLYER_API_SECRET", "")

    rest_client = BitflyerRestAPI(api_key=api_key, api_secret=api_secret)
    service = BitflyerApiService(rest_client=rest_client)

    try:
        # 中間価格の取得（Public API、APIキー不要）
        mid_price = service.get_mid_price_from_board("BTC_JPY")
        print(f"Current Mid Price: {mid_price}")

        # 資産残高の取得（Private API、要APIキー）
        balance = service.get_balance()
        print(f"Assets: {balance}")

    except BitflyerApiError as e:
        print(f"API呼び出しに失敗しました (status_code={e.status_code}): {e}")

if __name__ == "__main__":
    main()
```

## 環境変数

本ライブラリ自体は環境変数を読み込まない(`BitflyerRestAPI`のコンストラクタに `api_key`/`api_secret` を明示的に渡す設計)。以下は上記のクイックスタート例で使用している変数名の一例であり、任意の名前を使ってよい。

| 変数名 | 説明 |
| --- | --- |
| `BITFLYER_API_KEY` | bitFlyerから発行されたAPIキー |
| `BITFLYER_API_SECRET` | bitFlyerから発行されたAPIシークレット |

## エラーハンドリング

API呼び出しに失敗した場合(リトライ不可能なHTTPエラー、またはリトライ上限到達時)、`BitflyerApiService` の各メソッドは `BitflyerApiError` を送出する。HTTPステータスコードが分かる場合は `status_code` 属性に格納される。

```python
from bitflyer_api_client import BitflyerApiError

try:
    balance = service.get_balance()
except BitflyerApiError as e:
    print(e.status_code, e)
```

なお、引数の不正(例: `product_code` の未指定)は `ValueError` として即座に送出される。

## 開発とテスト

本プロジェクトをクローンして開発を行う場合は、以下の手順に従うこと。

```bash
cd bitflyer-api-client

# 開発用依存関係のインストール
pip install -e ".[dev]"

# テストの実行（カバレッジレポート含む）
pytest --cov=bitflyer_api_client --cov-report=term-missing
```

## 免責事項

本ソフトウェアの使用により生じた損害（投資による損失等）について、開発者は一切の責任を負わない。
実際の取引に投入する前に、必ず利用者自身の責任において十分な検証を行う必要がある。

## ライセンス

[MIT License](LICENSE)
