mzoe/ritmex-bot
1
0
Fork 0
mirror of https://github.com/discountry/ritmex-bot.git synced 2026-09-09 08:18:07 +00:00
Code Issues Packages Projects Releases Wiki Activity

feat(lighter): add Robinhood Chain venue support

Browse Source
This commit is contained in:
discountry
2026-08-14 14:05:37 +08:00
parent 0ea71503e3
commit f3a96886ac
14 changed files with 1009 additions and 139 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/exchanges/lighter.en.md
+53 -15
View File
@@ -8,18 +8,30 @@ This guide configures Lighter perpetuals and the integrated Spot markets. Lighte
## 1. Select a network
| `LIGHTER_ENV` | REST URL | Chain ID |
| --- | --- | --- |
| `mainnet` | `https://mainnet.zklighter.elliot.ai` | `304` |
| `testnet` | `https://testnet.zklighter.elliot.ai` | `300` |
| `staging` | `https://staging.zklighter.elliot.ai` | `300` |
| `dev` | `https://dev.zklighter.elliot.ai` | `300` |
| `LIGHTER_ENV` | REST URL | WebSocket | Signing chain ID | Quote asset |
| --- | --- | --- | --- | --- |
| `mainnet` | `https://mainnet.zklighter.elliot.ai` | `wss://mainnet.zklighter.elliot.ai/stream` | `304` | USDC |
| `rh` | `https://api.rh.lighter.xyz` | `wss://api.rh.lighter.xyz/stream` | `466324` | USDG |
| `testnet` | `https://testnet.zklighter.elliot.ai` | `wss://testnet.zklighter.elliot.ai/stream` | `300` | USDC |
| `rh-testnet` | `https://api.rh-testnet.lighter.xyz` | `wss://api.rh-testnet.lighter.xyz/stream` | `300` | USDG |
| `staging` | `https://staging.zklighter.elliot.ai` | `wss://staging.zklighter.elliot.ai/stream` | `300` | USDC |
| `dev` | `https://dev.zklighter.elliot.ai` | `wss://dev.zklighter.elliot.ai/stream` | `300` | USDC |
The current default is `testnet`. Set `LIGHTER_ENV=mainnet` explicitly for production trading.
`rh` is the Robinhood Chain deployment (web app at `robinhoodchain.lighter.xyz`). It is a separate chain from the main venue: accounts, API keys, market IDs and funds are not shared, and the signing chain ID differs.
**Switching venues means changing only `LIGHTER_ENV`** — the REST URL, WebSocket URL and signing chain ID are all derived from it together, so they cannot drift apart. The aliases `robinhood`, `robinhoodchain` and `rhc` all mean `rh`.
The current default is `testnet`. Set `LIGHTER_ENV=mainnet` or `LIGHTER_ENV=rh` explicitly for production trading.
At startup the bot prints one confirmation line and calls `/api/v1/layer1BasicInfo` to check the L1 chain ID and ZkLighter contract address against the configured deployment, failing immediately on a mismatch:
```
[Lighter] env=rh rest=https://api.rh.lighter.xyz ws=wss://api.rh.lighter.xyz/stream chainId=466324 account=12345
```
## 2. Obtain the account index and API key
1. Create and fund an account on [Lighter](https://app.lighter.xyz/?referral=111909FA).
1. Create and fund an account on [Robinhood Chain](https://robinhoodchain.lighter.xyz/?referral=RITMEX) (10% bonus points) or the [Lighter main venue](https://app.lighter.xyz/?referral=111909FA). Accounts on the two are independent.
2. Follow the official [Get Started guide](https://apidocs.lighter.xyz/docs/get-started) to query `account_index` from the L1 address.
3. Follow the official [API Keys guide](https://apidocs.lighter.xyz/docs/api-keys) to create an API key.
4. Save the API private key returned by the creation flow and record its `api_key_index`.
@@ -53,22 +65,45 @@ LIGHTER_SYMBOL=BTC
Testnet and mainnet credentials cannot be mixed.
## 5. Optional settings
## 5. Robinhood Chain configuration
```dotenv
EXCHANGE=lighter
LIGHTER_ENV=rh
LIGHTER_ACCOUNT_INDEX=<your_rh_account_index>
LIGHTER_API_KEY_INDEX=<your_rh_api_key_index>
LIGHTER_API_PRIVATE_KEY=<your_rh_api_private_key_hex>
LIGHTER_SYMBOL=BTC
```
What changes when switching venues:
- **Credentials are venue-specific.** Create the account index and API key on Robinhood Chain itself.
- **Market IDs use a different numbering**, so reusing one across venues points at the wrong instrument. Leave `LIGHTER_MARKET_ID` unset unless metadata resolution fails, and clear it when coming from the main venue.
- **Spot is quoted in USDG, not USDC** — spot symbols look like `ETH/USDG`.
- The venue lists equity perpetuals (`TSLA`, `AAPL`, `NVDA`, …) and tokenized equity spot markets.
- `SGOV/USDG`, `ORCL/USDG` and `MU/USDG` have a contract `multiplier` other than 1 while order scaling assumes 1.0, so those markets are refused. Set `LIGHTER_ALLOW_NON_UNIT_MULTIPLIER=1` to trade them anyway.
## 6. Optional settings
| Variable | Purpose |
| --- | --- |
| `LIGHTER_BASE_URL` | Overrides the REST URL; known hostnames also determine the network |
| `LIGHTER_BASE_URL` | Overrides the REST URL; known hostnames determine the network, and a web-app URL (e.g. `robinhoodchain.lighter.xyz`) is remapped to its API host |
| `LIGHTER_WS_URL` | Overrides the WebSocket URL; derived from `LIGHTER_ENV` or `LIGHTER_BASE_URL` otherwise |
| `LIGHTER_L1_ADDRESS` | L1 address associated with the account |
| `LIGHTER_MARKET_ID` | Forces a market ID when metadata resolution fails |
| `LIGHTER_MARKET_ID` | Forces a market ID when metadata resolution fails; never reuse across venues |
| `LIGHTER_MARKET_TYPE` | `perp` or `spot` |
| `LIGHTER_PRICE_DECIMALS` | Forces price decimals |
| `LIGHTER_SIZE_DECIMALS` | Forces size decimals |
| `LIGHTER_CHAIN_ID` | Overrides the signing chain ID |
| `LIGHTER_CHAIN_ID` | Overrides the signing chain ID; required for a self-hosted or proxied host that cannot be recognized |
| `LIGHTER_ALLOW_NON_UNIT_MULTIPLIER` | Allows trading markets whose `multiplier` is not 1 |
| `LIGHTER_DEBUG` | Set to `1` or `true` for debug output |
Spot markets use symbols such as `ETH/USDC`. Explicit market IDs and decimal overrides must match order-book metadata for the selected network.
Spot markets use symbols such as `ETH/USDC` (main venue) or `ETH/USDG` (Robinhood Chain). Explicit market IDs and decimal overrides must match order-book metadata for the selected network.
## 6. Verify the configuration
For a self-hosted node or a proxy whose hostname cannot be recognized, `LIGHTER_CHAIN_ID` is mandatory: no endpoint exposes the signing chain ID, and guessing it wrong makes every transaction fail signature verification, so startup fails loudly instead of assuming a default.
## 7. Verify the configuration
```bash
bun run index.ts doctor --exchange lighter --symbol BTC --json
@@ -82,7 +117,10 @@ The ticker check loads market metadata, validates the account/API-key pair, and
- `LIGHTER_ACCOUNT_INDEX must be an integer`: use the numeric index returned by the account API.
- `Invalid LIGHTER_API_KEY_INDEX`: use the non-negative integer recorded during key creation.
- `private key does not match the one on Lighter`: the account index, key index, private key, or network differs.
- `Configured market id ... not found`: verify `LIGHTER_ENV`, `LIGHTER_SYMBOL`, and any manual market ID.
- `Configured market id ... not found`: verify `LIGHTER_ENV`, `LIGHTER_SYMBOL`, and any manual market ID. After switching venues the usual cause is a `LIGHTER_MARKET_ID` left over from the previous one.
- `Lighter network mismatch`: the REST URL and `LIGHTER_ENV` point at different deployments, caught before any order is signed. Reconcile `LIGHTER_ENV` and `LIGHTER_BASE_URL` against the table above.
- `Unknown Lighter environment`: `LIGHTER_ENV` is misspelled; the error lists every valid value and alias.
- `has contract multiplier ... not 1.0`: the market's contract multiplier is not 1 and sizing could be wrong; set `LIGHTER_ALLOW_NON_UNIT_MULTIPLIER=1` once you have verified the scaling.
- Signer loading failures: the repository ships macOS arm64 and Linux amd64 signer libraries. Other platforms require a compatible signer build or a supported WSL/Linux environment.
## Security
docs/exchanges/lighter.md
+53 -15
View File
@@ -8,18 +8,30 @@ English version: [Lighter Configuration Guide](lighter.en.md)
## 1. 选择网络
| `LIGHTER_ENV` | REST 地址 | Chain ID |
| --- | --- | --- |
| `mainnet` | `https://mainnet.zklighter.elliot.ai` | `304` |
| `testnet` | `https://testnet.zklighter.elliot.ai` | `300` |
| `staging` | `https://staging.zklighter.elliot.ai` | `300` |
| `dev` | `https://dev.zklighter.elliot.ai` | `300` |
| `LIGHTER_ENV` | REST 地址 | WebSocket | 签名 Chain ID | 计价资产 |
| --- | --- | --- | --- | --- |
| `mainnet` | `https://mainnet.zklighter.elliot.ai` | `wss://mainnet.zklighter.elliot.ai/stream` | `304` | USDC |
| `rh` | `https://api.rh.lighter.xyz` | `wss://api.rh.lighter.xyz/stream` | `466324` | USDG |
| `testnet` | `https://testnet.zklighter.elliot.ai` | `wss://testnet.zklighter.elliot.ai/stream` | `300` | USDC |
| `rh-testnet` | `https://api.rh-testnet.lighter.xyz` | `wss://api.rh-testnet.lighter.xyz/stream` | `300` | USDG |
| `staging` | `https://staging.zklighter.elliot.ai` | `wss://staging.zklighter.elliot.ai/stream` | `300` | USDC |
| `dev` | `https://dev.zklighter.elliot.ai` | `wss://dev.zklighter.elliot.ai/stream` | `300` | USDC |
当前默认值为 `testnet`。生产交易应显式设置 `LIGHTER_ENV=mainnet`。
`rh` 是 Robinhood Chain 部署（网页端 `robinhoodchain.lighter.xyz`）。它与主站是两条独立的链：账户、API Key、market ID 和资金都不互通，签名 Chain ID 也不同。
**切换平台只需要改 `LIGHTER_ENV` 这一个变量** —— REST 地址、WebSocket 地址和签名 Chain ID 都由它一起派生，不会出现只改了一半的错配。别名 `robinhood`、`robinhoodchain`、`rhc` 等价于 `rh`。
当前默认值为 `testnet`。生产交易应显式设置 `LIGHTER_ENV=mainnet` 或 `LIGHTER_ENV=rh`。
启动时机器人会打印一行确认，并调用 `/api/v1/layer1BasicInfo` 用 L1 Chain ID 与 ZkLighter 合约地址核对连接的确实是配置声明的那条链，不一致直接报错退出：
```
[Lighter] env=rh rest=https://api.rh.lighter.xyz ws=wss://api.rh.lighter.xyz/stream chainId=466324 account=12345
```
## 2. 获取账户索引和 API Key
1. 在 [Lighter](https://app.lighter.xyz/?referral=111909FA) 创建并入金账户。
1. 创建并入金账户：[Robinhood Chain](https://robinhoodchain.lighter.xyz/?referral=RITMEX)（额外 10% 积分加成）或 [Lighter 主站](https://app.lighter.xyz/?referral=111909FA)。两个平台的账户互相独立。
2. 按[官方 Get Started](https://apidocs.lighter.xyz/docs/get-started) 使用 L1 地址查询 `account_index`。
3. 按[官方 API Keys 指南](https://apidocs.lighter.xyz/docs/api-keys) 创建 API Key。
4. 保存创建流程返回的 API 私钥，并记录对应的 `api_key_index`。
@@ -53,22 +65,45 @@ LIGHTER_SYMBOL=BTC
测试网和主网凭证不可混用。
## 5. 可选配置
## 5. Robinhood Chain 配置
```dotenv
EXCHANGE=lighter
LIGHTER_ENV=rh
LIGHTER_ACCOUNT_INDEX=<your_rh_account_index>
LIGHTER_API_KEY_INDEX=<your_rh_api_key_index>
LIGHTER_API_PRIVATE_KEY=<your_rh_api_private_key_hex>
LIGHTER_SYMBOL=BTC
```
切换平台时的注意事项：
- **凭证不通用**：Robinhood Chain 的账户索引和 API Key 必须在该平台单独创建。
- **market ID 是另一套编号**，跨平台复用必然指向错误的标的。除非自动解析失败，否则不要设置 `LIGHTER_MARKET_ID`；从主站切过来时务必清掉这个变量。
- **现货计价资产是 USDG 而非 USDC**，现货符号写成 `ETH/USDG`。
- 该平台提供股票类永续（`TSLA`、`AAPL`、`NVDA` 等）和代币化股票现货。
- `SGOV/USDG`、`ORCL/USDG`、`MU/USDG` 三个现货市场的合约 `multiplier` 不等于 1，而下单数量/价格换算按 1.0 处理，因此这些市场会被直接拒绝。确认自己清楚换算关系后可用 `LIGHTER_ALLOW_NON_UNIT_MULTIPLIER=1` 放行。
## 6. 可选配置
| 变量 | 说明 |
| --- | --- |
| `LIGHTER_BASE_URL` | 覆盖 REST 地址；网络可从已知主机名推断 |
| `LIGHTER_BASE_URL` | 覆盖 REST 地址；已知主机名会自动推断网络，填入网页端地址（如 `robinhoodchain.lighter.xyz`）会自动换成对应 API 地址 |
| `LIGHTER_WS_URL` | 覆盖 WebSocket 地址；不填时由 `LIGHTER_ENV` 或 `LIGHTER_BASE_URL` 派生 |
| `LIGHTER_L1_ADDRESS` | 账户关联的 L1 地址 |
| `LIGHTER_MARKET_ID` | 强制 market ID；仅在自动解析失败时设置 |
| `LIGHTER_MARKET_ID` | 强制 market ID；仅在自动解析失败时设置，且不可跨平台复用 |
| `LIGHTER_MARKET_TYPE` | `perp` 或 `spot` |
| `LIGHTER_PRICE_DECIMALS` | 强制价格小数位 |
| `LIGHTER_SIZE_DECIMALS` | 强制数量小数位 |
| `LIGHTER_CHAIN_ID` | 覆盖签名 Chain ID |
| `LIGHTER_CHAIN_ID` | 覆盖签名 Chain ID；自建/代理主机无法识别网络时必填 |
| `LIGHTER_ALLOW_NON_UNIT_MULTIPLIER` | 允许交易 `multiplier ≠ 1` 的市场 |
| `LIGHTER_DEBUG` | 设置为 `1` 或 `true` 输出调试日志 |
现货市场使用 `ETH/USDC` 这类符号。显式 market ID、价格小数位和数量小数位必须与目标网络的 order book 元数据一致。
现货市场使用 `ETH/USDC`（主站）或 `ETH/USDG`（Robinhood Chain）这类符号。显式 market ID、价格小数位和数量小数位必须与目标网络的 order book 元数据一致。
## 6. 验证配置
自建节点或走代理时，若主机名无法识别为已知部署，则必须显式设置 `LIGHTER_CHAIN_ID` —— 签名 Chain ID 没有任何接口可以查询，猜错会导致每一笔交易验签失败，因此这里选择直接报错而不是使用默认值。
## 7. 验证配置
```bash
bun run index.ts doctor --exchange lighter --symbol BTC --json
@@ -82,7 +117,10 @@ bun run index.ts market ticker --exchange lighter --symbol BTC --json
- `LIGHTER_ACCOUNT_INDEX must be an integer`：填写账户接口返回的数字索引。
- `Invalid LIGHTER_API_KEY_INDEX`：使用创建 Key 时记录的非负整数索引。
- `private key does not match the one on Lighter`：账户索引、Key 索引、私钥或网络不匹配。
- `Configured market id ... not found`：检查 `LIGHTER_ENV`、`LIGHTER_SYMBOL` 和手动 market ID。
- `Configured market id ... not found`：检查 `LIGHTER_ENV`、`LIGHTER_SYMBOL` 和手动 market ID。跨平台切换后最常见的原因是 `LIGHTER_MARKET_ID` 仍是上一个平台的编号。
- `Lighter network mismatch`：REST 地址与 `LIGHTER_ENV` 指向了不同的部署，机器人在下单前拦下了这个错配。按上表核对 `LIGHTER_ENV` 与 `LIGHTER_BASE_URL`。
- `Unknown Lighter environment`：`LIGHTER_ENV` 拼写错误，报错信息会列出全部合法取值与别名。
- `has contract multiplier ... not 1.0`：该市场的合约乘数不为 1，换算可能失真；确认无误后用 `LIGHTER_ALLOW_NON_UNIT_MULTIPLIER=1` 放行。
- signer 加载失败：仓库预置 macOS arm64 与 Linux amd64 签名库，其他平台需要构建兼容签名库或使用受支持的 WSL/Linux 环境。
## 安全要求