Wallet 튜토리얼

Ethereum Sepolia의 USDT를 이용해 수탁형 고객 지갑을 구현합니다. 고객 계정 준비부터 입금 탐지, 잔액·원장 조회와 외부 출금 완료까지 고객용 지갑의 전체 생명주기를 다룹니다.

이 예제는 테스트넷에서 실행합니다. 운영용 메인넷과 테스트 자산을 구분하고, 이용 가능 네트워크는 지원 네트워크에서 확인합니다.

고객→USER 계정→입금 주소→잔액·원장→외부 출금

구현할 흐름

text

Wallet API 연결과 요청 서명
  → 자산과 네트워크 조회
  → 고객 USER 계정 생성 또는 재사용
  → 입금 주소 발급
  → 외부 입금 탐지 및 확정
  → 잔액과 확정 원장 조회
  → 외부 출금 주소 검증·견적·요청
  → 온체인 처리 결과를 최종 상태까지 추적

준비 사항

Node.js, curl, openssl, jq와 BPMG에서 전달받은 Base URL, API Key, HMAC Key를 준비합니다.

bash

export WALLET_BASE_URL='https://{environment-api-host}'
export WALLET_API_KEY='{issued-api-key}'
export WALLET_HMAC_KEY='{issued-hmac-key}'

자격 증명은 Secret Manager에 보관하고 호출 서버 시각을 NTP로 동기화합니다. 서명 요청의 timestamp는 서버 허용 범위 안에 있어야 합니다.

wallet_request

wallet_request는 Wallet API에 HMAC 인증 헤더를 붙여 curl로 요청하는 셸 함수입니다. 호출 형식은 wallet_request <HTTP 메서드> <Base URL을 제외한 경로와 쿼리> [JSON 본문]입니다. 아래 코드 블록 전체를 환경 변수를 설정한 셸에 등록합니다. 이후 단계도 같은 셸에서 실행하며 새 셸에서는 환경 변수와 함수를 다시 설정합니다.

bash

wallet_request() {
  local method="$1"
  local request_path="$2"
  local body="${3-}"
  local timestamp nonce signature
  timestamp="$(node -e 'process.stdout.write(String(Date.now()))')"
  nonce="$(node -e 'process.stdout.write(require("crypto").randomUUID())')"
  signature="$(printf '%s\n\n%s\n\n%s\n\n%s\n\n%s' \
    "$method" "$request_path" "$timestamp" "$nonce" "$body" \
    | openssl dgst -sha256 -hmac "$WALLET_HMAC_KEY" -binary \
    | openssl base64 -A)"

  if [ -n "$body" ]; then
    curl -sS -X "$method" "$WALLET_BASE_URL$request_path" \
      -H "X-API-KEY: $WALLET_API_KEY" \
      -H "X-TIMESTAMP: $timestamp" \
      -H "X-NONCE: $nonce" \
      -H "X-SIGNATURE: $signature" \
      -H 'Content-Type: application/json' \
      --data-raw "$body"
  else
    curl -sS -X "$method" "$WALLET_BASE_URL$request_path" \
      -H "X-API-KEY: $WALLET_API_KEY" \
      -H "X-TIMESTAMP: $timestamp" \
      -H "X-NONCE: $nonce" \
      -H "X-SIGNATURE: $signature"
  fi
}

이 함수는 튜토리얼용입니다. 운영 클라이언트에는 응답 검증, timeout, 안전한 제한 재시도를 추가합니다. 서명 규칙은 HMAC 요청 서명을 확인하십시오.

예제 실행과 응답 확인

각 페이지는 앞 단계에서 저장한 변수를 사용합니다.

변수	준비하는 단계
`CUSTOMER_UID`, `ACCOUNT_ID`	사용자와 지갑 계정 생성
`ASSET_TYPE_ID`, `NETWORK_ID`, `ASSET_DECIMALS`, `DEPOSIT_ADDRESS`	입금 주소 발급
`DEPOSIT_ID`, `LEDGER_ID`	입금·원장 목록에서 조회할 항목 선택
`TO_ADDRESS`, `WITHDRAW_AMOUNT`, `ASSET_ID`, `WITHDRAWAL_REQUEST_ID`, `WITHDRAWAL_ID`	외부 출금 요청

curl -sS는 HTTP 오류에도 JSON을 출력할 수 있고, | jq는 응답 표시용입니다. 각 요청의 HTTP 상태와 success를 확인한 뒤 다음 단계를 실행합니다. 오류나 빈 목록에서 추출한 null을 ID로 사용하지 마십시오. 조회 결과가 예상 자산·네트워크·계정인지도 확인합니다.

셸 변수는 튜토리얼을 이어서 실행하기 위한 임시 저장소입니다. 운영에서는 고객·계정 연결과 업무 요청 ID·거래 ID를 DB에 저장하고, 재시작 시 저장된 값으로 복구합니다.

진행 순서

IMPORTANT

문서의 ID, 주소, 금액은 예시입니다. 실제 연동에서는 대상 환경이 반환한 값과 선택한 네트워크의 올바른 주소를 사용하십시오.

Wallet 튜토리얼 ​

구현할 흐름 ​

준비 사항 ​

wallet_request ​

예제 실행과 응답 확인 ​