【システム実装検証②】PythonでkabuステーションAPIの口座残高（買付余力）を取得する

2026.04.19

前回の記事では、PythonからkabuステーションにAPIパスワードを送信し、通信の鍵となる「APIトークン」を取得・保存するプログラムを作成しました。
今回は、その保存したトークンを実際に使用し、API経由で「現在の口座残高（現物買付余力）」を取得するプログラムのテストを行います。

事前準備：config.pyのアップデート

本番環境と検証環境の切り替えをスムーズにするため、ポート番号もconfig.pyで一元管理できるように追記しておきます。

# config.py
KABU_API_PASSWORD = "ここに設定したAPIパスワードを入力"
KABU_TOKEN_PATH = "kabu_token.txt"

# kabuステーションのポート番号（本番:18080 / 検証:18081）
KABU_PORT = 18080

残高取得のPython検証コード（実運用向け）

以下が、口座の買付余力を取得するコードです。
単に通信するだけでなく、「通信は成功したけれど、証券会社側でエラー（業務エラー）が起きているケース」を見逃さないための安全対策を組み込んでいます。

import requests
import config

def check_wallet_cash():
    """保存されたトークンを読み込み、買付余力（残高）を取得する"""
    print("口座の買付余力を確認中...")

    try:
        with open(config.KABU_TOKEN_PATH, 'r', encoding='utf-8') as f:
            token = f.read().strip()
    except FileNotFoundError:
        print("エラー: トークンファイルが見つかりません。先に取得処理を実行してください。")
        return None

    # config.py からポート番号を読み込んでURLを生成
    url = f'http://localhost:{config.KABU_PORT}/kabusapi/wallet/cash'
    headers = {'X-API-KEY': token}

    try:
        response = requests.get(url, headers=headers, timeout=5)
        response.raise_for_status()
        content = response.json()

        # 【重要】HTTP 200（通信成功）でも業務エラーが返るケースの検知
        if 'Code' in content and 'Message' in content:
            print(f"業務エラー発生: [Code:{content['Code']}] {content['Message']}")
            return None

        stock_account_wallet = content.get('StockAccountWallet', 0)
        print(f"通信成功！現在の買付余力: {stock_account_wallet:,} 円")
        return stock_account_wallet

    except requests.exceptions.RequestException as e:
        print(f"API通信エラーが発生しました: {e}")
        return None

if __name__ == "__main__":
    check_wallet_cash()

実運用を見据えた設計の「トレードオフ」

今回、APIを用いた残高取得の基礎テストを行いましたが、当システムでは毎回の発注前にこの「残高照会」を行うことはせず、「発注してエラー（余力不足）が返ってきたらメール通知する」という例外検知型（事後検知）の設計を暫定的に採用しています。

この設計には、以下のような明確なメリットと懸念点（トレードオフ）が存在します。

  • 【メリット】 APIコール数が減るため、処理が軽量・高速になり、コードもシンプルになる。
  • 【懸念点】 正常な処理が「エラー（例外）前提」になってしまうため、将来的にポジション管理が複雑化した際、ロジックのバグなのか単なる資金不足なのかの切り分けが難しくなる。

より実用性を高める（一段上のシステムにする）ためのベストプラクティスとしては、「1日の起動時に1回だけAPIで実残高を取得し、その後の日中の取引はプログラム内部で仮想的に残高を減算管理する」という手法が挙げられます。

まずはシンプルな例外検知型で検証を進めますが、今後運用資金が大きくなり、トークンの有効期限切れによる自動リカバリ（再取得フロー）や高度な資金管理が必要になった段階で、上記のような「状態管理」を持たせたシステムへのリファクタリング（改修）を予定しています。

APIを通じたGET通信と、業務エラー検知の基礎が確認できました。
次回は、同じくGET通信を用いて「現在保有している建玉（ポジション）の数量と評価損益」を取得するプログラムのテストを行います。
これは、システムが正しく稼働しているか、また想定外のリスク（過剰なポジション）を抱えていないかを、日次で正確にモニタリングするための非常に重要な機能となります。