콘텐츠로 이동

스크립트와 트레이딩 봇 작성

  • 결과는 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 포함)을 출력하고, 완료 후 결과를 한 줄 더 출력
기타 조회 명령 한 줄

명령이 제출 전에 오류가 나면(파라미터 오류, 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초 대기)에 한 번 요청하고, 결과는 ~/.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는 이 시각을 저장하지 않으므로 서명할 때 직접 기록해 두십시오.