Wallet 전체 흐름 구현

앞선 튜토리얼을 하나의 백엔드 처리 순서로 정리합니다.

1. 연동 초기화

Base URL, API Key, HMAC Key를 Secret Manager에 저장합니다.
/health와 /time을 확인하고 호출 서버 시각을 동기화합니다.
보호 요청마다 새로운 timestamp, nonce, signature를 만듭니다.
대상 환경의 기준정보에서 자산과 네트워크 ID를 조회합니다.

2. 고객 지갑 준비

안정적인 고객 uid로 기존 계정을 조회합니다.
의도한 활성 USER 계정을 재사용하거나 한 번만 생성합니다.
고객과 계정의 연결 정보를 저장합니다.
선택한 자산·네트워크의 입금 주소를 발급하고 네트워크와 memo 요구사항을 표시합니다.

3. 입금 처리

전용 EXTERNAL cursor로 외부 입금을 탐지합니다.
deposit_id 기준으로 멱등 저장하고 next_cursor를 트랜잭션으로 저장합니다.
새로 발견한 비최종 입금은 ID로 polling합니다.
잔액은 현재 자산 상태, 원장은 확정된 감사 기록으로 사용합니다.

4. 외부 출금 처리

text

주소 검증 → 견적 → 고객 확인
  → 고유 client_request_id로 생성
  → 응답 유실 시 client_request_id로 복구
  → withdrawal_id를 최종 상태까지 polling

생성 전에 외부 출금 견적을 확인합니다.
생성 요청 전 client_request_id를 영구 저장합니다.
응답이 타임아웃되었다는 이유만으로 재요청하지 않습니다.
두 상태가 COMPLETED이고 tx_hash가 유효할 때만 고객 출금을 완료 처리합니다.

5. 동기화와 대사

다음 리소스별로 cursor를 따로 관리합니다.

외부 입금
계정 출금
계정 원장

입금과 출금 cursor는 신규 레코드를 발견합니다. 이후 상태 변경은 반환하지 않으므로 비최종 레코드는 ID로 polling합니다. Append-only 원장은 cursor로 동기화합니다.

운영 적용 규칙

IMPORTANT

실제 고객 자금을 처리하기 전에 다음 규칙을 적용하십시오.

API Key와 HMAC Key를 모바일 또는 브라우저 클라이언트에 노출하지 않습니다.
모든 지갑 작업을 고객사 백엔드에서 인가하며 account ID만으로 권한을 인정하지 않습니다.
내부·외부 출금 전체에서 client_request_id를 재사용하지 않습니다.
자산 금액은 정수 또는 decimal-safe 연산을 사용합니다.
지역화될 수 있는 message가 아니라 HTTP 상태, error.code, error.action으로 분기합니다.
재시도 횟수를 제한하고 backoff를 적용하며, 생성 요청은 재전송 전에 기존 결과를 복구합니다.
자격 증명을 로그에 남기지 않고 진단용 API request_id를 저장합니다.

전체 스키마와 상태 계약은 Wallet API Reference에서 확인할 수 있습니다.