> ## Documentation Index > Fetch the complete documentation index at: https://docs.hifi.com/llms.txt > Use this file to discover all available pages before exploring further. # 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. ## OpenAPI ````yaml https://production.hifi.com/api/v3/openapi.json post /v3/bridges openapi: 3.0.0 info: title: Hifi API version: 3.0.0 description: API documentation for HIFI servers: - url: https://production.hifi.com description: Production server - url: https://sandbox.hifi.com description: Sandbox server security: - bearerAuth: [] tags: - name: Common description: Common endpoints - name: User description: User endpoints - name: Counter Party description: Counter party endpoints - name: Crypto Transfer description: Crypto transfer and batch transfer endpoints - name: Wallet description: Wallet and wallet offer endpoints - name: External Account description: External bank account endpoints (under a counter party) - name: External Wallet description: External wallet endpoints (under a counter party) - name: External Card description: External card endpoints (under a counter party) - name: Token Swap description: Token swap endpoints - name: Bridge description: Bridge endpoints - name: Virtual Account description: Virtual account endpoints - name: Compliance description: Compliance and compliance link endpoints - name: Webhook Endpoint description: Webhook endpoint endpoints - name: File description: File upload endpoints - name: Onramp description: Onramp (fiat to crypto) endpoints - name: Offramp description: Offramp (crypto to fiat) endpoints - name: Orchestration Address description: Orchestration (liquidation) address endpoints - name: KYC Link description: Hosted and custom KYC/KYB link endpoints - name: Transfer Approval description: Transfer approval endpoints - name: Corridor description: Supported fiat/crypto transfer corridor endpoints - name: Migration description: v2-to-v3 ID mapping endpoints paths: /v3/bridges: post: tags: - Bridge summary: Create a bridge transfer description: > 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. operationId: v3CreateBridge requestBody: $ref: '#/components/requestBodies/CreateBridgeBody' responses: '200': $ref: '#/components/responses/CreateBridgeResponse' '400': $ref: '#/components/responses/BadRequestResponse' '401': $ref: '#/components/responses/UnauthorizedResponse' '409': $ref: '#/components/responses/ConflictResponse' '500': $ref: '#/components/responses/InternalServerErrorResponse' components: requestBodies: CreateBridgeBody: required: true description: > 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`. content: application/json: schema: $ref: '#/components/schemas/BridgeCreate' examples: OwnedWalletExample: summary: Bridge to an owned wallet value: requestId: b3d1f2a4-5c6e-4a7b-8c9d-0e1f2a3b4c5d amount: 100 source: walletId: wlt_1aLcs3Kf9dQ2mNpXwZ7bV currency: USDC destination: walletId: wlt_4mNpXwZ7bV1aLcs3Kf9dQ currency: USDC ExternalWalletExample: summary: Bridge to an external wallet value: requestId: c4e2a3b5-6d7f-4b8c-9d0e-1f2a3b4c5d6e amount: 250 source: walletId: wlt_1aLcs3Kf9dQ2mNpXwZ7bV currency: USDC destination: externalWalletId: extw_4mNpXwZ7bV1aLcs3Kf9dQ currency: USDC RequireApprovalExample: summary: Bridge held for transfer approval value: requestId: d5f3b4c6-7e80-4c9d-8e1f-2a3b4c5d6e7f amount: 50 source: walletId: wlt_1aLcs3Kf9dQ2mNpXwZ7bV currency: USDT destination: walletId: wlt_4mNpXwZ7bV1aLcs3Kf9dQ currency: USDT requireApproval: true responses: CreateBridgeResponse: description: Bridge transfer created successfully. content: application/json: schema: $ref: '#/components/schemas/BridgeObject' example: 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' BadRequestResponse: description: Bad Request — the request was malformed or failed validation. content: application/json: schema: $ref: '#/components/schemas/ApiError' example: 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 UnauthorizedResponse: description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Unauthorized' ConflictResponse: description: >- Conflict — the request collides with the current state of the resource (e.g. idempotency-key reuse with a different payload). content: application/json: schema: $ref: '#/components/schemas/ApiError' example: type: RESOURCE_CONFLICT message: Resource already exists or conflicts with current state InternalServerErrorResponse: description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/InternalServerError' schemas: BridgeCreate: type: object description: Fields required to create a cross-chain bridge transfer. required: - requestId - amount - source - destination properties: requestId: type: string format: uuid description: >- Client-supplied idempotency key (UUID). Reusing a value returns the existing bridge. example: b3d1f2a4-5c6e-4a7b-8c9d-0e1f2a3b4c5d amount: type: number minimum: 0.000001 maximum: 999999999 description: > Amount of the source currency to bridge. When the source or destination currency is `USDT`, the minimum amount is `10`. example: 100 source: $ref: '#/components/schemas/BridgeCreateSource' destination: $ref: '#/components/schemas/BridgeCreateDestination' requireApproval: type: boolean description: >- When true, the bridge is held for transfer approval before execution. example: false BridgeObject: type: object description: A cross-chain bridge transfer. properties: id: type: string description: Public ID of the bridge transfer (prefixed with `brdg_`). example: brdg_9dQ2mNpXwZ7bV1aLcs3Kf requestId: type: string format: uuid description: Client-supplied idempotency key. example: b3d1f2a4-5c6e-4a7b-8c9d-0e1f2a3b4c5d status: type: string enum: - 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: type: string nullable: true example: null error: type: string nullable: true example: null errorDetails: type: string nullable: true example: null amount: type: string example: '100' source: $ref: '#/components/schemas/BridgeSource' destination: $ref: '#/components/schemas/BridgeDestination' receipt: $ref: '#/components/schemas/BridgeReceipt' fee: $ref: '#/components/schemas/BridgeFee' quote: $ref: '#/components/schemas/BridgeQuote' createdAt: type: string format: date-time example: '2026-07-01T10:30:00.000Z' updatedAt: type: string format: date-time example: '2026-07-01T10:30:00.000Z' ApiError: type: object description: >- Standard v3 error shape, returned by validation failures and business-logic errors alike. properties: type: type: string description: >- Machine-readable error type, e.g. VALIDATION_ERROR, ACTION_NOT_ALLOWED, RESOURCE_CONFLICT. example: VALIDATION_ERROR message: type: string description: Human-readable error message. example: One or more fields are invalid or missing. fields: type: array description: >- Present on field-level validation errors. One entry per problem field. items: type: object properties: code: type: string description: Error code related to the field issue. message: type: string description: Error message for the specific issue. field: type: string description: The name of the field that has an issue. Unauthorized: type: object properties: type: type: string description: Unauthorized enum example: UNAUTHORIZED message: type: string description: Unauthorized message example: Authentication required InternalServerError: type: object properties: type: type: string example: INTERNAL_SERVER_ERROR description: Internal server error enum message: type: string example: An internal server error occurred description: Internal server error message BridgeCreateSource: type: object description: Source of the bridge transfer. required: - walletId - currency properties: walletId: type: string description: >- Public ID of the source wallet (prefixed with `wlt_`). Its chain is used as the source chain. example: wlt_1aLcs3Kf9dQ2mNpXwZ7bV currency: type: string enum: - USDC - USDT - PYUSD0 - USDCX - PYUSD description: Source stablecoin. example: USDC BridgeCreateDestination: type: object description: > 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. required: - currency properties: walletId: type: string description: Public ID of the destination owned wallet (prefixed with `wlt_`). example: wlt_4mNpXwZ7bV1aLcs3Kf9dQ externalWalletId: type: string description: >- Public ID of the destination external wallet (prefixed with `extw_`). example: extw_4mNpXwZ7bV1aLcs3Kf9dQ currency: type: string enum: - USDC - USDT - PYUSD0 - USDCX - PYUSD description: Destination stablecoin. example: USDC BridgeSource: type: object description: Resolved source of the bridge transfer. properties: userId: type: string description: Public ID of the source user (prefixed with `usr_`). example: usr_3Kf9dQ2mNpXwZ7bV1aLcs walletId: type: string description: Public ID of the source wallet (prefixed with `wlt_`). example: wlt_1aLcs3Kf9dQ2mNpXwZ7bV currency: type: string enum: - USDC - USDT - PYUSD0 - USDCX - PYUSD example: USDC chain: type: string enum: - ETHEREUM - POLYGON - SOLANA - BASE - ARBITRUM - FLOW_EVM - CANTON - TRON example: POLYGON BridgeDestination: type: object description: >- Resolved destination of the bridge transfer. One of `walletId` or `externalWalletId` is present. properties: userId: type: string nullable: true description: Public ID of the destination user (prefixed with `usr_`). example: usr_7bV1aLcs3Kf9dQ2mNpXwZ walletId: type: string nullable: true description: Public ID of the destination owned wallet (prefixed with `wlt_`). example: wlt_4mNpXwZ7bV1aLcs3Kf9dQ externalWalletId: type: string nullable: true description: >- Public ID of the destination external wallet (prefixed with `extw_`). example: null currency: type: string enum: - USDC - USDT - PYUSD0 - USDCX - PYUSD example: USDC chain: type: string enum: - ETHEREUM - POLYGON - SOLANA - BASE - ARBITRUM - FLOW_EVM - CANTON - TRON example: BASE BridgeReceipt: type: object description: > 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. properties: transactionHash: type: string nullable: true description: Final settlement transaction hash on the destination chain. example: '0x9f2c1a5b7d3e4f6089a0b1c2d3e4f5061728394a5b6c7d8e9f0a1b2c3d4e5f60' operations: type: object additionalProperties: $ref: '#/components/schemas/BridgeReceiptOperation' BridgeFee: type: object nullable: true description: >- Developer fee charged for the bridge transfer, or null when no fee applies. properties: feeId: type: string description: Identifier of the fee record. example: 9c1e2f3a-4b5c-6d7e-8f90-1a2b3c4d5e6f feeType: type: string example: FIXED feeAmount: type: string example: '0.50' feePercent: type: string nullable: true example: null status: type: string description: Charge status of the fee. example: CHARGED transactionHash: type: string nullable: true example: '0x71a2b3c4d5e6f70819202122232425262728292a2b2c2d2e2f3031323334353' failedReason: type: string nullable: true example: null BridgeQuote: type: object description: Quote information for the bridge transfer. properties: sendGross: $ref: '#/components/schemas/BridgeQuoteAmount' sendNet: $ref: '#/components/schemas/BridgeQuoteAmount' railFee: $ref: '#/components/schemas/BridgeQuoteAmount' receiveGross: $ref: '#/components/schemas/BridgeQuoteAmount' receiveNet: $ref: '#/components/schemas/BridgeQuoteAmount' rate: type: string description: Exchange rate applied to the transfer. example: '1' expiresAt: type: string format: date-time nullable: true description: >- When the quote expires. Populated while the bridge has an open quote. example: '2026-07-02T10:30:00.000Z' BridgeReceiptOperation: type: object description: An on-chain operation performed as part of the bridge. properties: transactionHash: type: string nullable: true example: '0x9f2c1a5b7d3e4f6089a0b1c2d3e4f5061728394a5b6c7d8e9f0a1b2c3d4e5f60' userOpHash: type: string nullable: true description: >- User operation hash for account-abstraction transactions, when applicable. example: '0x71a2b3c4d5e6f70819202122232425262728292a2b2c2d2e2f3031323334353' chain: type: string enum: - ETHEREUM - POLYGON - SOLANA - BASE - ARBITRUM - FLOW_EVM - CANTON - TRON nullable: true example: POLYGON BridgeQuoteAmount: type: object description: An amount paired with its currency. properties: amount: type: string example: '100.000000' currency: type: string enum: - USDC - USDT - PYUSD0 - USDCX - PYUSD example: USDC securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT ````