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

docs: update README and add bilingual configuration guides for exchanges

Browse Source 
- Changed installation command from `npx` to `bunx` for consistency.
- Added bilingual configuration guides for Aster and Backpack exchanges.
- Updated exchange details in the README to reflect new market types and required settings.
- Enhanced clarity in the supported exchanges section with updated variable names and descriptions.
This commit is contained in:
discountry
2026-07-12 11:51:45 +08:00
parent 35653c8beb
commit a6394191d8
20 changed files with 1669 additions and 238 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/exchanges/aster.en.md
+80
View File
@@ -0,0 +1,80 @@
# Aster Configuration Guide
中文版：[Aster 配置教程](aster.md)
## Scope
This guide configures the ritmex-bot Aster USDT perpetual adapter. The current adapter connects to the production endpoint at `https://fapi.asterdex.com`. Market symbols use compact uppercase values such as `BTCUSDT`.
## 1. Prepare the account and credentials
1. Connect a wallet, activate perpetual trading, and fund the account on [Aster](https://www.asterdex.com/en/referral/4665f3).
2. Create an API key from Aster's API management page and save the API key and API secret shown there.
3. Enable read and perpetual-trading permissions. Keep withdrawal permission disabled.
4. Add the bot server's fixed IP address to the key whitelist.
5. Select one-way position mode and configure leverage in the Aster interface.
Aster also publishes a [programmatic API-key registration flow](https://github.com/asterdex/api-docs/blob/master/demo/aster-api-key-registration.md) with trading scopes, expiry, and IP whitelist settings.
## 2. Minimal configuration
Add these values to the project-root `.env` file:
```dotenv
EXCHANGE=aster
ASTER_API_KEY=<your_aster_api_key>
ASTER_API_SECRET=<your_aster_api_secret>
ASTER_SYMBOL=BTCUSDT
```
`ASTER_SYMBOL` takes priority over the shared `TRADE_SYMBOL`. The default is `BTCUSDT`.
## 3. Precision and strategy values
Aster returns market precision metadata. Keep the strategy values aligned with the selected market:
```dotenv
PRICE_TICK=0.1
QTY_STEP=0.001
```
Confirm the price increment, quantity increment, and minimum notional in Aster's market rules. Configure `TRADE_AMOUNT`, stop-loss values, and maker settings after a small-account validation run.
## 4. Environment behavior
The current Aster adapter uses production REST and WebSocket endpoints. It exposes no environment switch or custom endpoint variables. Aster testnet credentials cannot authenticate against these production endpoints. Use a dedicated low-balance account and ritmex-bot `--dry-run` write simulation for strategy checks.
## 5. Verify the configuration
Run the local configuration check:
```bash
bun run index.ts doctor --exchange aster --symbol BTCUSDT --json
```
Then run a read-only market connection check:
```bash
bun run index.ts market ticker --exchange aster --symbol BTCUSDT --json
```
These commands create no orders. Run an order command with `--dry-run` before starting a live strategy.
## Troubleshooting
- `Missing ASTER_API_KEY`: fill both Aster credential variables.
- `Invalid signature`: synchronize system time and verify the secret, permissions, and IP whitelist.
- `Symbol not found`: use the native Aster perpetual symbol, such as `BTCUSDT`.
- Precision errors: update `PRICE_TICK`, `QTY_STEP`, and the order quantity from the market rules.
## Security
- Grant read and trading scopes only.
- Keep the API secret in the local runtime environment.
- Delete and replace a credential immediately after exposure.
## References
- [Aster Futures API](https://github.com/asterdex/api-docs)
- [Repository Aster API reference](../aster/v2-api.md)
docs/exchanges/aster.md
+80
View File
@@ -0,0 +1,80 @@
# Aster 配置教程
English version: [Aster Configuration Guide](aster.en.md)
## 适用范围
本教程用于配置 ritmex-bot 的 Aster USDT 永续适配器。当前适配器连接 Aster 生产环境的 `https://fapi.asterdex.com`，交易对使用 `BTCUSDT` 这类连续大写格式。
## 1. 准备账户与 API 凭证
1. 在 [Aster](https://www.asterdex.com/zh-CN/referral/4665f3) 完成钱包连接、永续账户开通和入金。
2. 在 Aster API 管理页面创建 API Key，保存页面显示的 API Key 与 API Secret。
3. 开启读取和永续交易权限，关闭提现权限。
4. 为运行机器配置固定 IP 白名单。
5. 将账户持仓模式设置为单向持仓，并在交易所界面设置所需杠杆。
Aster 官方还提供[程序化 API Key 注册说明](https://github.com/asterdex/api-docs/blob/master/demo/aster-api-key-registration.md)。该流程支持交易权限、到期时间和 IP 白名单配置。
## 2. 最小配置
在项目根目录的 `.env` 中填写：
```dotenv
EXCHANGE=aster
ASTER_API_KEY=<your_aster_api_key>
ASTER_API_SECRET=<your_aster_api_secret>
ASTER_SYMBOL=BTCUSDT
```
`ASTER_SYMBOL` 优先于通用的 `TRADE_SYMBOL`。未设置时默认使用 `BTCUSDT`。
## 3. 精度与策略参数
Aster 会返回市场精度，策略配置仍需与目标市场保持一致：
```dotenv
PRICE_TICK=0.1
QTY_STEP=0.001
```
通过 Aster 市场规则确认价格步长、数量步长和最小名义价值。`TRADE_AMOUNT`、止损和做市参数属于策略配置，应在小额验证后设置。
## 4. 环境说明
当前 Aster 适配器没有环境切换变量，也没有自定义 REST/WebSocket 端点变量。Aster 测试网凭证无法用于当前生产端点。测试策略时使用专用小额账户和 ritmex-bot 的 `--dry-run` 写操作模拟。
## 5. 验证配置
先执行本地配置检查：
```bash
bun run index.ts doctor --exchange aster --symbol BTCUSDT --json
```
再执行只读行情连接检查：
```bash
bun run index.ts market ticker --exchange aster --symbol BTCUSDT --json
```
以上命令不会创建订单。启动真实策略前，先用命令模式执行带 `--dry-run` 的订单路由检查。
## 常见问题
- `Missing ASTER_API_KEY`：确认两个 Aster 凭证变量均已填写。
- `Invalid signature`：同步系统时间，检查 API Secret、权限和 IP 白名单。
- `Symbol not found`：使用 Aster 永续市场的原始符号，例如 `BTCUSDT`。
- 精度错误：从市场规则更新 `PRICE_TICK`、`QTY_STEP` 和下单数量。
## 安全要求
- API Key 仅授予读取和交易权限。
- API Secret 只保存在本机运行环境中。
- 凭证泄露后立即删除旧 Key 并创建新 Key。
## 参考资料
- [Aster Futures API](https://github.com/asterdex/api-docs)
- [仓库内 Aster API 参考](../aster/v2-api.md)
docs/exchanges/backpack.en.md
+73
View File
@@ -0,0 +1,73 @@
# Backpack Configuration Guide
中文版：[Backpack 配置教程](backpack.md)
## Scope
This guide configures the Backpack Spot and USDC perpetual adapter. Backpack API authentication uses an Ed25519 keypair: the API key is the verifying public key, and the API secret is the signing private key.
## 1. Create an API key
1. Complete account activation, trading access, and funding on [Backpack Exchange](https://backpack.exchange/join/ritmex).
2. Create a dedicated trading key from the API Keys section in account settings.
3. Save the API key and API secret immediately after creation.
4. Enable read and trading access. Keep withdrawal access disabled.
5. Configure the IP whitelist and target subaccount.
## 2. Minimal perpetual configuration
```dotenv
EXCHANGE=backpack
BACKPACK_API_KEY=<your_backpack_api_key>
BACKPACK_API_SECRET=<your_backpack_api_secret>
BACKPACK_SYMBOL=BTC_USDC_PERP
```
`BTC_USDC_PERP` is Backpack's native perpetual market ID. The adapter also matches the CCXT unified symbol `BTC/USDC:USDC`. Set the `_PERP` symbol explicitly so the matching Spot market is not selected.
## 3. Spot configuration
```dotenv
BACKPACK_SYMBOL=BTC_USDC
```
Spot mode also accepts the CCXT unified symbol `BTC/USDC`.
## 4. Optional settings
| Variable | Default | Purpose |
| --- | --- | --- |
| `BACKPACK_PASSWORD` | Empty | Set only when the credential flow supplies a passphrase |
| `BACKPACK_SUBACCOUNT` | Main account | Target subaccount ID |
| `BACKPACK_WS_WINDOW` | `5000` | Signed-request validity window in milliseconds; official maximum is 60000 |
| `BACKPACK_DEBUG` | `false` | Market-resolution and WebSocket debug output |
| `BACKPACK_SANDBOX` | `false` | Sandbox flag forwarded to CCXT |
The installed CCXT Backpack adapter exposes production API URLs only, and this repository has no Backpack endpoint override variables. `BACKPACK_SANDBOX=true` does not create a documented isolated test environment. Use `--dry-run` for write-operation simulation.
## 5. Verify the configuration
```bash
bun run index.ts doctor --exchange backpack --symbol BTC_USDC_PERP --json
bun run index.ts market ticker --exchange backpack --symbol BTC_USDC_PERP --json
```
These commands create no orders. The ticker check loads Backpack markets and confirms symbol resolution.
## Troubleshooting
- `BACKPACK_API_KEY and BACKPACK_API_SECRET ... required`: provide the complete Ed25519 credential pair.
- `Symbol ... not found in Backpack markets`: use `BTC_USDC_PERP` for perpetuals or `BTC_USDC` for Spot.
- Signature failures: verify that the API key and secret form one pair and synchronize the host clock.
- Empty subaccount balance: confirm that `BACKPACK_SUBACCOUNT` matches the account authorized for the key.
## Security
- The API secret is an Ed25519 private key. Protect it as a trading private key.
- Grant read and trading scopes only.
- Delete the key and create a new pair immediately after exposure.
## References
- [Backpack Exchange API](https://docs.backpack.exchange/)
- [Repository Backpack OpenAPI](../backpack/openapi.json)
docs/exchanges/backpack.md
+73
View File
@@ -0,0 +1,73 @@
# Backpack 配置教程
English version: [Backpack Configuration Guide](backpack.en.md)
## 适用范围
本教程用于 Backpack 现货和 USDC 永续适配器。Backpack API 使用 Ed25519 密钥对：API Key 是验证公钥，API Secret 是签名私钥。
## 1. 创建 API Key
1. 在 [Backpack Exchange](https://backpack.exchange/join/ritmex) 完成账户、交易权限和入金设置。
2. 在账户设置的 API Keys 页面创建专用交易 Key。
3. 创建后立即保存 API Key 和 API Secret。
4. 开启读取和交易权限，关闭提现权限。
5. 配置 IP 白名单和目标子账户。
## 2. 永续最小配置
```dotenv
EXCHANGE=backpack
BACKPACK_API_KEY=<your_backpack_api_key>
BACKPACK_API_SECRET=<your_backpack_api_secret>
BACKPACK_SYMBOL=BTC_USDC_PERP
```
`BTC_USDC_PERP` 是 Backpack 原始永续 market ID。适配器也能匹配 CCXT 统一符号 `BTC/USDC:USDC`。应显式设置 `_PERP` 符号，避免同名现货市场被选中。
## 3. 现货配置
```dotenv
BACKPACK_SYMBOL=BTC_USDC
```
现货也可使用 CCXT 统一符号 `BTC/USDC`。
## 4. 可选配置
| 变量 | 默认值 | 说明 |
| --- | --- | --- |
| `BACKPACK_PASSWORD` | 空 | 仅在凭证流程提供 passphrase 时填写 |
| `BACKPACK_SUBACCOUNT` | 主账户 | 目标子账户 ID |
| `BACKPACK_WS_WINDOW` | `5000` | 签名请求有效窗口，单位毫秒，官方最大值为 60000 |
| `BACKPACK_DEBUG` | `false` | 输出市场解析和 WebSocket 调试日志 |
| `BACKPACK_SANDBOX` | `false` | 传递给 CCXT 的 sandbox 标志 |
当前安装的 CCXT Backpack 适配器只公开生产 API 地址，仓库也没有 Backpack 自定义端点变量。`BACKPACK_SANDBOX=true` 不构成独立的已文档化测试环境。测试写操作时使用 `--dry-run`。
## 5. 验证配置
```bash
bun run index.ts doctor --exchange backpack --symbol BTC_USDC_PERP --json
bun run index.ts market ticker --exchange backpack --symbol BTC_USDC_PERP --json
```
以上命令不会创建订单。行情检查会加载 Backpack 市场列表并确认符号解析。
## 常见问题
- `BACKPACK_API_KEY and BACKPACK_API_SECRET ... required`：填写完整 Ed25519 凭证对。
- `Symbol ... not found in Backpack markets`：永续使用 `BTC_USDC_PERP`，现货使用 `BTC_USDC`。
- 签名失败：检查 API Key/Secret 是否属于同一密钥对，并同步系统时间。
- 子账户余额为空：确认 `BACKPACK_SUBACCOUNT` 与创建 Key 时授权的账户一致。
## 安全要求
- API Secret 是 Ed25519 私钥，应按交易私钥保护。
- Key 仅授予读取和交易权限。
- Secret 泄露后立即删除 Key 并创建新密钥对。
## 参考资料
- [Backpack Exchange API](https://docs.backpack.exchange/)
- [仓库内 Backpack OpenAPI](../backpack/openapi.json)
docs/exchanges/binance.en.md
+105
View File
@@ -0,0 +1,105 @@
# Binance Configuration Guide
中文版：[Binance 配置教程](binance.md)
## Scope
The ritmex-bot Binance adapter supports Spot and USDⓈ-M perpetual markets. `BINANCE_MARKET_TYPE` selects the market class, and symbol suffixes can force Spot or perpetual resolution.
## 1. Create an API key
1. Create a dedicated key in [Binance API Management](https://www.binance.com/en/my/settings/api-management).
2. Enable read access.
3. Enable Futures permission for perpetual strategies or Spot Trading permission for Spot strategies.
4. Keep withdrawal permission disabled and add a fixed IP whitelist.
5. Use one-way position mode for USDⓈ-M Futures and configure leverage in the Binance interface.
Mainnet and testnet keys are separate. Follow the [official Spot Testnet guide](https://developers.binance.com/docs/binance-spot-api-docs/testnet) to create Spot credentials. Use Binance Futures Testnet credentials for USDⓈ-M testnet trading.
## 2. Minimal perpetual configuration
```dotenv
EXCHANGE=binance
BINANCE_API_KEY=<your_binance_api_key>
BINANCE_API_SECRET=<your_binance_api_secret>
BINANCE_MARKET_TYPE=perp
BINANCE_SYMBOL=BTCUSDT_PERP
```
`BTCUSDT_PERP` forces perpetual resolution. `BTCUSDT` with `BINANCE_MARKET_TYPE=perp` also selects the perpetual market.
## 3. Minimal Spot configuration
```dotenv
EXCHANGE=binance
BINANCE_API_KEY=<your_binance_api_key>
BINANCE_API_SECRET=<your_binance_api_secret>
BINANCE_MARKET_TYPE=spot
BINANCE_SYMBOL=BTCUSDT_SPOT
```
Spot mode also accepts `BINANCE_SYMBOL=BTCUSDT`. Spot markets have no perpetual positions, funding rates, or derivatives-only protective-order features.
## 4. Market modes and symbols
| Setting | Meaning |
| --- | --- |
| `BINANCE_MARKET_TYPE=perp` | Default mode; prefers USDⓈ-M perpetuals |
| `BINANCE_MARKET_TYPE=spot` | Spot mode |
| `BINANCE_MARKET_TYPE=auto` | Resolves by symbol and applies default selection to duplicate names |
| `BTCUSDT_PERP` | Forces the perpetual market |
| `BTCUSDT_SPOT` | Forces the Spot market |
Use explicit legs for basis arbitrage:
```dotenv
BASIS_FUTURES_SYMBOL=BTCUSDT_PERP
BASIS_SPOT_SYMBOL=BTCUSDT_SPOT
```
## 5. Testnet configuration
`BINANCE_SANDBOX=true` switches the CCXT REST clients. The adapter manages native WebSocket URLs separately, so a complete testnet setup defines both REST and WebSocket endpoints:
```dotenv
BINANCE_SANDBOX=true
BINANCE_SPOT_REST_URL=https://testnet.binance.vision
BINANCE_SPOT_WS_URL=wss://stream.testnet.binance.vision/ws
BINANCE_FUTURES_REST_URL=https://testnet.binancefuture.com
BINANCE_FUTURES_WS_URL=wss://fstream.binancefuture.com
```
Use API keys generated by the matching testnet.
## 6. Optional settings
| Variable | Default | Purpose |
| --- | --- | --- |
| `BINANCE_ACCOUNT_POLL_MS` | `5000` | Account REST reconciliation interval; minimum 1000 ms |
| `BINANCE_ORDERS_POLL_MS` | `3000` | Order REST reconciliation interval; minimum 1000 ms |
| `BINANCE_SPOT_REST_URL` | `https://api.binance.com` | Spot REST base URL |
| `BINANCE_FUTURES_REST_URL` | `https://fapi.binance.com` | Perpetual REST base URL |
| `BINANCE_SPOT_WS_URL` | `wss://stream.binance.com:9443/ws` | Spot WebSocket base URL |
| `BINANCE_FUTURES_WS_URL` | `wss://fstream.binance.com/ws` | Perpetual WebSocket base URL |
## 7. Verify the configuration
```bash
bun run index.ts doctor --exchange binance --symbol BTCUSDT_PERP --json
bun run index.ts market ticker --exchange binance --symbol BTCUSDT_PERP --json
```
These commands create no orders. Run an order command with `--dry-run` before starting a live strategy.
## Troubleshooting
- `Invalid API-key, IP, or permissions`: verify market permissions, IP restrictions, and the mainnet/testnet key source.
- `Binance symbol not found`: use `BTCUSDT_PERP` or `BTCUSDT_SPOT` to select the market explicitly.
- `Position side does not match`: switch the USDⓈ-M Futures account to one-way mode.
- Timestamp errors: synchronize the host clock.
## References
- [Binance Spot API](https://developers.binance.com/docs/binance-spot-api-docs)
- [Binance USDⓈ-M Futures API](https://developers.binance.com/docs/derivatives/usds-margined-futures)
- [Repository Binance API reference](../binance/binance-spot/README.md)
docs/exchanges/binance.md
+105
View File
@@ -0,0 +1,105 @@
# Binance 配置教程
English version: [Binance Configuration Guide](binance.en.md)
## 适用范围
ritmex-bot 的 Binance 适配器支持现货和 USDⓈ-M 永续。`BINANCE_MARKET_TYPE` 决定市场类型，交易对后缀可以显式指定现货或永续。
## 1. 创建 API Key
1. 在 [Binance API Management](https://www.binance.com/en/my/settings/api-management) 创建专用 API Key。
2. 开启读取权限。
3. 永续策略开启 Futures 权限；现货策略开启 Spot Trading 权限。
4. 关闭提现权限并配置固定 IP 白名单。
5. 永续账户使用单向持仓模式，并在交易所界面设置杠杆。
主网 Key 与测试网 Key 相互独立。Spot Testnet 按[官方测试网指南](https://developers.binance.com/docs/binance-spot-api-docs/testnet)创建凭证；USDⓈ-M Futures Testnet 使用 Binance Futures Testnet 凭证。
## 2. 永续最小配置
```dotenv
EXCHANGE=binance
BINANCE_API_KEY=<your_binance_api_key>
BINANCE_API_SECRET=<your_binance_api_secret>
BINANCE_MARKET_TYPE=perp
BINANCE_SYMBOL=BTCUSDT_PERP
```
`BTCUSDT_PERP` 强制选择永续市场。`BTCUSDT` 配合 `BINANCE_MARKET_TYPE=perp` 也会选择永续。
## 3. 现货最小配置
```dotenv
EXCHANGE=binance
BINANCE_API_KEY=<your_binance_api_key>
BINANCE_API_SECRET=<your_binance_api_secret>
BINANCE_MARKET_TYPE=spot
BINANCE_SYMBOL=BTCUSDT_SPOT
```
现货也可使用 `BINANCE_SYMBOL=BTCUSDT`。现货模式不提供永续专属的持仓、资金费率和部分保护单能力。
## 4. 市场模式与符号
| 配置 | 含义 |
| --- | --- |
| `BINANCE_MARKET_TYPE=perp` | 默认模式，优先 USDⓈ-M 永续 |
| `BINANCE_MARKET_TYPE=spot` | 现货模式 |
| `BINANCE_MARKET_TYPE=auto` | 根据符号匹配市场，同名市场由默认逻辑选择 |
| `BTCUSDT_PERP` | 强制永续 |
| `BTCUSDT_SPOT` | 强制现货 |
期现套利使用显式拆分交易对：
```dotenv
BASIS_FUTURES_SYMBOL=BTCUSDT_PERP
BASIS_SPOT_SYMBOL=BTCUSDT_SPOT
```
## 5. 测试网配置
`BINANCE_SANDBOX=true` 会切换 CCXT REST 客户端。适配器的原生 WebSocket 地址由独立变量控制，完整测试网配置应同时设置 REST 与 WebSocket 地址：
```dotenv
BINANCE_SANDBOX=true
BINANCE_SPOT_REST_URL=https://testnet.binance.vision
BINANCE_SPOT_WS_URL=wss://stream.testnet.binance.vision/ws
BINANCE_FUTURES_REST_URL=https://testnet.binancefuture.com
BINANCE_FUTURES_WS_URL=wss://fstream.binancefuture.com
```
测试网配置必须使用对应测试网生成的 API Key。
## 6. 其他可选配置
| 变量 | 默认值 | 说明 |
| --- | --- | --- |
| `BINANCE_ACCOUNT_POLL_MS` | `5000` | 账户 REST 校准间隔，最小 1000 ms |
| `BINANCE_ORDERS_POLL_MS` | `3000` | 订单 REST 校准间隔，最小 1000 ms |
| `BINANCE_SPOT_REST_URL` | `https://api.binance.com` | 现货 REST 地址 |
| `BINANCE_FUTURES_REST_URL` | `https://fapi.binance.com` | 永续 REST 地址 |
| `BINANCE_SPOT_WS_URL` | `wss://stream.binance.com:9443/ws` | 现货 WebSocket 地址 |
| `BINANCE_FUTURES_WS_URL` | `wss://fstream.binance.com/ws` | 永续 WebSocket 地址 |
## 7. 验证配置
```bash
bun run index.ts doctor --exchange binance --symbol BTCUSDT_PERP --json
bun run index.ts market ticker --exchange binance --symbol BTCUSDT_PERP --json
```
以上命令不会创建订单。真实策略启动前，先使用带 `--dry-run` 的订单命令检查下单参数。
## 常见问题
- `Invalid API-key, IP, or permissions`：检查市场权限、IP 白名单和主网/测试网 Key。
- `Binance symbol not found`：使用 `BTCUSDT_PERP` 或 `BTCUSDT_SPOT` 明确市场。
- `Position side does not match`：将 USDⓈ-M Futures 账户切换为单向持仓模式。
- 时间戳错误：同步运行机器时间。
## 参考资料
- [Binance Spot API](https://developers.binance.com/docs/binance-spot-api-docs)
- [Binance USDⓈ-M Futures API](https://developers.binance.com/docs/derivatives/usds-margined-futures)
- [仓库内 Binance API 参考](../binance/binance-spot/README.md)
docs/exchanges/grvt.en.md
+93
View File
@@ -0,0 +1,93 @@
# GRVT Configuration Guide
中文版：[GRVT 配置教程](grvt.md)
## Scope
This guide configures the GRVT perpetual adapter. The standard authentication path uses an API key to create a session and an API secret to sign orders with EIP-712. GRVT's API instrument and the ritmex-bot display symbol are separate settings.
## 1. Collect the account values and credentials
1. Activate an account and subaccount on [GRVT](https://grvt.io/exchange/sign-up?ref=sea).
2. Create trading credentials from the API Keys section in account settings.
3. Save the API key and its signing secret.
4. Record the numeric ID of the target subaccount.
5. Read the exact instrument name from the GRVT market list or the `all_instruments` endpoint.
The standard BTC perpetual instrument is `BTC_USDT_Perp`. Instrument names preserve GRVT's capitalization and separators.
## 2. Minimal configuration
```dotenv
EXCHANGE=grvt
GRVT_ENV=prod
GRVT_API_KEY=<your_grvt_api_key>
GRVT_API_SECRET=<your_grvt_signing_secret>
GRVT_SUB_ACCOUNT_ID=<your_sub_account_id>
GRVT_INSTRUMENT=BTC_USDT_Perp
GRVT_SYMBOL=BTCUSDT
```
`GRVT_INSTRUMENT` is required by the current adapter. `GRVT_SYMBOL` controls ritmex-bot display values and unified position mapping. When omitted, the adapter derives it by removing `_` and `-` from the instrument.
## 3. Select an environment
| `GRVT_ENV` | Purpose |
| --- | --- |
| `prod` | Production |
| `testnet` | Public test environment |
| `staging` | GRVT staging environment |
| `dev` | GRVT development environment |
`mainnet` and `production` resolve to `prod`. The API key, secret, and subaccount ID must belong to the same environment.
Testnet example:
```dotenv
GRVT_ENV=testnet
GRVT_INSTRUMENT=BTC_USDT_Perp
GRVT_SYMBOL=BTCUSDT
```
## 4. Reuse an existing session
Advanced deployments can provide:
```dotenv
GRVT_COOKIE=<existing_session_cookie>
GRVT_ACCOUNT_ID=<existing_account_id>
```
These two values bypass API-key login. Order signing still requires `GRVT_API_SECRET` or an external signer configured through `GRVT_SIGNER_PATH`.
`GRVT_SIGNER_PATH` is designed for deployments that maintain their own signing service. The module must export a signing function that returns the GRVT order-signature fields.
## 5. Verify the configuration
```bash
bun run index.ts doctor --exchange grvt --symbol BTCUSDT --json
bun run index.ts market ticker --exchange grvt --symbol BTCUSDT --json
```
These commands create no orders. The ticker check validates the environment, session login, and instrument metadata.
## Troubleshooting
- `Missing GRVT_INSTRUMENT`: provide the complete instrument, such as `BTC_USDT_Perp`.
- `Failed to authenticate with GRVT using API key`: verify the environment, API key, and subaccount ownership.
- `GRVT_API_SECRET is not configured for local signing`: provide the signing secret or configure an external signer.
- `Unable to load GRVT instrument metadata`: verify the instrument spelling and `GRVT_ENV`.
- Expired signatures: synchronize the host clock.
## Security
- Use dedicated trading credentials for the API key and signing secret.
- Protect the session cookie as an account-access credential.
- Restrict file permissions and callers for an external signer module.
## References
- [GRVT API Documentation](https://api-docs.grvt.io/)
- [GRVT Trading Streams and Authentication](https://api-docs.grvt.io/trading_streams)
- [Repository GRVT SDK reference](../grvt/sdk-readme.md)
docs/exchanges/grvt.md
+93
View File
@@ -0,0 +1,93 @@
# GRVT 配置教程
English version: [GRVT Configuration Guide](grvt.en.md)
## 适用范围
本教程用于 GRVT 永续适配器。标准认证路径使用 API Key 登录会话，并使用 API Secret 对订单执行 EIP-712 签名。GRVT 的 API instrument 与 ritmex-bot 展示符号是两个独立配置项。
## 1. 获取账户信息与凭证
1. 在 [GRVT](https://grvt.io/exchange/sign-up?ref=sea) 完成账户和子账户开通。
2. 在账户设置的 API Key 页面创建交易凭证。
3. 保存 API Key 和配套的签名 Secret。
4. 记录目标子账户的数字 ID。
5. 从 GRVT 市场或 `all_instruments` 接口确认完整 instrument 名称。
BTC 永续的标准 instrument 为 `BTC_USDT_Perp`。instrument 区分大小写和分隔符，应使用 GRVT 返回的原始值。
## 2. 最小配置
```dotenv
EXCHANGE=grvt
GRVT_ENV=prod
GRVT_API_KEY=<your_grvt_api_key>
GRVT_API_SECRET=<your_grvt_signing_secret>
GRVT_SUB_ACCOUNT_ID=<your_sub_account_id>
GRVT_INSTRUMENT=BTC_USDT_Perp
GRVT_SYMBOL=BTCUSDT
```
`GRVT_INSTRUMENT` 是当前适配器的必填项。`GRVT_SYMBOL` 用于 ritmex-bot 内部展示和统一仓位映射；省略时会从 instrument 去除 `_` 和 `-` 后生成。
## 3. 环境选择
| `GRVT_ENV` | 用途 |
| --- | --- |
| `prod` | 生产环境 |
| `testnet` | 公共测试环境 |
| `staging` | GRVT staging 环境 |
| `dev` | GRVT development 环境 |
`mainnet` 和 `production` 会解析为 `prod`。API Key、Secret 和子账户 ID 必须属于同一环境。
测试网示例：
```dotenv
GRVT_ENV=testnet
GRVT_INSTRUMENT=BTC_USDT_Perp
GRVT_SYMBOL=BTCUSDT
```
## 4. 复用现有会话
高级部署可以提供：
```dotenv
GRVT_COOKIE=<existing_session_cookie>
GRVT_ACCOUNT_ID=<existing_account_id>
```
这两个变量会跳过 API Key 登录。订单签名仍需要 `GRVT_API_SECRET` 或 `GRVT_SIGNER_PATH` 指向的外部签名模块。
`GRVT_SIGNER_PATH` 适用于自行维护签名服务的部署。模块需要导出签名函数，并返回 GRVT 订单签名字段。
## 5. 验证配置
```bash
bun run index.ts doctor --exchange grvt --symbol BTCUSDT --json
bun run index.ts market ticker --exchange grvt --symbol BTCUSDT --json
```
以上命令不会创建订单。行情检查会验证环境、登录会话和 instrument 元数据。
## 常见问题
- `Missing GRVT_INSTRUMENT`：填写完整 instrument，例如 `BTC_USDT_Perp`。
- `Failed to authenticate with GRVT using API key`：检查环境、API Key 和子账户归属。
- `GRVT_API_SECRET is not configured for local signing`：填写签名 Secret 或配置外部 signer。
- `Unable to load GRVT instrument metadata`：检查 instrument 拼写和 `GRVT_ENV`。
- 签名过期：同步运行机器时间。
## 安全要求
- API Key 和签名 Secret 应使用专用交易凭证。
- 会话 Cookie 具备账户访问能力，应按敏感凭证保护。
- 外部 signer 模块应限制文件权限和调用来源。
## 参考资料
- [GRVT API Documentation](https://api-docs.grvt.io/)
- [GRVT Trading Streams and Authentication](https://api-docs.grvt.io/trading_streams)
- [仓库内 GRVT SDK 参考](../grvt/sdk-readme.md)
docs/exchanges/lighter.en.md
+98
View File
@@ -0,0 +1,98 @@
# Lighter Configuration Guide
中文版：[Lighter 配置教程](lighter.md)
## Scope
This guide configures Lighter perpetuals and the integrated Spot markets. Lighter credentials consist of an account index, an API-key index, and an API private key. All three values must belong to the same network and account.
## 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` |
The current default is `testnet`. Set `LIGHTER_ENV=mainnet` explicitly for production trading.
## 2. Obtain the account index and API key
1. Create and fund an account on [Lighter](https://app.lighter.xyz/?referral=111909FA).
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`.
User-created API-key indices range from `2` to `254`. Indices `0` and `1` are reserved for Web/mobile clients, and `255` queries all keys. ritmex-bot defaults to index `0`, so a user-created key needs an explicit matching index.
## 3. Minimal testnet configuration
```dotenv
EXCHANGE=lighter
LIGHTER_ENV=testnet
LIGHTER_ACCOUNT_INDEX=<your_account_index>
LIGHTER_API_KEY_INDEX=<your_api_key_index>
LIGHTER_API_PRIVATE_KEY=<your_api_private_key_hex>
LIGHTER_SYMBOL=BTC
```
Lighter perpetual markets use symbols such as `BTC`, `ETH`, and `SOL`. The adapter resolves the market ID and precision from metadata for the selected network.
## 4. Mainnet configuration
Replace the values with credentials generated for the mainnet account:
```dotenv
LIGHTER_ENV=mainnet
LIGHTER_ACCOUNT_INDEX=<your_mainnet_account_index>
LIGHTER_API_KEY_INDEX=<your_mainnet_api_key_index>
LIGHTER_API_PRIVATE_KEY=<your_mainnet_api_private_key_hex>
LIGHTER_SYMBOL=BTC
```
Testnet and mainnet credentials cannot be mixed.
## 5. Optional settings
| Variable | Purpose |
| --- | --- |
| `LIGHTER_BASE_URL` | Overrides the REST URL; known hostnames also determine the network |
| `LIGHTER_L1_ADDRESS` | L1 address associated with the account |
| `LIGHTER_MARKET_ID` | Forces a market ID when metadata resolution fails |
| `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_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.
## 6. Verify the configuration
```bash
bun run index.ts doctor --exchange lighter --symbol BTC --json
bun run index.ts market ticker --exchange lighter --symbol BTC --json
```
The ticker check loads market metadata, validates the account/API-key pair, and opens WebSocket connections. It creates no orders.
## Troubleshooting
- `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.
- 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
- The API private key can sign transactions. Use a dedicated key and restrictive file permissions.
- Keep public-key/index records separately and store the private key only in the runtime environment.
- Revoke the affected index and create a new key after exposure.
## References
- [Lighter Get Started](https://apidocs.lighter.xyz/docs/get-started)
- [Lighter API Keys](https://apidocs.lighter.xyz/docs/api-keys)
- [Repository Lighter introduction](../lighter/get-start.md)
docs/exchanges/lighter.md
+98
View File
@@ -0,0 +1,98 @@
# Lighter 配置教程
English version: [Lighter Configuration Guide](lighter.en.md)
## 适用范围
本教程用于 Lighter 永续和已接入现货市场。Lighter 凭证由账户索引、API Key 索引和 API 私钥组成，三者必须属于同一网络和同一账户。
## 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` |
当前默认值为 `testnet`。生产交易应显式设置 `LIGHTER_ENV=mainnet`。
## 2. 获取账户索引和 API Key
1. 在 [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`。
用户创建的 API Key 索引范围为 `2`–`254`。`0` 和 `1` 由 Web/移动端保留，`255` 用于查询全部 Key。ritmex-bot 代码默认索引为 `0`，用户创建的 Key 应显式填写真实索引。
## 3. 最小测试网配置
```dotenv
EXCHANGE=lighter
LIGHTER_ENV=testnet
LIGHTER_ACCOUNT_INDEX=<your_account_index>
LIGHTER_API_KEY_INDEX=<your_api_key_index>
LIGHTER_API_PRIVATE_KEY=<your_api_private_key_hex>
LIGHTER_SYMBOL=BTC
```
Lighter 永续市场使用 `BTC`、`ETH`、`SOL` 这类市场符号。适配器会从目标网络的市场元数据自动解析 market ID 和精度。
## 4. 主网配置
将同一组变量替换为主网账户生成的值：
```dotenv
LIGHTER_ENV=mainnet
LIGHTER_ACCOUNT_INDEX=<your_mainnet_account_index>
LIGHTER_API_KEY_INDEX=<your_mainnet_api_key_index>
LIGHTER_API_PRIVATE_KEY=<your_mainnet_api_private_key_hex>
LIGHTER_SYMBOL=BTC
```
测试网和主网凭证不可混用。
## 5. 可选配置
| 变量 | 说明 |
| --- | --- |
| `LIGHTER_BASE_URL` | 覆盖 REST 地址；网络可从已知主机名推断 |
| `LIGHTER_L1_ADDRESS` | 账户关联的 L1 地址 |
| `LIGHTER_MARKET_ID` | 强制 market ID；仅在自动解析失败时设置 |
| `LIGHTER_MARKET_TYPE` | `perp` 或 `spot` |
| `LIGHTER_PRICE_DECIMALS` | 强制价格小数位 |
| `LIGHTER_SIZE_DECIMALS` | 强制数量小数位 |
| `LIGHTER_CHAIN_ID` | 覆盖签名 Chain ID |
| `LIGHTER_DEBUG` | 设置为 `1` 或 `true` 输出调试日志 |
现货市场使用 `ETH/USDC` 这类符号。显式 market ID、价格小数位和数量小数位必须与目标网络的 order book 元数据一致。
## 6. 验证配置
```bash
bun run index.ts doctor --exchange lighter --symbol BTC --json
bun run index.ts market ticker --exchange lighter --symbol BTC --json
```
行情检查会加载市场元数据、校验账户/API Key 对并建立 WebSocket，不会创建订单。
## 常见问题
- `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。
- signer 加载失败：仓库预置 macOS arm64 与 Linux amd64 签名库，其他平台需要构建兼容签名库或使用受支持的 WSL/Linux 环境。
## 安全要求
- API 私钥可以签署交易，应使用独立 Key 并限制文件权限。
- 保留 API 公钥和索引记录，私钥只存放在运行环境中。
- Key 泄露后在 Lighter 撤销对应索引并创建新 Key。
## 参考资料
- [Lighter Get Started](https://apidocs.lighter.xyz/docs/get-started)
- [Lighter API Keys](https://apidocs.lighter.xyz/docs/api-keys)
- [仓库内 Lighter 入门参考](../lighter/get-start.md)
docs/exchanges/nado.en.md
+100
View File
@@ -0,0 +1,100 @@
# Nado Configuration Guide
中文版：[Nado 配置教程](nado.md)
## Scope
This guide configures the Nado perpetual adapter. Nado uses the Ink network, subaccounts, and linked signers. ritmex-bot requires the private key of an authorized linked signer, the subaccount owner address, and the subaccount name.
## 1. Prepare the Nado account
1. Connect an EVM wallet on [Nado](https://app.nado.xyz?join=LKbIUs5).
2. Fund the Ink network with ETH for gas and a supported collateral asset.
3. Deposit collateral and create the target subaccount.
4. Record the subaccount owner's EVM address and subaccount name. The common default name is `default`.
## 2. Obtain the linked-signer private key
The official Nado SDK provides `createStandardLinkedSigner` and `createDeterministicLinkedSignerPrivateKey` for creating and authorizing a subaccount linked signer.
The current Nado Web UI stores authorized signer information in browser local storage under the official domain. After creating the signer through the Web UI, inspect `Application` → `Local Storage` → `nado.userSettings` in browser developer tools and read the `privateKey` field. This value is a trading private key. Close developer tools and remove temporary records after retrieval.
`NADO_SIGNER_PRIVATE_KEY` must contain `0x` followed by 64 hexadecimal characters. It must be the linked-signer key. Do not place a wallet seed phrase or primary wallet private key in this variable.
## 3. Minimal mainnet configuration
```dotenv
EXCHANGE=nado
NADO_ENV=inkMainnet
NADO_SIGNER_PRIVATE_KEY=<0x_linked_signer_private_key>
NADO_SUBACCOUNT_OWNER=<0x_owner_address>
NADO_SUBACCOUNT_NAME=default
NADO_SYMBOL=BTC-PERP
```
`NADO_EVM_ADDRESS` is a compatible alias for `NADO_SUBACCOUNT_OWNER`.
## 4. Testnet configuration
```dotenv
NADO_ENV=inkTestnet
NADO_SIGNER_PRIVATE_KEY=<0x_testnet_linked_signer_private_key>
NADO_SUBACCOUNT_OWNER=<0x_testnet_owner_address>
NADO_SUBACCOUNT_NAME=default
NADO_SYMBOL=BTC-PERP
```
Linked-signer authorization is environment-specific. A mainnet signer cannot authorize a testnet subaccount.
## 5. Symbol format
Nado perpetual markets use product symbols such as `BTC-PERP` and `ETH-PERP`. The adapter also accepts:
- `BTCPERP` → `BTC-PERP`
- `BTCUSDT0` → `BTC-PERP`
- `BTC/PERP` → `BTC-PERP`
Prefer the native `*-PERP` symbol returned by the Nado API.
## 6. Optional settings
| Variable | Default | Purpose |
| --- | --- | --- |
| `NADO_GATEWAY_WS_URL` | Selected by environment | Trading gateway WebSocket |
| `NADO_SUBSCRIPTIONS_WS_URL` | Selected by environment | Market subscription WebSocket |
| `NADO_ARCHIVE_URL` | Production/test archive | History and indexer endpoint |
| `NADO_TRIGGER_URL` | Production/test trigger | Stop-loss and take-profit service |
| `NADO_MARKET_SLIPPAGE_PCT` | `0.01` | Market/trigger protection range; `0.01` means 1% |
| `NADO_STOP_TRIGGER_SOURCE` | `oracle` | `oracle`, `last`, or `mid` |
| `NADO_MIN_SIZE_POLICY` | `adjust` | `adjust` raises to minimum size; `reject` rejects the order |
| `NADO_DEBUG` | `false` | Detailed error logging |
## 7. Verify the configuration
```bash
bun run index.ts doctor --exchange nado --symbol BTC-PERP --json
bun run index.ts market ticker --exchange nado --symbol BTC-PERP --json
```
The ticker check validates the network, linked signer, subaccount, and product metadata. It creates no orders.
## Troubleshooting
- `Missing NADO_SIGNER_PRIVATE_KEY`: provide the 32-byte key of an authorized linked signer.
- Invalid private-key errors: confirm the value contains `0x` and 64 hexadecimal characters.
- `Missing NADO_SUBACCOUNT_OWNER`: provide the subaccount owner's 20-byte EVM address.
- Signature or permission errors: confirm that the signer is linked to the same owner, subaccount name, and network.
- Product lookup failures: use a native Nado symbol such as `BTC-PERP`.
## Security
- A linked signer can execute trades. Use a dedicated signer and rotate it regularly.
- Keep the primary wallet private key and seed phrase outside ritmex-bot configuration.
- Revoke authorization and create a new signer immediately after exposure.
## References
- [Nado Onboarding](../nado/onboarding-tutorial.md)
- [Nado TypeScript SDK](https://docs.nado.xyz/developer-resources/typescript-sdk)
- [Create a Nado Client](../nado/developer-resources/typescript-sdk/how-to/create-a-nado-client.md)
docs/exchanges/nado.md
+99
View File
@@ -0,0 +1,99 @@
# Nado 配置教程
English version: [Nado Configuration Guide](nado.en.md)
## 适用范围
本教程用于 Nado 永续适配器。Nado 使用 Ink 网络、子账户和 linked signer。ritmex-bot 需要已授权 linked signer 的私钥、子账户 owner 地址和子账户名称。
## 1. 准备 Nado 账户
1. 在 [Nado](https://app.nado.xyz?join=LKbIUs5) 连接 EVM 钱包。
2. 为 Ink 网络准备 ETH gas 和受支持的保证金资产。
3. 完成入金并创建目标子账户。
4. 记录子账户 owner 的 EVM 地址和子账户名称，默认名称为 `default`。
## 2. 获取 linked signer 私钥
Nado 官方 SDK 提供 `createStandardLinkedSigner` 和 `createDeterministicLinkedSignerPrivateKey`，用于创建并授权子账户 linked signer。
当前 Nado Web UI 会在官方域名的浏览器本地存储中保存已授权 signer 信息。使用 Web UI 创建 signer 后，可以在浏览器开发者工具的 `Application` → `Local Storage` 中检查 `nado.userSettings`，读取其中的 `privateKey` 字段。该值属于交易私钥，应在读取后关闭开发者工具并清理任何临时记录。
`NADO_SIGNER_PRIVATE_KEY` 必须是 `0x` 加 64 个十六进制字符。它应是 linked signer 私钥。钱包助记词和主钱包私钥不应填入该变量。
## 3. 主网最小配置
```dotenv
EXCHANGE=nado
NADO_ENV=inkMainnet
NADO_SIGNER_PRIVATE_KEY=<0x_linked_signer_private_key>
NADO_SUBACCOUNT_OWNER=<0x_owner_address>
NADO_SUBACCOUNT_NAME=default
NADO_SYMBOL=BTC-PERP
```
`NADO_SUBACCOUNT_OWNER` 可以使用兼容别名 `NADO_EVM_ADDRESS`。
## 4. 测试网配置
```dotenv
NADO_ENV=inkTestnet
NADO_SIGNER_PRIVATE_KEY=<0x_testnet_linked_signer_private_key>
NADO_SUBACCOUNT_OWNER=<0x_testnet_owner_address>
NADO_SUBACCOUNT_NAME=default
NADO_SYMBOL=BTC-PERP
```
linked signer 的授权与环境绑定。主网 signer 无法用于测试网子账户。
## 5. 符号格式
Nado 永续市场使用 `BTC-PERP`、`ETH-PERP` 这类产品符号。适配器还接受：
- `BTCPERP` → `BTC-PERP`
- `BTCUSDT0` → `BTC-PERP`
- `BTC/PERP` → `BTC-PERP`
应优先使用 Nado API 返回的原始 `*-PERP` 符号。
## 6. 可选配置
| 变量 | 默认值 | 说明 |
| --- | --- | --- |
| `NADO_GATEWAY_WS_URL` | 按环境选择 | 交易网关 WebSocket |
| `NADO_SUBSCRIPTIONS_WS_URL` | 按环境选择 | 行情订阅 WebSocket |
| `NADO_ARCHIVE_URL` | 生产/测试 archive | 历史和索引查询地址 |
| `NADO_TRIGGER_URL` | 生产/测试 trigger | 止损止盈服务地址 |
| `NADO_MARKET_SLIPPAGE_PCT` | `0.01` | 市价/触发单保护范围，`0.01` 表示 1% |
| `NADO_STOP_TRIGGER_SOURCE` | `oracle` | `oracle`、`last` 或 `mid` |
| `NADO_MIN_SIZE_POLICY` | `adjust` | `adjust` 自动上调到最小量；`reject` 直接拒绝 |
| `NADO_DEBUG` | `false` | 详细错误日志 |
## 7. 验证配置
```bash
bun run index.ts doctor --exchange nado --symbol BTC-PERP --json
bun run index.ts market ticker --exchange nado --symbol BTC-PERP --json
```
行情检查会验证网络、linked signer、子账户和产品元数据，不会创建订单。
## 常见问题
- `Missing NADO_SIGNER_PRIVATE_KEY`：填写已授权 linked signer 的 32 字节私钥。
- `Invalid NADO private key`：确认值包含 `0x` 和 64 个十六进制字符。
- `Missing NADO_SUBACCOUNT_OWNER`：填写子账户 owner 的 20 字节 EVM 地址。
- 签名/权限错误：确认 signer 已链接到相同 owner、子账户名称和网络。
- 产品未找到：使用 `BTC-PERP` 这类 Nado 原始符号。
## 安全要求
- linked signer 可以执行交易，应使用专用 signer 并定期轮换。
- 主钱包私钥和助记词不进入 ritmex-bot 配置。
- signer 泄露后立即在 Nado 撤销授权并创建新 signer。
## 参考资料
- [Nado Onboarding](../nado/onboarding-tutorial.md)
- [Nado TypeScript SDK](https://docs.nado.xyz/developer-resources/typescript-sdk)
- [创建 Nado Client](../nado/developer-resources/typescript-sdk/how-to/create-a-nado-client.md)
docs/exchanges/ondoperps.en.md
+97
View File
@@ -0,0 +1,97 @@
# Ondo Perps Configuration Guide
中文版：[Ondo Perps 配置教程](ondoperps.md)
## Scope
This guide configures the Ondo Perps crypto, equity, and commodity perpetual adapter. Authentication uses an API key ID and an API secret with HMAC-SHA256 signatures.
## 1. Create an API key
1. Activate and fund an account on [Ondo Perps](https://app.ondoperps.xyz/?ref=4A3ACQ).
2. Create an API key with read and trading permissions from the account API settings.
3. Save the API key ID and API secret.
4. Keep withdrawal access disabled and add a fixed IPv4 whitelist.
## 2. Minimal mainnet configuration
```dotenv
EXCHANGE=ondoperps
ONDOPERPS_API_KEY_ID=<your_ondo_key_id>
ONDOPERPS_API_SECRET=<your_ondo_api_secret>
ONDOPERPS_SYMBOL=BTC-USD.P
```
Market symbols use the `{TICKER}-USD.P` format, including:
- `BTC-USD.P`
- `ETH-USD.P`
- `XAU-USD.P`
- `NVDA-USD.P`
The adapter also normalizes `BTCUSDT`, `BTC/USD`, and `BTC-USD` to `BTC-USD.P`.
## 3. Sandbox configuration
```dotenv
EXCHANGE=ondoperps
ONDOPERPS_SANDBOX=true
ONDOPERPS_API_KEY_ID=<your_sandbox_key_id>
ONDOPERPS_API_SECRET=<your_sandbox_api_secret>
ONDOPERPS_SYMBOL=BTC-USD.P
```
Sandbox mode defaults to:
- REST: `https://api.ondoperps-sandbox.xyz`
- WebSocket: `wss://api.ondoperps-sandbox.xyz/ws`
The sandbox requires separately generated credentials.
## 4. Optional settings
| Variable | Default | Purpose |
| --- | --- | --- |
| `ONDOPERPS_BASE_URL` | `https://api.ondoperps.xyz` | REST API base URL |
| `ONDOPERPS_WS_URL` | `wss://api.ondoperps.xyz/ws` | WebSocket URL |
| `ONDOPERPS_BUILDER_CODE` | Empty | Builder code assigned by Ondo |
| `ONDOPERPS_BUILDER_FEE_RATE_BPS` | Empty | Positive integer builder fee, capped at 10 bps by the adapter |
Compatibility aliases:
- `EXCHANGE=ondoperp` or `EXCHANGE=ondo`
- Legacy `ONDOPERP_*` variable prefix
- `ONDO_KEY_ID` and `ONDO_API_SECRET`
Use `ondoperps` and `ONDOPERPS_*` for new deployments.
## 5. Verify the configuration
```bash
bun run index.ts doctor --exchange ondoperps --symbol BTC-USD.P --json
bun run index.ts market ticker --exchange ondoperps --symbol BTC-USD.P --json
```
The ticker check loads contract precision, opens WebSocket connections, and performs read-only market requests. It creates no orders.
## Troubleshooting
- `Missing ONDOPERPS_API_KEY_ID or ONDOPERPS_API_SECRET`: provide the complete credential pair.
- `401` or signature failures: synchronize system time and verify the key ID, secret, environment, and IP whitelist.
- Missing market: use a `{TICKER}-USD.P` symbol from the official Ondo market list.
- Invalid builder fee: use an integer from `1` to `10` bps.
- Empty production account in sandbox: use the dedicated sandbox account and credentials.
## Security
- Grant read and trading permissions only.
- Pass the API secret through the local runtime environment.
- Revoke and replace the key immediately after exposure.
## References
- [Ondo Perps API Authentication](https://docs.ondoperps.xyz/api-reference/api_key_authentication.md)
- [Ondo Perps REST Specification](https://docs.ondoperps.xyz/api-reference/rest-spec.json)
- [Ondo Perps WebSocket Specification](https://docs.ondoperps.xyz/api-reference/ws-spec.json)
- [Repository Ondo Perps integration reference](../ondoperps/README.md)
docs/exchanges/ondoperps.md
+97
View File
@@ -0,0 +1,97 @@
# Ondo Perps 配置教程
English version: [Ondo Perps Configuration Guide](ondoperps.en.md)
## 适用范围
本教程用于 Ondo Perps 加密资产、股票和商品永续适配器。认证使用 API Key ID 与 API Secret 的 HMAC-SHA256 签名。
## 1. 创建 API Key
1. 在 [Ondo Perps](https://app.ondoperps.xyz/?ref=4A3ACQ) 完成账户开通和入金。
2. 在账户 API 管理页面创建具备读取和交易权限的 API Key。
3. 保存 API Key ID 和 API Secret。
4. 关闭提现权限并配置固定 IPv4 白名单。
## 2. 主网最小配置
```dotenv
EXCHANGE=ondoperps
ONDOPERPS_API_KEY_ID=<your_ondo_key_id>
ONDOPERPS_API_SECRET=<your_ondo_api_secret>
ONDOPERPS_SYMBOL=BTC-USD.P
```
市场符号使用 `{TICKER}-USD.P` 格式，例如：
- `BTC-USD.P`
- `ETH-USD.P`
- `XAU-USD.P`
- `NVDA-USD.P`
适配器也会把 `BTCUSDT`、`BTC/USD` 和 `BTC-USD` 归一化为 `BTC-USD.P`。
## 3. 沙盒配置
```dotenv
EXCHANGE=ondoperps
ONDOPERPS_SANDBOX=true
ONDOPERPS_API_KEY_ID=<your_sandbox_key_id>
ONDOPERPS_API_SECRET=<your_sandbox_api_secret>
ONDOPERPS_SYMBOL=BTC-USD.P
```
启用沙盒后默认使用：
- REST：`https://api.ondoperps-sandbox.xyz`
- WebSocket：`wss://api.ondoperps-sandbox.xyz/ws`
沙盒需要独立生成的凭证。
## 4. 可选配置
| 变量 | 默认值 | 说明 |
| --- | --- | --- |
| `ONDOPERPS_BASE_URL` | `https://api.ondoperps.xyz` | REST API 地址 |
| `ONDOPERPS_WS_URL` | `wss://api.ondoperps.xyz/ws` | WebSocket 地址 |
| `ONDOPERPS_BUILDER_CODE` | 空 | Ondo 分配的 Builder Code |
| `ONDOPERPS_BUILDER_FEE_RATE_BPS` | 空 | 正整数 Builder 费率，适配器上限为 10 bps |
兼容别名：
- `EXCHANGE=ondoperp` 或 `EXCHANGE=ondo`
- `ONDOPERP_*` 旧变量前缀
- `ONDO_KEY_ID` 与 `ONDO_API_SECRET`
新部署应统一使用 `ondoperps` 和 `ONDOPERPS_*`。
## 5. 验证配置
```bash
bun run index.ts doctor --exchange ondoperps --symbol BTC-USD.P --json
bun run index.ts market ticker --exchange ondoperps --symbol BTC-USD.P --json
```
行情检查会加载合约精度、连接 WebSocket 并执行只读市场请求，不会创建订单。
## 常见问题
- `Missing ONDOPERPS_API_KEY_ID or ONDOPERPS_API_SECRET`：填写完整凭证对。
- `401` 或签名失败：同步系统时间，检查 Key ID、Secret、环境和 IP 白名单。
- 市场不存在：使用 Ondo 官方市场列表中的 `{TICKER}-USD.P` 符号。
- Builder 费率异常：使用 `1`–`10` 的整数 bps 值。
- 沙盒连接生产账户为空：使用沙盒专用账户和凭证。
## 安全要求
- API Key 仅授予读取和交易权限。
- API Secret 只通过本机运行环境传入。
- 凭证泄露后立即撤销 Key 并创建新凭证。
## 参考资料
- [Ondo Perps API Authentication](https://docs.ondoperps.xyz/api-reference/api_key_authentication.md)
- [Ondo Perps REST Specification](https://docs.ondoperps.xyz/api-reference/rest-spec.json)
- [Ondo Perps WebSocket Specification](https://docs.ondoperps.xyz/api-reference/ws-spec.json)
- [仓库内 Ondo Perps 接入说明](../ondoperps/README.md)
docs/exchanges/paradex.en.md
+83
View File
@@ -0,0 +1,83 @@
# Paradex Configuration Guide
中文版：[Paradex 配置教程](paradex.md)
## Scope
This guide configures the Paradex perpetual adapter. The current implementation uses CCXT with an EVM wallet address and matching private key for Paradex account authentication. Production and testnet environments are supported.
## 1. Prepare a dedicated wallet and account
1. Create an EVM wallet dedicated to Paradex API trading.
2. Connect that wallet on [Paradex](https://paradex.io/ref/xingxingjun) and complete account onboarding.
3. Accept the trading terms and fund the target environment.
4. Record the wallet's `0x` address and matching 32-byte private key.
The adapter validates these formats:
- `PARADEX_PRIVATE_KEY` must contain `0x` followed by 64 hexadecimal characters.
- `PARADEX_WALLET_ADDRESS` must contain `0x` followed by 40 hexadecimal characters.
## 2. Minimal mainnet configuration
```dotenv
EXCHANGE=paradex
PARADEX_PRIVATE_KEY=<0x_private_key>
PARADEX_WALLET_ADDRESS=<0x_wallet_address>
PARADEX_SANDBOX=false
PARADEX_SYMBOL=BTC-USD-PERP
```
`BTC-USD-PERP` is the native Paradex market ID. The adapter resolves it to the CCXT unified market symbol. The native ID avoids unified-symbol collisions between options, dated futures, and perpetuals.
## 3. Testnet configuration
```dotenv
EXCHANGE=paradex
PARADEX_PRIVATE_KEY=<0x_testnet_private_key>
PARADEX_WALLET_ADDRESS=<0x_testnet_wallet_address>
PARADEX_SANDBOX=true
PARADEX_SYMBOL=BTC-USD-PERP
```
The Paradex testnet account requires separate onboarding. Mainnet and testnet account state, balances, and authentication contexts are independent.
## 4. Optional settings
| Variable | Default | Purpose |
| --- | --- | --- |
| `PARADEX_RECONNECT_DELAY_MS` | `2000` | WebSocket/polling reconnect delay |
| `PARADEX_USE_PRO` | Auto-detect | Allows `ccxt.pro` streaming APIs |
| `PARADEX_DEBUG` | `false` | Adapter debug output |
The project depends on `ccxt` and does not include `ccxt.pro`. A standard installation uses REST polling.
## 5. Verify the configuration
```bash
bun run index.ts doctor --exchange paradex --symbol BTC-USD-PERP --json
bun run index.ts market ticker --exchange paradex --symbol BTC-USD-PERP --json
```
The ticker check loads markets and verifies account access. It creates no orders. An account without onboarding returns a specific error.
## Troubleshooting
- `Invalid PARADEX_PRIVATE_KEY`: use a 32-byte `0x` hexadecimal private key.
- `Invalid PARADEX_WALLET_ADDRESS`: use the matching 20-byte EVM address.
- `Paradex account is not onboarded`: complete onboarding in the selected mainnet or testnet environment.
- `Symbol ... not found`: use the native market ID, such as `BTC-USD-PERP`.
- Balance query failures: verify that the address, private key, and `PARADEX_SANDBOX` setting belong to one environment.
## Security
- Use a dedicated API wallet and keep only strategy capital in it.
- The private key can sign wallet actions. Apply restrictive file permissions and limit host access.
- Move funds and replace the wallet immediately after key exposure.
## References
- [Paradex API Documentation](https://docs.paradex.trade/)
- [Paradex API Quick Start](https://docs.paradex.trade/api/general-information/api-quick-start)
- [Paradex API Authentication](https://docs.paradex.trade/api/general-information/authentication)
docs/exchanges/paradex.md
+83
View File
@@ -0,0 +1,83 @@
# Paradex 配置教程
English version: [Paradex Configuration Guide](paradex.en.md)
## 适用范围
本教程用于 Paradex 永续适配器。当前实现通过 CCXT 使用 EVM 钱包地址和对应私钥完成 Paradex 账户认证，并支持生产环境与测试网。
## 1. 准备专用钱包与账户
1. 创建一个专用于 Paradex API 交易的 EVM 钱包。
2. 在 [Paradex](https://paradex.io/ref/xingxingjun) 连接该钱包并完成账户 onboarding。
3. 接受交易条款并为目标环境准备保证金。
4. 记录钱包的 `0x` 地址和对应 32 字节私钥。
适配器会校验：
- `PARADEX_PRIVATE_KEY` 必须是 `0x` 加 64 个十六进制字符。
- `PARADEX_WALLET_ADDRESS` 必须是 `0x` 加 40 个十六进制字符。
## 2. 主网最小配置
```dotenv
EXCHANGE=paradex
PARADEX_PRIVATE_KEY=<0x_private_key>
PARADEX_WALLET_ADDRESS=<0x_wallet_address>
PARADEX_SANDBOX=false
PARADEX_SYMBOL=BTC-USD-PERP
```
`BTC-USD-PERP` 是 Paradex 原始 market ID。适配器会将其解析到 CCXT 统一市场符号。使用原始 market ID 可以避免期权、交割合约和永续市场的统一符号冲突。
## 3. 测试网配置
```dotenv
EXCHANGE=paradex
PARADEX_PRIVATE_KEY=<0x_testnet_private_key>
PARADEX_WALLET_ADDRESS=<0x_testnet_wallet_address>
PARADEX_SANDBOX=true
PARADEX_SYMBOL=BTC-USD-PERP
```
Paradex 测试网账户需要独立 onboarding。主网和测试网账户状态、余额与认证上下文相互独立。
## 4. 可选配置
| 变量 | 默认值 | 说明 |
| --- | --- | --- |
| `PARADEX_RECONNECT_DELAY_MS` | `2000` | WebSocket/轮询重连延迟 |
| `PARADEX_USE_PRO` | 自动检测 | 允许使用 `ccxt.pro` 流式接口 |
| `PARADEX_DEBUG` | `false` | 输出适配器调试日志 |
项目依赖包含 `ccxt`，未包含 `ccxt.pro`。当前标准安装会使用 REST 轮询路径。
## 5. 验证配置
```bash
bun run index.ts doctor --exchange paradex --symbol BTC-USD-PERP --json
bun run index.ts market ticker --exchange paradex --symbol BTC-USD-PERP --json
```
行情检查会加载市场并验证账户访问，不会创建订单。未完成 onboarding 时会返回明确错误。
## 常见问题
- `Invalid PARADEX_PRIVATE_KEY`：私钥必须是 32 字节 `0x` 十六进制值。
- `Invalid PARADEX_WALLET_ADDRESS`：填写与私钥匹配的 20 字节 EVM 地址。
- `Paradex account is not onboarded`：在当前主网或测试网完成 onboarding。
- `Symbol ... not found`：使用原始市场 ID，例如 `BTC-USD-PERP`。
- 余额查询失败：检查钱包地址、私钥和 `PARADEX_SANDBOX` 是否属于同一环境。
## 安全要求
- 使用专用 API 钱包，钱包中只保留策略所需资产。
- 私钥具备钱包签名能力，应使用严格文件权限并限制机器访问。
- 私钥泄露后立即转移资产并更换钱包。
## 参考资料
- [Paradex API Documentation](https://docs.paradex.trade/)
- [Paradex API Quick Start](https://docs.paradex.trade/api/general-information/api-quick-start)
- [Paradex API Onboarding](https://docs.paradex.trade/api/general-information/authentication)
docs/exchanges/standx.en.md
+80
View File
@@ -0,0 +1,80 @@
# StandX Configuration Guide
中文版：[StandX 配置教程](standx.md)
## Scope
This guide configures the StandX perpetual adapter. A standard setup uses a JWT token and an Ed25519 request-signing private key. The JWT authenticates the session, and the Ed25519 key signs trading requests.
## 1. Obtain the token and signing key
1. Open [StandX API Session](https://standx.com/user/session).
2. Connect the wallet and sign in.
3. Generate an API token.
4. Save the JWT token, Ed25519 private key, creation date, and validity period shown by the page.
The official authentication flow obtains a JWT through wallet signing and uses an Ed25519 key for request-body signatures. The official key format is Base58. The adapter also accepts a 32-byte hexadecimal or Base64 representation.
## 2. Minimal configuration
```dotenv
EXCHANGE=standx
STANDX_TOKEN=<your_standx_jwt>
STANDX_REQUEST_PRIVATE_KEY=<your_ed25519_private_key>
STANDX_SYMBOL=BTC-USD
```
`STANDX_TOKEN` is required during adapter construction. `STANDX_REQUEST_PRIVATE_KEY` is required for signed actions such as creating orders, cancelling orders, and changing margin mode.
## 3. Token-expiry reminder
The official authentication flow uses a seven-day JWT lifetime by default. Configure the reminder from the values shown on the API page:
```dotenv
STANDX_TOKEN_CREATE_DATE=2026-07-12
STANDX_TOKEN_VALIDITY_DAYS=7
```
The legacy `STANDX_TOKEN_EXPIRY` setting accepts a seconds/milliseconds timestamp or an ISO date.
## 4. Optional settings
| Variable | Default | Purpose |
| --- | --- | --- |
| `STANDX_BASE_URL` | `https://perps.standx.com` | REST API base URL |
| `STANDX_WS_URL` | `wss://perps.standx.com/ws-stream/v1` | WebSocket URL |
| `STANDX_SESSION_ID` | Generated UUID | Session identifier for order-response streams |
| `STANDX_WS_DEBUG` | `false` | WebSocket debug logging |
| `STANDX_WS_DEBUG_RAW` | `false` | Raw WebSocket message logging |
Symbols use values such as `BTC-USD`. Confirm `PRICE_TICK`, `QTY_STEP`, and minimum quantity from the StandX market rules.
## 5. Verify the configuration
```bash
bun run index.ts doctor --exchange standx --symbol BTC-USD --json
bun run index.ts market ticker --exchange standx --symbol BTC-USD --json
```
These commands create no orders. Generate a new credential set after expiry and update both the token and signing key.
## Troubleshooting
- `Missing STANDX_TOKEN`: provide a valid JWT token.
- `Request signature skipped`: provide `STANDX_REQUEST_PRIVATE_KEY` and confirm its decoded length is 32 bytes.
- `401` or token expiry: generate a fresh token and update the expiry settings.
- Missing order-response events: keep `STANDX_SESSION_ID` stable and verify the WebSocket URL.
## Security
- The token and signing key together provide trading capability. Protect both as trading credentials.
- Use a dedicated API session and rotate it regularly.
- Revoke the session and generate new credentials immediately after exposure.
## References
- [StandX Authentication](https://docs.standx.com/standx-api/perps-auth)
- [StandX HTTP API](https://docs.standx.com/standx-api/perps-http)
- [Repository StandX authentication reference](../standx/auth.md)
- [StandX Maker Points strategy guide](../standx/maker-points-guide.md)
docs/exchanges/standx.md
+80
View File
@@ -0,0 +1,80 @@
# StandX 配置教程
English version: [StandX Configuration Guide](standx.en.md)
## 适用范围
本教程用于 StandX 永续适配器。标准配置包含 JWT Token 和 Ed25519 请求签名私钥。JWT 负责身份认证，签名私钥负责交易类请求签名。
## 1. 获取 Token 与签名私钥
1. 打开 [StandX API Session](https://standx.com/user/session)。
2. 连接钱包并完成登录。
3. 生成 API Token。
4. 保存页面显示的 JWT Token、Ed25519 Private Key、创建日期和有效期。
官方认证流程使用钱包签名获取 JWT，并使用 Ed25519 密钥签署请求正文。官方密钥格式为 Base58，适配器也接受 32 字节十六进制或 Base64 表示。
## 2. 最小配置
```dotenv
EXCHANGE=standx
STANDX_TOKEN=<your_standx_jwt>
STANDX_REQUEST_PRIVATE_KEY=<your_ed25519_private_key>
STANDX_SYMBOL=BTC-USD
```
`STANDX_TOKEN` 是适配器初始化的必填项。`STANDX_REQUEST_PRIVATE_KEY` 是下单、撤单和修改保证金模式等签名请求的必填项。
## 3. Token 到期提醒
StandX 官方认证流程的默认 JWT 有效期为 7 天。按 API 页面显示的信息配置到期提醒：
```dotenv
STANDX_TOKEN_CREATE_DATE=2026-07-12
STANDX_TOKEN_VALIDITY_DAYS=7
```
旧配置也支持 `STANDX_TOKEN_EXPIRY`，其值可以是秒级/毫秒级时间戳或 ISO 日期。
## 4. 可选配置
| 变量 | 默认值 | 说明 |
| --- | --- | --- |
| `STANDX_BASE_URL` | `https://perps.standx.com` | REST API 地址 |
| `STANDX_WS_URL` | `wss://perps.standx.com/ws-stream/v1` | WebSocket 地址 |
| `STANDX_SESSION_ID` | 自动生成 UUID | 订单响应流会话标识 |
| `STANDX_WS_DEBUG` | `false` | 输出 WebSocket 调试日志 |
| `STANDX_WS_DEBUG_RAW` | `false` | 输出原始 WebSocket 消息 |
交易对使用 `BTC-USD` 这类格式。通过市场规则确认 `PRICE_TICK`、`QTY_STEP` 和最小数量。
## 5. 验证配置
```bash
bun run index.ts doctor --exchange standx --symbol BTC-USD --json
bun run index.ts market ticker --exchange standx --symbol BTC-USD --json
```
以上命令不会创建订单。Token 到期后重新生成凭证，并同步更新 Token 与签名私钥。
## 常见问题
- `Missing STANDX_TOKEN`：填写有效 JWT Token。
- `Request signature skipped`：填写 `STANDX_REQUEST_PRIVATE_KEY`，确认 Base58 解码后为 32 字节。
- `401` 或 Token 过期：重新生成 Token，更新到期配置。
- 订单响应流缺失：保持 `STANDX_SESSION_ID` 稳定并检查 WebSocket 地址。
## 安全要求
- Token 与签名私钥组合具备交易能力，应按交易凭证级别保护。
- 使用独立 API 会话并定期轮换。
- 凭证泄露后立即在 StandX 撤销会话并生成新凭证。
## 参考资料
- [StandX Authentication](https://docs.standx.com/standx-api/perps-auth)
- [StandX HTTP API](https://docs.standx.com/standx-api/perps-http)
- [仓库内 StandX 认证参考](../standx/auth.md)
- [StandX 做市积分策略教程](../standx/maker-points-guide.md)