스크립트와 트레이딩 봇 작성
출력 형식
섹션 제목: “출력 형식”- 결과는 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에만 표시됩니다.
가격 읽기:
시장가 주문의 응답과 결과를 각각 읽기:
종료 코드
섹션 제목: “종료 코드”| 종료 코드 | 의미 |
|---|---|
| 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 버전이 바뀌면 명령과 출력이 달라질 수 있으므로, 프로덕션 환경에서는 버전을 고정하십시오.
현재 없는 기능
섹션 제목: “현재 없는 기능”- dry-run이 없습니다: 명령을 실행하는 즉시 실제 주문이 제출됩니다.
- 클라이언트 주문 번호나 멱등 키가 없습니다: 같은 명령을 두 번 실행하면 주문이 두 건 생깁니다.
- 일괄 주문이 없습니다:
jv order close --all도 한 건씩 순서대로 제출합니다. - 시세 푸시가 없습니다: 가격은
jv price로 폴링해야 합니다. - 계정 잔액을 조회하는 명령이 없습니다.
권장 사항
섹션 제목: “권장 사항”- 같은 지갑의 주문은 한 건씩 제출하고, 이전 주문의 결과가 나온 뒤 다음 주문을 제출하십시오.
- 주문하기 전에
jv price로 최신 가격을 가져오고, 캐시된 이전 가격을 사용하지 마십시오. - 모든 주문에 대해 전체 명령, stdout의 모든 줄, stderr, 종료 코드를 로그로 기록하십시오.
- 권한 부여가 만료되면
jv enable을 다시 실행해야 합니다. 이 단계는 브라우저에서 지갑으로 서명해야 하므로 무인으로 완료할 수 없습니다. 장기간 실행되는 봇은 미리 갱신 일정을 잡아 두십시오. 권한 부여의 유효 기간은 현재 7일입니다. 만료 시각은 서명 요청의deadline필드(Unix 초)에 적혀 있습니다. CLI는 이 시각을 저장하지 않으므로 서명할 때 직접 기록해 두십시오.