elliottech/lighter-agent-kit

Lighter Agent Kit

使用相同的指令在 Lighter 或其 Robinhood Chain 部署上進行交易。

腳本位於此技能的 scripts/ 目錄中。讀取指令使用 query.py，寫入指令使用 trade.py。每個指令都會將結構化 JSON 輸出到 stdout。錯誤訊息一律以 JSON 格式呈現，如 {"error": "..."}。

指令使用 <group> <action> 語法，與 Lighter 使用者介面一致（例如 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 會從 GitHub 克隆鎖定的 lighter-sdk 建置）。在 Claude.ai 的沙盒環境中，預設的出口允許清單不包含 github.com — 你需要在首次執行前將其加入白名單。

讀取指令無需憑證即可運作。寫入指令與帳戶私有讀取會先檢查環境變數，然後再檢查你的個人憑證檔案 — 請參閱 references/env-vars.md。

如何處理使用者請求

1. 符號慣例：永續合約使用 bare ticker，現貨使用貨幣對。 永續合約市場使用 bare ticker（BTC、ETH、SOL、LIT）；現貨市場使用報價貨幣對（Lighter 上為 ETH/USDC，Robinhood Lighter 上為 AAPL/USDG）。/ 的存在是唯一的區分標誌 — 在符號已解析的指令上不需要 --market_type 旗標。數值型的 market_index 也可作為備用方式接受。
2. 符號解析是自動的。 市場符號會從即時的訂單簿 API 解析，並在磁碟上快取 5 分鐘（依主機區分），因此 query.py、trade.py 和 paper.py 在多次呼叫之間共享相同的市場映射。資金資產會根據所選部署進行解析；當明確無誤時，collateral 會作為其報價資產的別名。只有當使用者說出你無法自信地映射的內容時（例如「布倫特原油」、「黃金」、「白銀」），才先執行 python3 scripts/query.py market list --search <子字串> [--market_type perp|spot] 來發現它們。這些通常以 ticker 風格的符號出現，如 BRENTOIL、XAU 和 XAG。
3. 方向接受兩種形式。 --side buy|sell|long|short — 在永續合約與現貨市場上兩者都接受。內部會正規化為標準形式（永續合約用 long/short，現貨用 buy/sell）。
4. 在高基數讀取時在來源端進行過濾。 market funding、market stats 和 market info 接受 --symbol / --market_index / --exchange — 當你只需要一行資料時，請務必傳入這些參數。
5. 執行對應的腳本：讀取用 python3 scripts/query.py <group> <action> ARGS，寫入用 python3 scripts/trade.py <group> <action> ARGS。路徑是相對於此技能的目錄。
6. 解析 JSON 並清晰呈現。
7. 帳戶範圍的指令與 LIGHTER_ACCOUNT_INDEX。 兩種情況：
   • 公開讀取（account info、account apikeys）接受 --account_index，省略時預設使用 LIGHTER_ACCOUNT_INDEX。
   • 需驗證的讀取（account limits、portfolio performance、orders open、orders history）是僅限自身的，使用 LIGHTER_ACCOUNT_INDEX 而非 --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 以獲取一行。
market info [--market_type perp|spot] [--symbol X]	完整的市場元資料（費用、小數位、最小數量）。務必過濾；未過濾時約有 150 行。
market book <symbol> [--limit 20]	頂部買賣盤報價。<symbol> 是 perp 的 ticker（BTC）、現貨貨幣對（ETH/USDC）或數值型 market_index。--limit 是每側的數量。
market trades <symbol> [--limit 20]	單一市場的近期成交。--limit 最大 100。
market candles <symbol> --resolution 1h --count_back 24	OHLCV K 線。解析度：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 會為帳戶曾接觸過的每個市場保留一行，因此原始列表可能非常龐大且大多是平的。當你需要每個市場的終身 realized_pnl / total_funding_paid_out 時（盈虧分析、資金審計、稅務報告），請傳入 --include_zero_positions。
account apikeys [--account_index N] [--api_key_index N]	列出帳戶的 API 金鑰。省略 --api_key_index（預設為 255）以列出所有金鑰。
auth status	僅限本機的憑證預檢。返回 auth_capable 加上每個憑證的來源。在驗證呼叫前執行一次。

帳戶私有讀取 — 需要 LIGHTER_API_PRIVATE_KEY + LIGHTER_ACCOUNT_INDEX + LIGHTER_API_KEY_INDEX

這些端點在每次呼叫時會從你設定的憑證產生一個短期驗證權杖。該驗證權杖綁定到 LIGHTER_ACCOUNT_INDEX，因此以下四個指令都是僅限自身的 — 它們不接受 --account_index，也無法查詢與簽署權杖的私鑰帳戶不同的帳戶。

指令	用途
account limits	交易限制與等級資訊。
portfolio performance --resolution 1h --count_back 24	一段時間範圍內的盈虧圖表。
orders open (--symbol X | --market_index N)	單一市場上的未成交訂單。傳入 --symbol（perp ticker 或現貨貨幣對）或 --market_index。
orders history [--symbol X] [--market_index N] [--limit 20]	已成交/已取消訂單歷史記錄。市場過濾為可選。

平台注意事項： 在 claude.ai 的沙盒化 bash 環境中，沒有持久的 shell 可以 export 環境變數，且將 API 私鑰貼到聊天中是不可接受的。將上述四個指令視為僅限 Claude Code / Cursor / 桌面環境使用。在 claude.ai 上，請回退到公開讀取或引導使用者前往 Lighter 網頁/行動 UI 以檢視帳戶私有視圖。

健全性檢查：python3 scripts/health.py 返回 {"status": "ok", "version": "..."}，無需觸及 SDK — 可用於確認技能已載入。

請參閱 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> 是 perp 的 ticker（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]	高風險。 使用只減倉市價單平掉所有未平倉持倉 — 一次性在所有市場上實現盈虧。務必先執行 --preview 並取得使用者的明確批准，然後再執行實際呼叫；不要從「清理」或「重置」等用語自動推斷意圖。--with_cancel_all 也會取消止盈/停損訂單。與 --preview 結合使用時，回應會包含一則備註，說明取消所有訂單會先執行，但 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	高風險。 更改符合條件的資產是否在統一模式下貢獻抵押品。檢查帳戶並先取得使用者的明確批准。
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

上述兩個寫入指令需要分別、明確的使用者批准。account collateral --mode enabled 會拒絕所選部署未標記為可作為抵押品的資產，並拒絕經典模式帳戶。

每個指令都支援 --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]	清除狀態。無引數形式會重複使用先前的抵押品和等級。
set_tier --tier T	變更現有帳戶的費用等級（更新快取的市場設定）。
status [--no-refresh]	帳戶摘要：抵押品、盈虧、持倉/交易計數。自動重新整理所有未平倉持倉的標記價格；傳入 --no-refresh 可跳過。
positions [--symbol X] [--no-refresh]	未平倉持倉。未指定 --symbol 時列出所有持倉。自動重新整理標記價格。
trades [--symbol X] [--limit 50]	交易歷史記錄，最新的排在最前面。
health [--no-refresh]	帳戶健康度：TAV、保證金要求、槓桿。自動重新整理標記價格。
liquidation_price <symbol> [--no-refresh]	持倉的估計清算價格。自動重新整理標記價格。
refresh <symbol>	強制重新整理一個市場的訂單簿快照。用於在交易前預熱市場，或當你想要當前的標記資料而不需要在每次讀取時傳遞 --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 以……

[已截斷以進行翻譯]