mantis-node-cli

基于 ccxt 的交易所 CLI 封装，面向自动化系统/脚本的可编排调用场景。

核心约束

• 业务命令（例如 call、fetch、transfer）只在 stdout 输出一行 JSON。
• help 命令输出纯文本帮助信息，不与业务 JSON 混合。
• 调试日志和错误堆栈输出到 stderr。
• 退出码固定：0 成功、1 参数/配置错误、2 交易所业务错误、3 网络错误、4 内部错误。

命令体系

命令分为两层：

• 顶层通用命令（尽量跨交易所）： call、fetch、transfer、futures-kline、funding-rates、futures-balance、futures-positions、futures-order、futures-orders、futures-cancel、set-position-mode、set-margin-mode
• Gate 专属命令（统一在 gate 子命令组）： mantis gate total-balance、mantis gate sub-accounts、mantis gate sub-balance、mantis gate sub-futures-balance、mantis gate sub-transfer、mantis gate dual-mode、mantis gate dual-position、mantis gate dual-leverage、mantis gate dual-risk-limit、mantis gate dual-margin-mode

说明：

• set-position-mode、set-margin-mode 对外是通用命令，内部采用「unified 优先，Gate fallback」。
• sub-transfer 是 Gate 专属能力，只在 mantis gate sub-transfer 提供。

安装

先安装 Bun，然后在项目目录执行：

bun install

可选：全局安装命令。

bun add -g .

配置与凭证

配置文件路径

固定读取：~/.mantis/config.toml

示例：

[general]
timeout = 30

[[accounts]]
name = "main"
exchange = "gate"
api_key = "your_exchange_api_key"
api_secret = "your_exchange_api_secret"
api_passphrase = "optional"

[[accounts]]
name = "alt"
exchange = "okx"
api_key = "your_exchange_api_key_2"
api_secret = "your_exchange_api_secret_2"

[market.coinglass]
api_key = "your_coinglass_api_key"

凭证优先级与生效规则

最终凭证按以下顺序解析：

1. CLI 参数覆盖（--exchange / --exchange-api-key / --exchange-api-secret / --exchange-api-passphrase / --exchange-user-id）
2. 配置文件 accounts 中选中的账号

账号选择规则：

• 指定 --profile <name>：匹配 accounts[].name
• 不指定 --profile：使用 accounts 第一项

重要规则（避免歧义）：

• 若 未传 --profile 且同时传了完整 CLI 三元组（--exchange + --exchange-api-key + --exchange-api-secret），则可不依赖配置文件。
• 其他情况（例如仅传了部分 CLI 凭证，或者显式传 --profile）都要求 ~/.mantis/config.toml 有效可读。

全局凭证参数

所有命令都支持以下参数（可写在命令前或命令后）：

• --profile <name>
• --exchange <exchange>
• --exchange-api-key <key>
• --exchange-api-secret <secret>
• --exchange-api-passphrase <passphrase>
• --exchange-user-id <userId>

示例：

mantis --profile alt call --method fetchBalance
mantis call --method fetchBalance --profile alt
mantis gate --profile main sub-accounts
mantis gate sub-accounts --profile main

快速开始

# 1) 查看可用命令
mantis help

# 2) 查询余额（使用默认 profile）
mantis call --method fetchBalance

# 3) 直接走 CLI 凭证（不依赖配置文件）
mantis call --method fetchBalance \
  --exchange gate \
  --exchange-api-key <key> \
  --exchange-api-secret <secret>

# 4) Gate 专属命令
mantis gate sub-accounts

输出协议

成功响应

{
  "success": true,
  "requestId": "550e8400-e29b-41d4-a716-446655440000",
  "data": {}
}

失败响应

{
  "success": false,
  "requestId": "550e8400-e29b-41d4-a716-446655440000",
  "error": {
    "code": "EXCHANGE_ERROR",
    "message": "..."
  }
}

requestId 每次调用唯一，用于日志串联与问题定位。

退出码

| 退出码 | 含义 | |---|---| | 0 | 成功 | | 1 | 参数错误 / 配置错误 / 不支持的命令能力 | | 2 | 交易所业务错误（认证失败、余额不足、订单不存在等） | | 3 | 网络错误（超时、连接失败、DNS 等） | | 4 | 内部错误 |

主要错误码

| 错误码 | 说明 | |---|---| | MISSING_CREDENTIALS | 缺少必要凭证 | | UNKNOWN_EXCHANGE | 交易所 ID 不受 ccxt 支持 | | INVALID_PARAMS | 参数不合法 | | UNKNOWN_METHOD | call 指定的方法不存在 | | UNSUPPORTED_EXCHANGE | 当前交易所不支持该命令能力 | | AUTH_FAILED | 鉴权失败 | | INSUFFICIENT_FUNDS | 余额不足 | | RATE_LIMIT | 触发限流 | | ORDER_NOT_FOUND | 订单不存在 | | INVALID_ORDER | 订单状态非法 | | EXCHANGE_ERROR | 其他交易所业务错误 | | NETWORK | 网络层错误 | | INTERNAL_ERROR | 未预期错误 |

调试

# 仅查看 stdout（业务 JSON）
mantis call --method fetchBalance 2>/dev/null

# 仅查看 stderr（调试日志）
mantis call --method fetchBalance 1>/dev/null

# 分离保存
mantis call --method fetchBalance > result.json

构建与测试

# 测试（含覆盖率）
npm test

# 仅测试
npm run test:unit

# 构建单文件可执行产物
bun run build

文档索引

• 完整命令手册见 Command.md

项目结构

bin/
  mantis.js                 # CLI 入口（命令汇总注册）
  runtime.js             # CLI 运行时（凭证、校验、错误映射、重试）
  commands/generic.js    # 通用命令注册
  commands/gate.js       # Gate 专属命令注册
src/
  credentials.js         # 凭证解析
  exchange.js            # 交易所实例创建
  errors.js              # 错误映射
  output.js              # JSON 输出封装
  coinglass.js           # CoinGlass 聚合
tests/
  cli.test.js            # CLI 集成测试