Bridges

Create a bridge transfer

Create a cross-chain bridge transfer that moves a stablecoin from a source wallet on one chain to a destination wallet (owned or external) on a different chain. The source and destination chains are derived from the wallets referenced and must be different.

Provide exactly one destination: either destination.walletId (an owned wallet) or destination.externalWalletId (an external wallet). The requestId makes the request idempotent — reusing a requestId returns the existing bridge.

POST

bridges

curl --request POST \
  --url https://production.hifi.com/v3/bridges \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "requestId": "b3d1f2a4-5c6e-4a7b-8c9d-0e1f2a3b4c5d",
  "amount": 100,
  "source": {
    "walletId": "wlt_1aLcs3Kf9dQ2mNpXwZ7bV",
    "currency": "USDC"
  },
  "destination": {
    "walletId": "wlt_4mNpXwZ7bV1aLcs3Kf9dQ",
    "currency": "USDC"
  }
}
'

{
  "id": "brdg_9dQ2mNpXwZ7bV1aLcs3Kf",
  "requestId": "b3d1f2a4-5c6e-4a7b-8c9d-0e1f2a3b4c5d",
  "status": "OPEN_QUOTE",
  "failedReason": null,
  "error": null,
  "errorDetails": null,
  "amount": "100",
  "source": {
    "userId": "usr_3Kf9dQ2mNpXwZ7bV1aLcs",
    "walletId": "wlt_1aLcs3Kf9dQ2mNpXwZ7bV",
    "currency": "USDC",
    "chain": "POLYGON"
  },
  "destination": {
    "userId": "usr_3Kf9dQ2mNpXwZ7bV1aLcs",
    "walletId": "wlt_4mNpXwZ7bV1aLcs3Kf9dQ",
    "externalWalletId": null,
    "currency": "USDC",
    "chain": "BASE"
  },
  "receipt": {
    "transactionHash": null,
    "operations": {}
  },
  "fee": null,
  "quote": {
    "sendGross": {
      "amount": "100.000000",
      "currency": "USDC"
    },
    "sendNet": {
      "amount": "100.000000",
      "currency": "USDC"
    },
    "railFee": {
      "amount": "0",
      "currency": "USDC"
    },
    "receiveGross": {
      "amount": "100.000000",
      "currency": "USDC"
    },
    "receiveNet": {
      "amount": "100.000000",
      "currency": "USDC"
    },
    "rate": "1",
    "expiresAt": "2026-07-02T10:30:00.000Z"
  },
  "createdAt": "2026-07-01T10:30:00.000Z",
  "updatedAt": "2026-07-01T10:30:00.000Z"
}

{
  "type": "VALIDATION_ERROR",
  "message": "One or more fields are invalid or missing.",
  "fields": [
    {
      "code": "invalid_value",
      "message": "Must be a valid email address",
      "field": "email"
    }
  ]
}

{
  "type": "UNAUTHORIZED",
  "message": "Authentication required"
}

{
  "type": "RESOURCE_CONFLICT",
  "message": "Resource already exists or conflicts with current state"
}

{
  "type": "INTERNAL_SERVER_ERROR",
  "message": "An internal server error occurred"
}

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

Bridge transfer details. The source and destination chains are derived from the referenced wallets and must be different. Provide exactly one of destination.walletId or destination.externalWalletId.

Fields required to create a cross-chain bridge transfer.

requestId

string<uuid>

required

Client-supplied idempotency key (UUID). Reusing a value returns the existing bridge.

Example:

"b3d1f2a4-5c6e-4a7b-8c9d-0e1f2a3b4c5d"

amount

number

required

Amount of the source currency to bridge. When the source or destination currency is USDT, the minimum amount is 10.

Required range: 0.000001 <= x <= 999999999

Example:

100

source

object

required

Source of the bridge transfer.

Show child attributes

destination

object

required

Destination of the bridge transfer. Provide exactly one of walletId or externalWalletId. The destination chain is derived from the referenced wallet and must differ from the source chain.

Show child attributes

requireApproval

boolean

When true, the bridge is held for transfer approval before execution.

Example:

false

transferSpeed

enum<string>

default:STANDARD

Settlement speed for USDC bridges. FAST settles in seconds and charges a fee deducted from the transferred amount; STANDARD waits for source-chain finality. Not every source chain offers FAST; when omitted, STANDARD is used. The quote's railFee is the fee for the transfer and receiveNet the amount the destination receives. The quoted fee is also the maximum charged, so the destination is never paid less than receiveNet.

Available options:

FAST,

STANDARD

Example:

"FAST"

Response

Bridge transfer created successfully.

A cross-chain bridge transfer.

string

Public ID of the bridge transfer (prefixed with brdg_).

Example:

"brdg_9dQ2mNpXwZ7bV1aLcs3Kf"

requestId

string<uuid>

Client-supplied idempotency key.

Example:

"b3d1f2a4-5c6e-4a7b-8c9d-0e1f2a3b4c5d"

status

enum<string>

Available options:

NOT_INITIATED,

OPEN_QUOTE,

CREATED,

SOURCE_INITIATED,

SOURCE_PENDING,

SOURCE_PROCESSED,

SOURCE_FAILED,

DESTINATION_INITIATED,

DESTINATION_PENDING,

COMPLETED,

DESTINATION_FAILED,

QUOTE_FAILED,

UNKNOWN,

PENDING_APPROVAL,

APPROVED,

REJECTED,

EXPIRED

Example:

"OPEN_QUOTE"

failedReason

string | null

Example:

null

error

string | null

Example:

null

errorDetails

string | null

Example:

null

amount

string

Example:

"100"

source

object

Resolved source of the bridge transfer.

Show child attributes

destination

object

Resolved destination of the bridge transfer. One of walletId or externalWalletId is present.

Show child attributes

receipt

object

On-chain receipt for the bridge. transactionHash is the final settlement hash. operations contains provider-specific step hashes (for example approve, send, mint, burn, deposit) and is empty until execution begins.

Show child attributes

fee

object | null

Developer fee charged for the bridge transfer, or null when no fee applies.

Show child attributes

quote

object | null

null while the bridge is waiting for approval (PENDING_APPROVAL), and if the approval is rejected or expires. A bridge that requires approval is quoted when it is approved.

Show child attributes

createdAt

string<date-time>

Example:

"2026-07-01T10:30:00.000Z"

updatedAt

string<date-time>

Example:

"2026-07-01T10:30:00.000Z"

⌘I

curl --request POST \
  --url https://production.hifi.com/v3/bridges \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "requestId": "b3d1f2a4-5c6e-4a7b-8c9d-0e1f2a3b4c5d",
  "amount": 100,
  "source": {
    "walletId": "wlt_1aLcs3Kf9dQ2mNpXwZ7bV",
    "currency": "USDC"
  },
  "destination": {
    "walletId": "wlt_4mNpXwZ7bV1aLcs3Kf9dQ",
    "currency": "USDC"
  }
}
'

{
  "id": "brdg_9dQ2mNpXwZ7bV1aLcs3Kf",
  "requestId": "b3d1f2a4-5c6e-4a7b-8c9d-0e1f2a3b4c5d",
  "status": "OPEN_QUOTE",
  "failedReason": null,
  "error": null,
  "errorDetails": null,
  "amount": "100",
  "source": {
    "userId": "usr_3Kf9dQ2mNpXwZ7bV1aLcs",
    "walletId": "wlt_1aLcs3Kf9dQ2mNpXwZ7bV",
    "currency": "USDC",
    "chain": "POLYGON"
  },
  "destination": {
    "userId": "usr_3Kf9dQ2mNpXwZ7bV1aLcs",
    "walletId": "wlt_4mNpXwZ7bV1aLcs3Kf9dQ",
    "externalWalletId": null,
    "currency": "USDC",
    "chain": "BASE"
  },
  "receipt": {
    "transactionHash": null,
    "operations": {}
  },
  "fee": null,
  "quote": {
    "sendGross": {
      "amount": "100.000000",
      "currency": "USDC"
    },
    "sendNet": {
      "amount": "100.000000",
      "currency": "USDC"
    },
    "railFee": {
      "amount": "0",
      "currency": "USDC"
    },
    "receiveGross": {
      "amount": "100.000000",
      "currency": "USDC"
    },
    "receiveNet": {
      "amount": "100.000000",
      "currency": "USDC"
    },
    "rate": "1",
    "expiresAt": "2026-07-02T10:30:00.000Z"
  },
  "createdAt": "2026-07-01T10:30:00.000Z",
  "updatedAt": "2026-07-01T10:30:00.000Z"
}

{
  "type": "VALIDATION_ERROR",
  "message": "One or more fields are invalid or missing.",
  "fields": [
    {
      "code": "invalid_value",
      "message": "Must be a valid email address",
      "field": "email"
    }
  ]
}

{
  "type": "UNAUTHORIZED",
  "message": "Authentication required"
}

{
  "type": "RESOURCE_CONFLICT",
  "message": "Resource already exists or conflicts with current state"
}

{
  "type": "INTERNAL_SERVER_ERROR",
  "message": "An internal server error occurred"
}

Overview

Endpoints

Create a bridge transfer

Authorizations

Body

Response