잔액과 원장 확인

잔액은 고객이 현재 보유한 자산 상태를 나타냅니다. 원장은 확정된 잔액 변동을 기록하는 append-only 데이터입니다. 두 정보는 서로 다른 목적으로 사용합니다.

잔액 조회

현재 계정에 존재하는 전체 자산을 조회합니다.

wallet_request GET "/accounts/$ACCOUNT_ID/balances" | jq

선택한 자산만 직접 조회합니다.

wallet_request GET "/accounts/$ACCOUNT_ID/balances/$ASSET_TYPE_ID" | jq

사용 가능 금액과 진행 중인 작업에 예약된 금액을 구분해서 확인합니다. 거래가 한 번도 없었던 자산은 전체 잔액의 items에 아직 없을 수 있습니다.

단일 자산 잔액 조회는 잔액 행이 아직 없으면 HTTP 404와 BALANCE_NOT_FOUND를 반환합니다. 이를 API 전체 장애로 처리하거나 자동 재시도하지 말고, 계정·자산 ID와 입금 처리 상태를 확인합니다. 고객 화면의 초기 잔액 표시 정책과 실제 입금 완료 판단은 구분하십시오.

*_raw 금액은 자산 최소 단위의 정수 문자열입니다. decimals가 6이면 1000000 raw가 1.00입니다. 금액 계산에는 BigInt, BigInteger 또는 decimal 라이브러리를 사용합니다.

원장 조회

wallet_request GET "/accounts/$ACCOUNT_ID/ledger?asset_type_id=$ASSET_TYPE_ID&after_id=0&limit=100" | jq

고객 지갑에서 주로 사용하는 거래 유형은 다음과 같습니다.

거래	원장 유형	방향
외부 입금	DEPOSIT	CREDIT
내부결제 전송	INTERNAL_OUT	DEBIT
외부 출금	WITHDRAW	DEBIT

원장에는 완료된 잔액 변동이 기록됩니다. 진행 중인 입금이나 출금은 아직 원장에 없을 수 있으므로 업무 상세 API로 상태를 추적합니다.

원장 단건 조회

원장 ID는 한 계정에만 속하므로 account_id와 ledger_id를 한 쌍으로 저장합니다.

export LEDGER_ID='{ledger-id-from-list}'
wallet_request GET "/accounts/$ACCOUNT_ID/ledger/$LEDGER_ID" | jq

ref_type과 ref_id로 관련 입금 또는 출금 상세와 연결합니다.

원장 증분 동기화

원장 응답의 next_cursor를 저장하고 ledger_id 기준으로 멱등 저장하며 has_more가 true인 동안 계속 조회합니다. 원장은 append-only이므로 cursor 동기화로 충분합니다. 입금과 출금 cursor는 원장과 별도로 관리합니다.

다음: 외부 출금 요청