跳到內容

撰寫腳本和交易機器人

  • 結果寫到 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 不儲存這個時間,請在簽名時自行記錄。