Lighter Agent Kit
同じコマンドでLighterまたはそのRobinhood Chainデプロイメント上で取引できます。
スクリプトはこのスキルの scripts/ ディレクトリにあります。読み取りコマンドは query.py を、書き込みコマンドは trade.py を使用します。すべてのコマンドは構造化JSONを標準出力に出力します。エラーは常に {"error": "..."} 形式のJSONで報告されます。
コマンドはLighter UIと同様に <group> <action> 構文を使用します（例：market stats、order limit、orders open）。
レスポンススキーマと詳細については、references/ フォルダを参照してください。
インストール
このフォルダを標準のClaude Codeスキル場所のいずれかにコピーします。
- 個人（全プロジェクト）：
~/.claude/skills/lighter-agent-kit/ - プロジェクトレベル（このリポジトリのみ）：
.claude/skills/lighter-agent-kit/
初回呼び出し時に、lighter-sdk とその推移的依存関係が <skill>/.vendor/pyX.Y/ にインストールされます。すべてのバージョンは requirements.lock で固定されています。サポート対象はApple Silicon Mac、Linux x86_64/arm64です。Intel Macはこのキットではサポートされていません。
選択したLighterホスト（mainnet.zklighter.elliot.ai、testnet.zklighter.elliot.ai、api.rh.lighter.xyz、api.rh-testnet.lighter.xyz）、pypi.org / files.pythonhosted.org、および github.com（pipが固定された lighter-sdk ビルドをGitHubからクローンするため）へのネットワーク出力が必要です。Claude.aiのサンドボックスでは、デフォルトの出力許可リストに github.com が含まれていないため、初回実行前に拡張する必要があります。
読み取りコマンドは認証なしで動作します。書き込みコマンドとアカウントプライベートな読み取りは、最初に環境変数をチェックし、次に個人の認証情報ファイルを確認します。references/env-vars.md を参照してください。
ユーザーリクエストの処理方法
- シンボル規則：無期限はベア、スポットはペア。 無期限市場はベアティッカー（
BTC、ETH、SOL、LIT）を使用します。スポット市場はクォート通貨で修飾されたペア（LighterではETH/USDC、Robinhood LighterではAAPL/USDG）を使用します。/の有無が唯一の判別子であり、シンボル解決済みのコマンドに--market_typeフラグは必要ありません。数値のmarket_indexもエスケープハッチとして受け入れられます。 - シンボル解決は自動的に行われます。 マーケットシンボルはライブのオーダーブックAPIから解決され、ホストごとに5分間ディスクにキャッシュされるため、
query.py、trade.py、paper.pyは呼び出し間で同じマーケットマップを共有します。ファンドアセットは選択されたデプロイメントに対して解決されます。collateralは、曖昧でない場合にそのクォートアセットのエイリアスとして機能します。ユーザーが自信を持ってマッピングできないもの（例：「ブレント原油」、「ゴールド」、「シルバー」）を言った場合のみ、最初にpython3 scripts/query.py market list --search <substring> [--market_type perp|spot]を実行して検出します。これらは通常、BRENTOIL、XAU、XAGのようなティッカースタイルのシンボルで表示されます。 - サイドは両方の形式を受け入れます。
--side buy|sell|long|short— 無期限とスポットの両方で受け入れられます。内部的に正規化されます（無期限はlong/short、スポットはbuy/sell）。 - 高カーディナリティの読み取りではソースでフィルタリングします。
market funding、market stats、market infoは--symbol/--market_index/--exchangeを受け入れます — 1行だけ必要な場合は常にこれらを渡します。 - 適切なスクリプトを実行します。読み取りは
python3 scripts/query.py <group> <action> ARGS、書き込みはpython3 scripts/trade.py <group> <action> ARGS。パスはこのスキルのディレクトリからの相対パスです。 - JSONを解析し、明確に表示します。
- アカウントスコープのコマンドと
LIGHTER_ACCOUNT_INDEX。 2つのケースがあります：- パブリック読み取り（
account info、account apikeys）は--account_indexを受け入れ、省略時はLIGHTER_ACCOUNT_INDEXをデフォルトとします。 - 認証付き読み取り（
account limits、portfolio performance、orders open、orders history）は自己のみであり、--account_indexの代わりにLIGHTER_ACCOUNT_INDEXを使用します。認証トークンがそのアカウントにバインドされているためです。
- パブリック読み取り（
診断（オプション）： 呼び出しが import lighter スタイルのエラーで失敗した場合、python3 scripts/bootstrap.py を実行してSDKが正しくベンダー化されていることを確認します。status: ok フィールドを持つレスポンスを返すはずです。正常なセッションではこれを実行する必要はありません。
読み取りコマンド（query.py）
パブリック読み取り — 認証不要
| コマンド | 目的 |
|---|---|
system status | zkLighterシステムステータス（ネットワークID、タイムスタンプ）。 |
market list [--market_type perp|spot] [--search X] | コンパクトな {symbol, market_index, market_type} カタログ。シンボル→インデックス検索に使用します。 |
market stats [--symbol X] | 市場概要：価格、24時間出来高、日次取引数。--symbol を渡すと1行取得します。 |
market info [--market_type perp|spot] [--symbol X] | 完全な市場メタデータ（手数料、小数点以下桁数、最小サイズ）。常にフィルタリングします。フィルタリングしないと約150行になります。 |
market book <symbol> [--limit 20] | トップオブブックのbidとask。<symbol> は無期限ティッカー（BTC）、スポットペア（ETH/USDC）、または数値のmarket_indexです。--limit はサイドごとです。 |
market trades <symbol> [--limit 20] | 1つの市場の最近の約定。--limit は最大100。 |
market candles <symbol> --resolution 1h --count_back 24 | OHLCVローソク足。解像度：1m、5m、15m、30m、1h、4h、1d。o/h/l/c（価格）、v（ベース出来高）、V（クォート出来高）、t（バケット開始時刻、ミリ秒）、i（最後のトレードID）を返します。 |
market funding [--symbol X] [--market_index N] [--exchange X] | 取引所間の資金調達レート。フィルタリングなしで約300行。常に --symbol または --exchange を渡します。 |
account info [--account_index N] [--by l1_address --value 0x…] [--include_zero_positions] | アカウントルックアップ：残高、ポジション、アセット。デフォルトは LIGHTER_ACCOUNT_INDEX。--by l1_address --value … を使用してL1アドレスで検索することもできます。positions[] はデフォルトで現在オープン中のポジションのみにフィルタリングされます — Lighterはアカウントがかつて触れた市場ごとに1行を保持するため、生のリストは非常に大きくなり、ほとんどがフラットになる可能性があります。市場ごとのライフタイム realized_pnl / total_funding_paid_out が必要な場合（PnL分析、資金調達監査、税務レポート）は --include_zero_positions を渡します。 |
account apikeys [--account_index N] [--api_key_index N] | アカウントのAPIキーを一覧表示します。--api_key_index を省略（デフォルトは255）するとすべてのキーを一覧表示します。 |
auth status | ローカルのみの認証情報事前チェック。auth_capable + 認証情報ごとのソースを返します。認証付き呼び出しの前に1回実行します。 |
アカウントプライベート読み取り — LIGHTER_API_PRIVATE_KEY + LIGHTER_ACCOUNT_INDEX + LIGHTER_API_KEY_INDEX が必要
これらのエンドポイントは、呼び出しごとに設定された認証情報から短期有効な認証トークンを生成します。認証トークンは LIGHTER_ACCOUNT_INDEX にバインドされているため、以下の4つのコマンドはすべて自己のみです — --account_index を受け入れず、秘密鍵でトークンに署名したアカウントとは異なるアカウントをクエリする方法はありません。
| コマンド | 目的 |
|---|---|
account limits | 取引制限とティア情報。 |
portfolio performance --resolution 1h --count_back 24 | 時間範囲にわたるPnLチャート。 |
orders open (--symbol X | --market_index N) | 1つの市場のオープンオーダー。--symbol（無期限ティッカーまたはスポットペア）または --market_index のいずれかを渡します。 |
orders history [--symbol X] [--market_index N] [--limit 20] | 約定済み/キャンセル済みの注文履歴。市場フィルターはオプションです。 |
プラットフォーム注記： claude.aiのサンドボックス化されたbash環境では、env varsを
exportするための永続的なシェルがなく、API秘密鍵をチャットに貼り付けることは許容されません。上記4つのコマンドは事実上Claude Code / Cursor / デスクトップのみと見なしてください。claude.aiでは、パブリック読み取りにフォールバックするか、アカウントプライベートなビューについてはユーザーをLighterのウェブ/モバイルUIに誘導してください。
正常性確認：python3 scripts/health.py はSDKに触れることなく {"status": "ok", "version": "..."} を返します — スキルがロードされていることを確認するのに役立ちます。
完全なレスポンス形状については、references/schemas-read.md を参照してください。
書き込みコマンド（trade.py）
すべての書き込みコマンドには認証情報が必要です。 価格と数量は人間単位です（例：--price 4050.5 --amount 0.1）。スクリプトは市場メタデータを取得し、自動的に整数のティック/ロットにスケーリングします。レスポンスは effective_amount / effective_price をエコーバックするため、丸め後に実際に何が設定されたかを確認できます。
サイドは両方の形式を受け入れます： --side buy|sell|long|short。無期限市場とスポット市場の両方で受け入れられます。内部的に正規化されます（無期限はlong/short、スポットはbuy/sell）。
シンボル規則： 位置引数 <symbol> は、無期限ティッカー（BTC、ETH）、スポットペア（ETH/USDC、LIT/USDC）、または数値の market_index（1）です。スポットシンボル内の / が判別子であり、--market_type フラグは必要ありません。
スポット取引： すべての注文コマンドはスポット市場でも透過的に機能します — ETH/USDC のようなスポットペアを渡すだけです。query.py market list --market_type spot を使用して検出します。スポット市場では、--reduce_only および position leverage / position margin コマンドは何も行いません — スポットにはレバレッジポジションはありません。
| コマンド | 主要引数 |
|---|---|
order limit <symbol> --side <side> --amount N --price N [--reduce_only] [--post_only] | 無期限またはスポットの指値注文。 |
order market <symbol> --side <side> --amount N [--slippage N] [--reduce_only] | 無期限またはスポットの成行注文。デフォルトスリッページ 0.01（1%）。 |
order modify <symbol> --order_index COI --price N --amount N | COI は order limit が返す client_order_index です。 |
order cancel <symbol> --order_index COI | 単一のオープンオーダーをキャンセルします。 |
order cancel_all | すべての市場のすべてのオープンオーダーをキャンセルします（引数なし）。 |
order close_all [--slippage N] [--with_cancel_all] [--preview] | 高リスク。 すべてのオープンポジションをreduce-only成行注文でフラットにします — すべての市場で一度にPnLを確定します。必ず最初に --preview を実行し、実際の呼び出しの前に明示的なユーザー承認を得てください。「クリーンアップ」や「リセット」などのフレーズから意図を自動推論しないでください。--with_cancel_all はTP/SLブラケットも削除します。--preview と組み合わせると、レスポンスには最初にcancel-allが実行されるという注記が含まれますが、would_close[] には引き続きポジションのみがリストされます。 |
position leverage <symbol> --leverage N [--margin_mode cross|isolated] | レバレッジを設定します。デフォルト cross。 |
position margin <symbol> --amount N --direction add|remove | 金額はデプロイメントの担保（USDCまたはUSDG）です。分離ポジションでのみ有効です。 |
account mode --mode classic|unified | 高リスク。 アカウント全体の証拠金動作を変更します。query.py account info を検査し、最初に明示的なユーザー承認を得てください。 |
account collateral --asset A --mode enabled|disabled | 高リスク。 対象となるアセットがUnifiedモードで担保に貢献するかどうかを変更します。アカウントを検査し、最初に明示的なユーザー承認を得てください。 |
funds withdraw --asset A --amount N [--route perp|spot] | デフォルトルート perp。任意のデプロイメントアセットシンボルまたは数値のアセットIDを受け入れます。曖昧でない場合、collateral はクォートアセットのエイリアスとして機能します。これにより出金リクエストが作成されます。資金はペンディング/クレームフローに移行し、ウォレットに即座に表示されない場合があります。 |
funds transfer --asset A --amount N --from_route perp|spot --to_route perp|spot | 任意のデプロイメントアセットを自身のスポットと無期限バケット間で移動します。L1署名は不要で、アカウント間ルーティングはありません。 |
order limit と order market は client_order_index を返します — これを保存してください。 後続の order modify / order cancel のためのハンドルです。
例 — デプロイメント担保を無期限からスポットに移動してスポット購入に資金を供給する：
python3 scripts/trade.py funds transfer --asset collateral --amount 250 \
--from_route perp --to_route spot
例 — Robinhood LighterでSPY担保を有効にする：
python3 scripts/query.py account info
python3 scripts/trade.py account mode --mode unified
python3 scripts/query.py account info # account_trading_mode が 1 になるまで待機
python3 scripts/trade.py account collateral --asset SPY --mode enabled
python3 scripts/query.py account info
上記2つの書き込みコマンドには、個別の明示的なユーザー承認が必要です。account collateral --mode enabled は、選択されたデプロイメントが担保適格とマークしていないアセットと、Classicモードのアカウントを拒否します。
すべてのコマンドは --help をサポートしています。レスポンスエンベロープ、精度エコーバック、エラーコードテーブルについては、references/schemas-write.md を参照してください。
ペーパートレーディング（paper.py）
実際のLighterオーダーブックスナップショットに対して、認証情報なし、ブロードキャストなし、リスクなしで取引をシミュレートします。すべての状態はローカルです。
共有サブセットコマンドは trade.py と同一の <group> <action> 形状を使用するため、スクリプト名を入れ替えるだけでエンジンが切り替わります。ペーパーのみのライフサイクルコマンドはフラットなままです。
コマンド
ペーパーのみ（フラット）：
| コマンド | 目的 |
|---|---|
init [--collateral N] [--tier T] | ペーパーアカウントを作成します。デフォルト：--collateral 10000 --tier premium。 |
reset [--collateral N] [--tier T] | 状態を消去します。引数なしの形式は、以前のcollateralとtierを再利用します。 |
set_tier --tier T | 既存のアカウントの手数料ティアを変更します（キャッシュされた市場設定を更新します）。 |
status [--no-refresh] | アカウントサマリー：担保、PnL、ポジション/トレード数。すべてのオープンポジションのマーク価格を自動更新します。--no-refresh を渡すとスキップします。 |
positions [--symbol X] [--no-refresh] | オープンポジション。--symbol なしですべてを一覧表示します。マーク価格を自動更新します。 |
trades [--symbol X] [--limit 50] | トレード履歴、最新順。 |
health [--no-refresh] | アカウントヘルス：TAV、証拠金要件、レバレッジ。マーク価格を自動更新します。 |
liquidation_price <symbol> [--no-refresh] | ポジションの推定清算価格。マーク価格を自動更新します。 |
refresh <symbol> | 1つの市場のオーダーブックスナップショットを強制的に更新します。取引前に市場を事前ウォームアップする場合や、すべての読み取りで --no-refresh を渡さずに現在のマークデータが必要な場合に便利です。 |
共有サブセット（trade.pyの形状をミラーリング）：
| コマンド | 目的 |
|---|---|
order market <symbol> --side buy|sell|long|short --amount N | ライブブックスナップショットに対するテイカー成行注文。 |
order ioc <symbol> --side buy|sell|long|short --amount N --price N | 指値付きテイカーIOC注文。 |
入れ替えルール： trade.py ↔ paper.py を入れ替えて、認証情報と実際のブロードキャストの必要なしにまったく同じ引数でコマンドを実行します。ペーパーのみのコマンドは paper.py でのみ使用します。
python3 scripts/paper.py status を実行してアカウントを作成したことを確認してから、取引を開始します。