撰寫腳本和交易機器人
- 結果寫到 stdout,預設是單行 JSON,一行一個物件。加
--pretty輸出縮排格式,會跨多行,腳本裡不要加。 - 例外:
jv market list預設輸出文字表格,加--json才輸出 JSON;jv install、jv update輸出的是文字。 - 提示訊息寫到 stderr,包括下單時的預估、參數警告、等待瀏覽器簽名時每 10 秒一行的等待狀態、錯誤訊息(以
Error:開頭)和新版本提示。解析結果時只讀 stdout。 - 價格和數量多為字串,例如
"price":"64073.95"。priceWei和訂單原始欄位裡的大整數請按字串或大整數處理,不要轉成浮點數。
各指令輸出幾行
Section titled “各指令輸出幾行”| 指令 | 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。
讀取價格:
市價單分別讀取回執和結果:
| 結束代碼 | 含義 |
|---|---|
| 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 版本變化可能改變指令和輸出,正式環境請固定版本:
目前沒有的功能
Section titled “目前沒有的功能”- 沒有 dry-run:指令一執行就會送出真實訂單。
- 沒有使用者端訂單編號或冪等鍵:同一條指令執行兩次,就是兩筆訂單。
- 沒有批次下單:
jv order close --all也是逐筆依序送出。 - 沒有行情推播:價格要用
jv price輪詢。 - 沒有查詢帳戶餘額的指令。
- 同一個錢包的訂單逐筆送出,等上一筆有了結果再送出下一筆。
- 下單前用
jv price取得最新價格,不要用快取的舊價格。 - 每筆訂單都記錄日誌:完整指令、stdout 的每一行、stderr 和結束代碼。
- 授權到期後要重新執行
jv enable,這一步需要在瀏覽器裡用錢包簽名,無法無人值守完成。長期執行的機器人要提前安排續期。授權有效期目前是 7 天。到期時間寫在簽名請求的deadline欄位裡(Unix 秒),CLI 不儲存這個時間,請在簽名時自行記錄。