한국어
잔액과 원장
잔액은 현재 얼마를 사용할 수 있는지, 원장은 어떤 확정 거래가 금액을 바꿨는지를 보여줍니다. 입출금 상세는 거래가 진행 중인지 완료됐는지를 알려줍니다. 지갑 화면, 거래 추적, 대사는 각 질문에 맞는 리소스를 사용합니다.
잔액의 세 가지 금액
잔액은 계정과 자산 유형을 기준으로 관리합니다. USDT 잔액과 ETH 잔액은 별개이며 서로 다른 자산의 raw 금액을 합산하지 않습니다.
| 필드 | 의미 | 사용하는 곳 |
|---|---|---|
available_amount_raw | 지금 사용할 수 있는 금액 | 출금·내부이체 전 자금 확인 |
pending_withdraw_amount_raw | 진행 중인 출금에 예약된 금액 | 출금 대기 금액 표시 |
total_amount_raw | 사용 가능 금액과 출금 예약 금액을 포함한 총액 | 지갑의 현재 보유 현황 |
decimals | raw 금액의 소수점 자릿수 | 고객 표시 금액 변환 |
총 잔액과 사용 가능 잔액이 다르면 그 차이는 진행 중인 출금 예약을 함께 확인해 해석합니다. 아직 완료되지 않은 외부 입금은 입금 상세의 처리 상태를 확인하며, 감지된 금액을 고객사에서 사용 가능 잔액에 임의로 더하지 않습니다.
고객 지갑의 출금 예시
고객이 100 USDT를 보유하고 외부 주소로 20 USDT를 출금한다고 가정합니다. 예시 수수료는 1 USDT이며, 다른 동시 거래는 없습니다.
| 시점 | 사용 가능 | 출금 예약 | 총 잔액 | 해석 |
|---|---|---|---|---|
| 출금 전 | 100 | 0 | 100 | 전체 금액 사용 가능 |
| 출금 접수 후 | 79 | 21 | 100 | 원금 20 + 수수료 1 예약 |
| 출금 완료 | 79 | 0 | 79 | 예약 자금의 출금 확정 |
| 실패·거절·취소로 예약 해제된 경우 | 100 | 0 | 100 | 원금과 수수료의 사용 가능 잔액 복구 |
완료와 예약 해제는 서로 다른 결과입니다. 최종 출금 상세와 잔액 응답을 함께 확인합니다. 표는 표시 금액이며 decimals=6이라면 예약된 21 USDT의 raw 값은 21000000입니다.
원장 한 건이 의미하는 것
원장은 확정된 잔액 변동을 추가 기록하는 이력입니다. 원장 항목은 거래 전체가 아니라 그 거래에서 발생한 하나의 금액 변동을 나타내므로, 한 거래에 여러 항목이 연결될 수 있습니다.
transaction_type | 코드 | entry_type | 의미 |
|---|---|---|---|
DEPOSIT | 1000 | CREDIT | 완료된 외부 입금 |
WITHDRAW | 2000 | DEBIT | 완료된 외부 출금 |
INTERNAL_OUT | 3000 | DEBIT | 보낸 내부이체 |
INTERNAL_IN | 4000 | CREDIT | 받은 내부이체 |
ADJUSTMENT | 5000 | 항목에 따라 다름 | 정정에 따른 금액 변동 |
표의 명칭은 의미를 설명하며 API의 transaction_type은 숫자 코드입니다. amount_raw는 절댓값이고 entry_type이 CREDIT이면 증가, DEBIT이면 감소입니다. entry_code는 원금·수수료 등 분개의 성격을 구분합니다.
ref_type과 ref_id는 원장 항목을 해당 거래에 연결합니다. ref_type=1000이면 입금, ref_type=2000이면 출금·내부이체 참조입니다. 원금과 수수료 항목을 구분하되 같은 참조의 관련 항목을 함께 확인합니다.
잔액과 원장을 대사하기
대사는 거래·원장·잔액이 서로 일치하는지 확인하는 작업입니다. 다른 예약이나 동시 거래가 없는 동일 계정·자산의 확정 구간에서는 다음 관계로 금액을 확인할 수 있습니다.
text
기말 잔액 = 기초 잔액 + CREDIT 합계 - DEBIT 합계100 USDT 입금 후 20 USDT와 수수료 1 USDT의 외부 출금이 완료됐다면 확정 변동의 결과는 79 USDT입니다. 진행 중인 예약이 있는 시점에는 사용 가능 잔액만 이 식에 대입하지 않고 예약 금액과 비교 구간을 함께 확인합니다.
Raw 금액, balance_after_raw, 거래 참조를 사용해 검증합니다. ledger_id와 계정 ID를 함께 저장하고 원장 순서를 유지합니다. 동기화 방법은 거래 대사를 참고합니다.
내부이체와 결제의 금액 변화
내부이체는 송신 계정에 INTERNAL_OUT / DEBIT, 수신 계정에 INTERNAL_IN / CREDIT을 기록합니다. 양쪽 항목은 동일한 출금 참조로 연결되며 내부이체 수수료는 0입니다.
예를 들어 고객 잔액 100 USDT에서 가맹점에 10 USDT를 결제하면 고객은 90 USDT, 초기 잔액이 0이었던 가맹점은 10 USDT를 보유합니다. 일반 계정 간 이체도 같은 방식입니다. 개별 이체·결제 성공은 잔액 차이만으로 판단하지 않고 해당 거래 상세로 확인합니다.
조회 결과 해석
전체 잔액 조회에는 아직 거래가 없던 자산이 없을 수 있습니다. 단일 자산 조회는 잔액이 없으면 BALANCE_NOT_FOUND를 반환할 수 있으므로 계정·자산과 입금 상태를 확인합니다.
실제 잔액·원장 조회는 잔액과 원장 확인에서 진행합니다. 잔액이 언제 적립되는지는 입금 처리 흐름, 예약이 언제 확정되는지는 출금 처리 흐름에서 설명합니다.