Skip to main content

Request Bridge

POST 

/2.0/wallets/:walletIdx/bridges

This API can be called with a Global Token. Creates a request to bridge an asset from the source wallet to the destination address. After the request is submitted, the Octet scheduler automatically processes the source-chain steps and then, if needed, the destination-chain steps. Track progress with status.

Prerequisites​

  • Only one bridge can be in progress per source wallet.
  • sourceAddress must be the main address of the source wallet.
  • The coin being sent must be added as a token to the source wallet.
  • The source address must hold enough of the source coin to send and enough of the platform coin to cover the source fee.
  • Under the current policy, destinationAddress must be a main address on the destination platform in the same account.
  • The coin being received must be added as a token to the destination wallet.
  • If the source wallet's key management type is multisig (co-managed), encryptedSourceUserKey is also required.
  • If the destination wallet's key management type is multisig (co-managed) and the tunnel requires destination steps (needActivateAddressDestination || needBridgeDestination = true), encryptedDestinationUserKey is also required.
  • If the tunnel requires destination steps, the destination address must hold enough of the destination platform coin to cover the estimated destination fee.

Status​

The Octet scheduler advances the bridge through its steps automatically, and status shows the current step.

statusMeaning
SOURCE_FETCH_KEY_FAILEDFailed to recover the source wallet's multisig key (see "If the multisig key is invalid" below)
DESTINATION_FETCH_KEY_FAILEDFailed to recover the destination wallet's multisig key (see "If the multisig key is invalid" below)
AWAITING_SOURCE_APPROVE_ERC20Waiting to send the ERC20 approve transaction on the source chain
SOURCE_APPROVING_ERC20Source approve transaction broadcast; awaiting confirmation
SOURCE_APPROVE_ERC20_FAILEDSource approve transaction failed
AWAITING_SOURCE_BRIDGEWaiting to send the bridge transaction on the source chain
SOURCE_BRIDGINGSource bridge transaction broadcast; awaiting confirmation
SOURCE_BRIDGE_FAILEDSource bridge transaction failed
AWAITING_DESTINATION_ACTIVATE_ADDRESSWaiting to send the destination address activation transaction
DESTINATION_ACTIVATING_ADDRESSDestination activation transaction broadcast
DESTINATION_ACTIVATE_ADDRESS_FAILEDDestination activation transaction failed
AWAITING_DESTINATION_BRIDGEWaiting to send the destination finalizing transaction (for CCTP, the Circle attestation is polled automatically until it arrives)
DESTINATION_BRIDGINGDestination finalizing transaction broadcast
DESTINATION_BRIDGE_FAILEDDestination finalizing transaction failed
COMPLETEDBridge completed

Default order: approveErc20 → sourceBridge → activateAddressDestination → destinationBridge → completed

Some steps are skipped depending on the tunnel's need* flags. For example, if needApproveErc20Source is false, the bridge skips AWAITING_SOURCE_APPROVE_ERC20 and starts at AWAITING_SOURCE_BRIDGE; if both destination flags are false, the bridge moves to COMPLETED as soon as the source steps finish.

If the multisig key is invalid​

If the private key of a multisig (co-managed) wallet cannot be recovered from its encryptedUserKey, the bridge moves to SOURCE_FETCH_KEY_FAILED or DESTINATION_FETCH_KEY_FAILED. To recover, resubmit the correct encryptedUserKey with the Re-apply Multisig Key API.

Webhooks are sent at certain points during a bridge. All of them are sent for the source wallet (failures in destination steps are also delivered to the source wallet owner), and the payload follows the BRIDGE_1 scheme.

  • COMPLETED_BRIDGE: when the bridge reaches COMPLETED
  • SOURCE_FETCH_KEY_FAILED_BRIDGE: when the bridge moves to SOURCE_FETCH_KEY_FAILED
  • DESTINATION_FETCH_KEY_FAILED_BRIDGE: when the bridge moves to DESTINATION_FETCH_KEY_FAILED

Each webhook is sent only if a webhook of that type is registered on the source wallet.

Request​

Responses​

Success