본문으로 건너뛰기

브릿지 신청

POST 

/2.0/wallets/:walletIdx/bridges

해당 API는 글로벌 토큰으로 호출 가능합니다. source 지갑에서 destination 주소로 자산을 브릿지하는 1건의 요청을 생성합니다. 신청 후엔 옥텟 스케줄러가 source 체인 → (필요 시) destination 체인 순으로 자동 진행하며, 진행 상황은 status로 추적합니다.

사전 조건​

  • source 지갑당 진행 중인 브릿지는 1건만 허용됩니다.
  • sourceAddress는 source 지갑의 대표주소여야 합니다.
  • source 지갑에 보내는 코인이 토큰 추가되어 있어야 합니다.
  • source 주소에 보낼 source 코인 잔액과 source 수수료를 위한 platform coin 잔액이 충분해야 합니다.
  • destinationAddress는 현재 정책상 같은 계정의 destination 플랫폼 대표주소만 가능합니다.
  • destination 지갑에 받는 코인이 토큰 추가되어 있어야 합니다.
  • 보내는 지갑(source)의 키 관리 방식이 멀티시그(공동관리)이면 encryptedSourceUserKey를 함께 보내야 합니다.
  • 받는 지갑(destination)의 키 관리 방식이 멀티시그(공동관리)이고 터널이 destination 단계를 요구하면(needActivateAddressDestination || needBridgeDestination = true) encryptedDestinationUserKey를 함께 보내야 합니다.
  • 터널이 destination 단계를 요구하는 경우 destination 주소의 destination platform coin 잔액이 추정 destination 수수료 이상이어야 합니다.

상태 (status)​

브릿지는 옥텟 스케줄러가 자동으로 단계를 진행하며 현재 위치를 status로 표시합니다.

status의미
SOURCE_FETCH_KEY_FAILEDsource 지갑의 멀티시그 키 복원 실패 (아래 "멀티시그 키가 잘못된 경우" 참고)
DESTINATION_FETCH_KEY_FAILEDdestination 지갑의 멀티시그 키 복원 실패 (아래 "멀티시그 키가 잘못된 경우" 참고)
AWAITING_SOURCE_APPROVE_ERC20source 체인 ERC20 approve 트랜잭션 대기 중
SOURCE_APPROVING_ERC20source approve 트랜잭션 블록체인에 전파됨, 확정 대기
SOURCE_APPROVE_ERC20_FAILEDsource approve 트랜잭션 실패
AWAITING_SOURCE_BRIDGEsource 체인 브릿지 트랜잭션 대기 중
SOURCE_BRIDGINGsource 브릿지 트랜잭션 전파됨, 확정 대기
SOURCE_BRIDGE_FAILEDsource 브릿지 트랜잭션 실패
AWAITING_DESTINATION_ACTIVATE_ADDRESSdestination 주소 활성화 트랜잭션 대기 중
DESTINATION_ACTIVATING_ADDRESSdestination 활성화 트랜잭션 전파됨
DESTINATION_ACTIVATE_ADDRESS_FAILEDdestination 활성화 트랜잭션 실패
AWAITING_DESTINATION_BRIDGEdestination 마무리 트랜잭션 대기 중 (CCTP는 Circle attestation 도착까지 자동 폴링)
DESTINATION_BRIDGINGdestination 마무리 트랜잭션 전파됨
DESTINATION_BRIDGE_FAILEDdestination 마무리 트랜잭션 실패
COMPLETED브릿지 완료

기본 진행 순서: approveErc20 → sourceBridge → activateAddressDestination → destinationBridge → completed

터널의 need* 플래그에 따라 일부 단계는 스킵됩니다. 예를 들어 needApproveErc20Source가 false인 터널은 AWAITING_SOURCE_APPROVE_ERC20을 거치지 않고 AWAITING_SOURCE_BRIDGE부터 시작하며, destination 단계가 둘 다 false이면 source 완료 후 곧바로 COMPLETED가 됩니다.

멀티시그 키가 잘못된 경우​

멀티시그(공동관리) 지갑의 encryptedUserKey로 개인키 복원에 실패하면 브릿지가 SOURCE_FETCH_KEY_FAILED 또는 DESTINATION_FETCH_KEY_FAILED 상태로 전환됩니다. 이 경우 멀티시그 키 재신청 API로 올바른 encryptedUserKey를 재제출해 복구할 수 있습니다.

관련 웹훅​

브릿지 진행 중 특정 시점에 웹훅이 발송됩니다. 발송 대상은 모두 source 지갑 기준이며 (destination 단계 실패 알림도 source 지갑 owner에게 전달됩니다), 페이로드는 BRIDGE_1 스킴을 따릅니다.

  • COMPLETED_BRIDGE: 브릿지가 최종적으로 COMPLETED 상태가 되었을 때
  • SOURCE_FETCH_KEY_FAILED_BRIDGE: 브릿지가 SOURCE_FETCH_KEY_FAILED 상태로 전환되었을 때
  • DESTINATION_FETCH_KEY_FAILED_BRIDGE: 브릿지가 DESTINATION_FETCH_KEY_FAILED 상태로 전환되었을 때

각 웹훅은 source 지갑에 해당 타입으로 등록되어 있어야 발송됩니다.

Request​

Responses​

Success