跳转到内容

写脚本和交易机器人

  • 结果写到 stdout,默认是单行 JSON,一行一个对象。加 --pretty 输出缩进格式,会跨多行,脚本里不要加。
  • 例外:jv market list 默认输出文本表格,加 --json 才输出 JSON;jv install、jv update 输出的是文本。
  • 提示信息写到 stderr,包括下单时的预估、参数警告、等待浏览器签名时每 10 秒一行的等待状态、错误信息(以 Error: 开头)和新版本提示。解析结果时只读 stdout。
  • 价格和数量多为字符串,比如 "price":"64073.95"。priceWei 和订单原始字段里的大整数请按字符串或大整数处理,不要转成浮点数。
命令 stdout
市价单 jv order create(不带 --limit-price) 两行:提交回执(带 jobId),执行结果(带 status、transactionHash)
jv order protect 两行:提交回执(带 jobId),执行结果
限价单 jv order create --limit-price、jv tp set、jv sl set 一行,带 limitOrderId
jv order close 一行:{"closed":[…],"failed":[…]}
jv enable、jv deposit、jv withdraw 先输出一行(带 url),完成后再输出一行结果
其他查询命令 一行

命令在提交前就出错时(参数不对、接口拒绝等),stdout 可能是空的,原因只在 stderr。

读取价格:

jv price --symbol JVBTC | jq -r .price

市价单分别读回执和结果:

out=$(jv order create --side long --symbol JVBTC -m 50 --leverage 10)
code=$?
job_id=$(printf '%s\n' "$out" | head -n 1 | jq -r .jobId)
status=$(printf '%s\n' "$out" | tail -n 1 | jq -r .status)
退出码 含义
0 成功
1 参数或配置错误:缺少必填参数、参数值不对、当前钱包配置还没授权、缺少 BASE_HTTP_RPC_URL 等
2 网络或 HTTP 错误:请求超时、连不上服务、HTTP 状态码不是 2xx;jv price 取不到价格也是 2
3 业务错误:接口拒绝了请求、市价单执行结果不是 completed、jv order close 有仓位没平掉、授权或充值提现没有完成

下单类命令(jv order create、jv order close、jv order protect、jv tp set、jv sl set)的退出码不能直接说明有没有成交。只有下面几种情况算明确成功:

  • 市价单和 jv order protect 的执行结果是 "status": "completed";
  • 限价单、止盈止损单返回了 limitOrderId;
  • jv order close 输出的 failed 为空。

其他情况都要当作结果不明,订单可能已经被受理,甚至已经成交:

  • 退出码 2:请求超时或网络错误时,下单请求可能已经到达服务端。
  • "status": "timeout":60 秒内没拿到执行结果,订单可能仍在执行。
  • "status": "failed":可能是订单失败,也可能是 CLI 查询执行结果时遇到 HTTP 错误或网络错误,订单本身已经成交。

遇到这些情况,先用 jv orders list 和 jv limit-order list 核对,再决定要不要重新提交。

另外,jv job status 总是返回 0,查到 failed 或 timeout 也一样,要读 status 字段判断。

  • 每个 HTTP 请求默认 30 秒超时,可以用环境变量 JV_TIMEOUT(单位毫秒)调整。
  • 市价单和 jv order protect 提交后,最多等 60 秒拿执行结果。
  • CLI 不会自动重试下单。程序也不要在结果不明时自动重试,先核对。

每条命令(jv mcp、jv update 除外)执行完后都会检查有没有新版本:距离上次检查超过 24 小时,就请求一次 npm registry(registry.npmjs.org,最多等 5 秒),结果缓存在 ~/.jaspervault/update-check.json。有新版本时在 stderr 打印提示。通过 MCP 调用时也一样会检查。

对延迟敏感的程序要把这次请求考虑进去。CLI 版本变化可能改变命令和输出,生产环境请固定版本:

npm i -g jaspervault_cli@1.4.0
# 或者每次指定版本运行
npx -y jaspervault_cli@1.4.0 price --symbol JVBTC
  • 没有 dry-run:命令一运行就会提交真实订单。
  • 没有客户端订单号或幂等键:同一条命令运行两次,就是两笔订单。
  • 没有批量下单:jv order close --all 也是逐笔按顺序提交。
  • 没有行情推送:价格要用 jv price 轮询。
  • 没有查询账户余额的命令。
  • 同一个钱包的订单逐笔提交,等上一笔有了结果再提交下一笔。
  • 下单前用 jv price 取最新价格,不要用缓存的旧价。
  • 每笔订单都记日志:完整命令、stdout 的每一行、stderr 和退出码。
  • 授权到期后要重新运行 jv enable,这一步需要在浏览器里用钱包签名,没法无人值守完成。长期运行的机器人要提前安排续期。授权有效期目前是 7 天。到期时间写在签名请求的 deadline 字段里(Unix 秒),CLI 不保存这个时间,请在签名时自己记录。