연동 순서와 역할
1. GET /v1/config → MetaMask 체인 전환 및 지갑 연결.
2. POST /v1/auth/challenges → personal_sign → POST /v1/auth/verify.
3. POST /v1/authorizations/prepare → 동의 내용 표시 → eth_signTypedData_v4 → submissions(kind: signature).
4. approval-step → eth_sendTransaction → submissions(kind: approval). RESET이면 완료 후 APPROVE를 별도로 요청합니다.
5. POST /v1/transfers → transferId로 결과 조회 → CONFIRMED 확인.
- 유저 토큰: 로그인 후 accessToken. Authorization: Bearer 헤더에 포함. 유효 기간 1시간.
- 운영사 토큰: OPERATOR_API_TOKEN. 회사 서버에서 전송·조회할 때만 사용. 브라우저에 전달하지 않습니다.
- Origin은 등록된 프런트 주소와 일치해야 합니다. challenge/verify에는 반드시 필요합니다.
- 위임은 정확히 365일입니다. 서명 최초 제출은 prepare 후 600초 이내입니다. 토큰 allowance 자체에는 만료가 없습니다.
- 토큰/수신 지갑/실행자는 서버 및 컨트랙트에 고정됩니다. API로 변경할 수 없습니다.
- 테스트 페이지는 사용자 세션으로 자기 지갑의 전송을 요청합니다. 실제 서비스의 자동 전송은 운영사 서버가 동일 API를 호출합니다.
회사 서버에서 전송 요청
아래 예시는 백엔드 전용입니다. 동일 작업을 재시도할 때 본문과 Idempotency-Key를 그대로 유지합니다.
const response = await fetch(`${API_URL}/v1/transfers`, {
method: 'POST',
headers: {
'Authorization': `Bearer ${process.env.OPERATOR_API_TOKEN}`,
'Content-Type': 'application/json',
'Idempotency-Key': 'invoice-2026-0001'
},
body: JSON.stringify({
authorizationId: 'authz_...',
amount: '12.5',
referenceId: 'invoice-2026-0001'
})
});
const result = await response.json();
if (!response.ok) throw new Error(result.error.code);
// 202 = 대기열 등록. 완료는 GET /v1/transfers/{transferId}로 확인.전송 수량은 소수 문자열입니다. JavaScript Number로 변환해 계산하지 마세요. decimals는 /v1/config에서 확인합니다.
상태와 재시도
| 상태 | 처리 |
|---|---|
| QUEUED / SIGNED / SUBMITTED / CONFIRMING | 처리 중. 3초 간격으로 결과 조회. |
| RECONCILING | 전파 여부 또는 nonce 확인 중. 새 결제 요청을 만들지 않음. |
| CONFIRMED | 성공 receipt·PaymentExecuted 이벤트·설정 확인 수 충족. |
| REJECTED | 서명 전 거부. errorCode 확인 후 새 주문을 결정. |
| REVERTED | 온체인 실행 실패. 가스는 사용될 수 있음. |
승인 제출의 NOT_OBSERVED / PENDING은 같은 txHash를 다시 제출하세요. 사용자가 한도를 줄였으면 다시 무제한 승인을 자동 요청하지 않습니다.
401: 재로그인 · 409: 충돌/만료/잔액·한도 등 errorCode 확인 · 422: 서명/트랜잭션 불일치 · 429: Retry-After 준수 · 500: RPC/서버 오류. 전송 생성 응답이 유실되어도 같은 멱등 키로 재시도합니다.
위임 철회 API는 서버 전송을 즉시 중지하고 두 트랜잭션을 준비합니다. transaction은 해당 위임 철회, allowanceRevocationTransaction은 해당 spender의 모든 토큰 승인을 0으로 변경합니다. 둘 다 사용자 지갑 서명이 필요하며, 먼저 전파된 전송은 철회보다 먼저 실행될 수 있습니다.