コンテンツにスキップ

スクリプトと取引ボットを書く

  • 結果は stdout に書き出されます。デフォルトは 1 行の JSON で、1 行に 1 つのオブジェクトです。--pretty を付けるとインデント付きの形式で複数行にわたって出力されるため、スクリプトでは付けないでください。
  • 例外:jv market list はデフォルトでテキストの表を出力し、--json を付けたときだけ JSON を出力します。jv install、jv update の出力はテキストです。
  • 案内メッセージは stderr に書き出されます。注文時の見積もり、パラメーターの警告、ブラウザーでの署名待ちの間に 10 秒ごとに 1 行出力される待機状況、エラーメッセージ(Error: で始まる)、新しいバージョンの案内が含まれます。結果を解析するときは stdout だけを読んでください。
  • 価格と数量の多くは文字列です(例:"price":"64073.95")。priceWei や注文の元のフィールドにある大きな整数は、文字列または多倍長整数として扱い、浮動小数点数に変換しないでください。
コマンド stdout
成行注文 jv order create(--limit-price なし) 2 行:送信の受付結果(jobId を含む)、執行結果(status、transactionHash を含む)
jv order protect 2 行:送信の受付結果(jobId を含む)、執行結果
指値注文 jv order create --limit-price、jv tp set、jv sl set 1 行。limitOrderId を含む
jv order close 1 行:{"closed":[…],"failed":[…]}
jv enable、jv deposit、jv withdraw まず 1 行(url を含む)を出力し、完了後に結果をもう 1 行出力
その他の照会コマンド 1 行

送信前にコマンドがエラーになった場合(パラメーターの誤り、API による拒否など)、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 業務エラー:API がリクエストを拒否した、成行注文の執行結果が 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 は failed や timeout が返った場合でも常に 0 を返すため、status フィールドを読んで判断する必要があります。

  • 各 HTTP リクエストのデフォルトのタイムアウトは 30 秒で、環境変数 JV_TIMEOUT(単位はミリ秒)で調整できます。
  • 成行注文と jv order protect は、送信後に執行結果を最大 60 秒待ちます。
  • CLI は注文を自動でリトライしません。プログラム側でも、結果が不明なときに自動でリトライせず、まず確認してください。

各コマンド(jv mcp、jv update を除く)は、実行後に新しいバージョンがあるかどうかを確認します。前回の確認から 24 時間以上経過していれば、npm registry(registry.npmjs.org、最大 5 秒待機)に 1 回リクエストを送り、結果を ~/.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 はありません。コマンドを実行するとすぐに実際の注文が送信されます。
  • クライアント注文 ID や冪等キーはありません。同じコマンドを 2 回実行すると 2 件の注文になります。
  • 一括注文はありません。jv order close --all も 1 件ずつ順番に送信します。
  • 相場のプッシュ配信はありません。価格は jv price でポーリングする必要があります。
  • アカウント残高を照会するコマンドはありません。
  • 同じウォレットの注文は 1 件ずつ送信し、前の注文の結果が出てから次を送信してください。
  • 注文前に jv price で最新価格を取得し、キャッシュされた古い価格を使わないでください。
  • すべての注文についてログを残してください。完全なコマンド、stdout の各行、stderr、終了コードを記録します。
  • 認可の有効期限が切れたら jv enable を再実行する必要があります。この手順にはブラウザーでのウォレット署名が必要で、無人では完了できません。長期間稼働するボットでは、事前に更新の段取りをしておいてください。認可の有効期間は現在 7 日間です。有効期限は署名リクエストの deadline フィールド(Unix 秒)に記載されています。CLI はこの時刻を保存しないため、署名時に自分で記録してください。