@onebullex-group/cli

OneBullEx Open API V2 的命令行工具。

当前版本（1.5.0）覆盖 V2 文档的全部 68 个端点：22 个公开 + 25 个私有只读 + 21 个写。所有写命令默认 dry-run，需 --confirm 才真发请求。

安装

npm i -g @onebullex-group/cli

或本地构建：

cd cli
pnpm install
pnpm build
pnpm link --global

校验：

onebullex --version
onebullex public time --base-url https://futures-openapi.1bullex.com

Quick Start

# 1. 初始化一个 profile（向导式）
onebullex config init

# 2. 看下当前 profile 配置（敏感字段已脱敏）
onebullex config show

# 3. 跑公开接口验证联通性
onebullex public time
onebullex symbol list

# 4. 跑私有只读接口（需要在 config init 时填了 api-key/secret）
onebullex balance list
onebullex position list

命令分组

完整命令列表跟 V2 文档逐项对齐，可用 onebullex <group> --help 查询。

公开（22）

public time                    GET /v2/public/time
symbol  list / get / coins / all
ticker  get / list / agg / agg-list   （`--time-range-type` 必填，如 H24 / UTC_P_8）
depth   get                           （`--level` 必填，1–50）
deal    list
kline   list
mark-price  list / get
index-price list / get
funding rate / history
risk-balance list
open-interest get
leverage brackets-list / brackets-get

私有只读（25）

listen-key get
balance list / get / bills / funding
bot     redeeming-info
order list-unfinished / list-unfinished-multi / list / list-by-ids /
      list-history / get / trades
entrust plan-list / plan-history / plan-get / profit-list / profit-get
order-entrust list
position list / confs / history / history-async
system  user-info / download

写操作（21）

所有写命令默认 dry-run：仅打印预览不发请求。加 --confirm 才会真正下单/撤单/改仓/划转。

balance transfer               ⚠ 真实资金划转，见下方说明
order create / create-batch / cancel / cancel-batch / cancel-all
entrust create-plan / create-profit /
        cancel-plan / cancel-profit / update-profit /
        cancel-all-plan / cancel-all-profit
order-entrust cancel / cancel-all
position adjust-leverage / margin / auto-margin /
         close-all / merge / change-type

例：

# dry-run（默认，退出码 4，preview 在 stdout）
onebullex order create --symbol btc_usdt --order-type LIMIT \
  --order-side BUY --position-side LONG --orig-qty 1 --price 50000

# 真正下单
onebullex order create --symbol btc_usdt --order-type LIMIT \
  --order-side BUY --position-side LONG --orig-qty 1 --price 50000 \
  --confirm

CLI flag 用 kebab-case，会映射到 API 的 camelCase 字段（如 --order-side → orderSide）。批量类（create-batch / cancel-batch）的 --list / --order-ids 接受 JSON 字符串数组。

⚠ 资金划转（balance transfer）

在资金账户（FUNDING，存钱、不能交易）和合约账户（CONTRACT，交易占保证金）之间搬钱。 划错不能撤销，只能反向再划一次。

# dry-run：预览里会显示自动生成的 billNo
onebullex balance transfer --from FUNDING --to CONTRACT --amount 500

# 真正划转 —— 把预览里那个 billNo 原样带上
onebullex balance transfer --from FUNDING --to CONTRACT --amount 500 \
  --bill-no obe-3f6c1e9a-... --confirm

--bill-no 是幂等单号。省略时 CLI 会生成一个 obe-<uuid>，但重试同一笔划转必须 复用第一次的单号 —— 换新单号会被服务端当成第二笔，等于划两次。所以脚本里重试请 先把 billNo 存下来，不要依赖自动生成。--from 与 --to 不能相同。

配置管理（6）

config init           交互式向导；新增 profile，--no-set-default 不改默认
config set <key>      仅 base-url / identify / env 可用 --value
                      api-key / secret 必须用 --stdin
config show           [--reveal] 默认脱敏，加 --reveal 后明文（带 stderr 警告）
config use <profile>  切换默认 profile
config list-profiles  表格列出全部 profile
config remove <p>     删除 profile（防止删掉最后一个）

配置文件

默认路径 ~/.onebullex/config.json，权限 0600（非 Windows 上自动校正）。

{
  "version": 1,
  "default-profile": "test",
  "profiles": {
    "test": {
      "base-url": "https://futures-openapi.1bullex.com",
      "api-key": "AK...",
      "secret": "...",
      "identify": null,
      "env": "test"
    }
  }
}

可通过 ONEBULLEX_CONFIG_PATH 环境变量覆盖路径（脚本/CI 友好）。

多个 API Key（多 profile）

一个 profile 对应一套 API Key。同一台电脑要用多个 Key，就在同一个配置文件里建多个 profile，调用时选一个。

添加 profile：每次 config init 新增（或覆盖同名）一个 profile，已有的 profile 保留。默认会把新 profile 设为默认，加 --no-set-default 则不改默认。

onebullex config init                    # 交互式：Profile name 填 alice，按提示填 key/secret
onebullex config init --no-set-default   # 再加一个：Profile name 填 bob，默认仍是 alice
onebullex config list-profiles           # 带 * 的是默认 profile

非交互（脚本）时，key/secret 建议用 --stdin 写入，不进 shell history：

onebullex config init --yes --no-set-default --name bob --env prod
onebullex --profile bob config set api-key --stdin   # 粘贴后 Ctrl+D（Windows: Ctrl+Z 回车）
onebullex --profile bob config set secret  --stdin

选用 profile（优先级从高到低）：

onebullex --profile bob balance list            # 单条命令临时切换，不改默认
ONEBULLEX_PROFILE=bob onebullex balance list    # 当前 shell / 脚本内生效
onebullex config use bob                        # 改默认 profile（影响之后所有未指定的调用）

多个终端或多个 Claude 会话同时跑时，用 --profile 或 ONEBULLEX_PROFILE，不要靠 config use 来回切：默认 profile 存在共享的配置文件里，一边切换，另一边下一次调用就会用错账户。

需要完全隔离（例如每个账户一份文件、不同权限的机器用户）时，用 ONEBULLEX_CONFIG_PATH 指向不同的配置文件：

ONEBULLEX_CONFIG_PATH=~/.onebullex/alice.json onebullex balance list

profile 名写错时会报 未找到 baseUrl 配置，先用 config list-profiles 核对名字。

MCP 场景下怎么同时连多个账户，见 mcp/README.md。

优先级与全局 flag

每次调用按以下顺序解析：

CLI flag > 环境变量 > 配置文件 profile > 报错（要求 config init）

| 全局 flag | 环境变量 | 说明 | |---|---|---| | --profile <name> | ONEBULLEX_PROFILE | 临时切换 profile | | --api-key <key> | ONEBULLEX_API_KEY | 覆盖 api key | | --secret <s> | ONEBULLEX_SECRET | 覆盖 secret（不建议 CLI 上明文） | | --base-url <url> | ONEBULLEX_BASE_URL | 覆盖 base URL | | --output <fmt> | — | table / json，TTY 默认 table，否则 json | | --debug | ONEBULLEX_DEBUG=1 | 把请求/响应（脱敏后）写到 stderr | | --timeout <ms> | — | HTTP 超时，默认 10s | | --confirm | — | Phase 2 写命令使用，未传时走 dry-run |

安全

• secret 与 api-key 明文落盘在 config.json，权限收紧到 0600
• config set api-key / config set secret 拒绝 --value，强制 --stdin，防止 shell history 泄漏
• config show 默认脱敏（AK****1234 / ****），仅 --reveal 时明文并带 stderr 警告
• --debug 输出会通过 redact 过滤掉 X-Signature / X-API-KEY / Authorization / secret 字段
• 每次调用都会校验 ~/.onebullex/config.json 的 mode（非 win32），不是 0600 时打 warn 并自动修复

输出格式

• TTY 下默认表格（cli-table3），列名取并集，时间戳列自动渲染成 YYYY-MM-DD HH:mm:ss
• 非 TTY（管道、重定向、CI）默认 JSON，jq 友好
• 任意时候用 --output json 强制 JSON，--output table 强制表格

防漂移 lint

pnpm check-coverage 跑三层校验：

1. 端点级：把 docs/onebullex-openapi-cn-v2.md 里的所有 #### GET/POST /v2/* 标题与 cli/src/registry.ts 对账，缺/多就 fail
2. 参数级：用 ts-morph 解析每个命令文件，提取 commander 的 command() / requiredOption() / option()，与文档参数表的 必填 列对账
3. 写守门：方法是 GET 但 isWrite=true，或者 method 是 POST 但 isWrite=false（/v2/order/list-by-ids 是已知例外）

CI 上当文档新增一个端点时，coverage 检查会立刻 fail，强制开发者补一个新命令。

开发

cd cli
pnpm install
pnpm dev <command>      # 直接跑 src/index.ts，无需先 build
pnpm test               # 跑全部单测/集成测
pnpm typecheck          # tsc --noEmit
pnpm lint               # biome
pnpm check-coverage     # 防漂移 lint
pnpm build              # 产出 dist/index.js

跑 testnet e2e

只读 e2e（默认跳过）只验证公开接口连通性：

ONEBULLEX_E2E=1 pnpm vitest run tests/e2e/public.e2e.test.ts

写 e2e（默认跳过）会真发请求到 testnet：下/撤远价限价单、改杠杆、改持仓模式、用 MARKET 单开仓 → 加保证金 → 创建止盈止损 → close-all。需要测试网账户和 ≥ 50 USDT 余额：

ONEBULLEX_E2E=1 \
ONEBULLEX_E2E_API_KEY=<testnet-key> \
ONEBULLEX_E2E_SECRET=<testnet-secret> \
pnpm vitest run tests/e2e/write.e2e.test.ts

按业务流程组织成 4 个 block，串行执行：configuration chain → limit order chain → plan + order-entrust chain → position + profit chain。每个 block 末尾有 best-effort cancel-all / close-all，跑挂时也尽量不留挂单/持仓残留。

Nightly CI（可选）

cli/.gitlab-ci.yml 里有一个 cli-e2e-nightly job，仅在 schedule 触发时跑（$CI_PIPELINE_SOURCE == "schedule"），跑完整 tests/e2e/ 套件。开启方式：

1. 在 GitLab project Settings → CI/CD → Variables 添加 masked + protected 变量：
   • ONEBULLEX_E2E_API_KEY = testnet API key
   • ONEBULLEX_E2E_SECRET = testnet API secret
2. Build → Pipeline schedules → New schedule，cron 设成例如 0 19 * * *（每日 03:00 UTC+8），target branch 选 main。

job 标 allow_failure: true 且 retry 一次——testnet 偶发抖动不会阻塞调度。变量没配时只有 public e2e 跑，写 e2e 自动 skip（HAS_AUTH 门控）。

与 Java SDK 的关系

签名实现严格对齐 src/main/java/com/onebullex/api/common/SignatureUtilsV2.java：

• timestamp 秒级（10 位）
• nonce 是 UUID v4 去横线（32 位 hex 小写）
• query string 按 key 字典序排序，不做 URL 编码
• HMAC-SHA256，输出 hex 小写

Java 端通过 SignatureVectorGenTest 生成 cli/tests/fixtures/signature-vectors.json，CLI 端 signature-parity.test.ts 把 7 条向量逐条对照 Java 输出，保证字节级一致。

License

MIT