Lighter Agent Kit
使用相同命令在Lighter或其在Robinhood Chain上的部署上进行交易。
脚本位于此技能的 scripts/ 目录中。读取命令使用 query.py，写入命令使用 trade.py。每个命令输出结构化的JSON到标准输出。错误始终以JSON格式返回，如 {"error": "..."}。
命令使用 <group> <action> 语法，与Lighter UI对应（例如 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。
如何处理用户请求
- **符号约定：永续-裸代码，现货-交易对。**永续市场使用裸代码（
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 <子串> [--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——当你只需要一行时始终传递它们。 - 运行匹配的脚本：读取使用
python3 scripts/query.py <group> <action> ARGS，写入使用python3 scripts/trade.py <group> <action> ARGS。路径相对于此技能的目录。 - 解析JSON并清晰地呈现。
- 账户作用域命令和
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> 是永续代码（BTC）、现货交易对（ETH/USDC）或数字市场索引。--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（K线起始时间，毫秒）、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（PnL分析、资金审计、税务报告）时，传递 --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（永续代码或现货交易对）或 --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> 是永续代码（BTC、ETH）、现货交易对（ETH/USDC、LIT/USDC）或数字市场索引（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] | 账户健康：总资产价值、保证金要求、杠杆。自动刷新标记价格。 |
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 互换以切换引擎。例如：
# 真实交易
python3 scripts/trade.py order market BTC --side long --amount 0.5
# 模拟相同交易
python3 scripts/paper.py order market BTC --side long --amount 0.5