> ## 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 batch crypto transfer > Create a batch crypto transfer that moves the same stablecoin from one source wallet to up to 50 destinations, each with its own amount. The chain is derived from the source wallet. Each destination must provide exactly one of `walletId` or `externalWalletId`. `requestId` is an idempotency key: reusing one for an in-flight batch returns a conflict, while reusing one for a settled batch returns the existing transfer. The batch is processed asynchronously after creation. ## OpenAPI ````yaml https://production.hifi.com/api/v3/openapi.json post /v3/batch-transfers 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/batch-transfers: post: tags: - Crypto Transfer summary: Create a batch crypto transfer description: > Create a batch crypto transfer that moves the same stablecoin from one source wallet to up to 50 destinations, each with its own amount. The chain is derived from the source wallet. Each destination must provide exactly one of `walletId` or `externalWalletId`. `requestId` is an idempotency key: reusing one for an in-flight batch returns a conflict, while reusing one for a settled batch returns the existing transfer. The batch is processed asynchronously after creation. operationId: v3CreateBatchCryptoTransfer requestBody: $ref: '#/components/requestBodies/CreateBatchCryptoTransferBody' responses: '200': $ref: '#/components/responses/CreateBatchCryptoTransferResponse' '400': $ref: '#/components/responses/BadRequestResponse' '401': $ref: '#/components/responses/UnauthorizedResponse' '409': $ref: '#/components/responses/ConflictResponse' '500': $ref: '#/components/responses/InternalServerErrorResponse' components: requestBodies: CreateBatchCryptoTransferBody: required: true description: > Batch crypto transfer details. Between 1 and 50 destinations, each with exactly one of `walletId` or `externalWalletId` and its own amount. The chain is derived from the source wallet. content: application/json: schema: $ref: '#/components/schemas/BatchCryptoTransferCreate' examples: BatchExample: summary: Batch transfer to mixed destinations value: requestId: d3a8b2e4-3c4d-4e5f-9012-2b3c4d5e6f70 currency: USDC source: walletId: wlt_1aLcs3Kf9dQ2mNpXwZ7bV destinations: - walletId: wlt_9dQ2mNpXwZ7bV1aLcs3Kf amount: 25 - externalWalletId: extw_4mNpXwZ7bV1aLcs3Kf9dQ amount: 75.5 requireApproval: false responses: CreateBatchCryptoTransferResponse: description: Batch crypto transfer created successfully. content: application/json: schema: $ref: '#/components/schemas/BatchCryptoTransferObject' example: id: bctx_2mNpXwZ7bV1aLcs3Kf9dQ requestId: d3a8b2e4-3c4d-4e5f-9012-2b3c4d5e6f70 currency: USDC status: CREATED failedReason: null source: userId: usr_3Kf9dQ2mNpXwZ7bV1aLcs walletId: wlt_1aLcs3Kf9dQ2mNpXwZ7bV destinations: - userId: usr_7bV1aLcs3Kf9dQ2mNpXwZ walletId: wlt_9dQ2mNpXwZ7bV1aLcs3Kf externalWalletId: null amount: 25 - userId: usr_5Kf9dQ2mNpXwZ7bV1aLcs walletId: null externalWalletId: extw_4mNpXwZ7bV1aLcs3Kf9dQ amount: 75.5 contractAddress: '0x3c499c542cef5e3811e1192ce70d8cc03d5c3359' receipt: transactionHash: null userOpHash: null chain: POLYGON 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: BatchCryptoTransferCreate: type: object description: > Create a batch crypto transfer that sends the same currency from one source wallet to up to 50 destinations, each with its own amount. The `chain` is derived from the source wallet. Each destination must supply exactly one of `walletId` or `externalWalletId`. required: - requestId - currency - source - destinations properties: requestId: type: string format: uuid description: >- Client-supplied idempotency key. Reusing a requestId returns the existing transfer or a conflict. example: b1e6f0c2-1a2b-4c3d-9e8f-0a1b2c3d4e5f currency: type: string enum: - USDC - USDT - USDG - PYUSD - PYUSD0 - USDCX example: USDC source: type: object required: - walletId properties: walletId: type: string description: Public ID of the source wallet (prefixed with `wlt_`). example: wlt_1aLcs3Kf9dQ2mNpXwZ7bV destinations: type: array minItems: 1 maxItems: 50 description: >- Between 1 and 50 destinations. Each item provides exactly one of `walletId` or `externalWalletId` plus an amount. items: type: object required: - amount properties: walletId: type: string description: Public ID of a destination HIFI wallet (prefixed with `wlt_`). example: wlt_9dQ2mNpXwZ7bV1aLcs3Kf externalWalletId: type: string description: >- Public ID of a destination external wallet (prefixed with `extw_`). example: extw_4mNpXwZ7bV1aLcs3Kf9dQ amount: type: number description: Amount to send to this destination, greater than zero. example: 25 requireApproval: type: boolean description: >- When true, the batch transfer is created in a pending-approval state and must be approved before execution. example: false BatchCryptoTransferObject: type: object description: A batch crypto transfer. properties: id: type: string description: Public ID of the batch crypto transfer (prefixed with `bctx_`). example: bctx_2mNpXwZ7bV1aLcs3Kf9dQ requestId: type: string format: uuid description: Client-supplied idempotency key. example: b1e6f0c2-1a2b-4c3d-9e8f-0a1b2c3d4e5f currency: type: string enum: - USDC - USDT - USDG - PYUSD - PYUSD0 - USDCX example: USDC status: type: string enum: - NOT_INITIATED - CREATED - PENDING_APPROVAL - APPROVED - REJECTED - EXPIRED - INITIATED - PENDING - COMPLETED - FAILED - QUOTE_FAILED - OPEN_QUOTE - UNKNOWN - CANCELLED example: CREATED failedReason: type: string nullable: true description: Reason the batch transfer failed, when applicable. example: null source: type: object 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 destinations: type: array items: $ref: '#/components/schemas/BatchCryptoTransferDestination' contractAddress: type: string nullable: true description: Token contract address for the transferred currency. example: '0x3c499c542cef5e3811e1192ce70d8cc03d5c3359' receipt: $ref: '#/components/schemas/BatchCryptoTransferReceipt' chain: type: string description: >- Blockchain the batch transfer settles on, derived from the source wallet. enum: - ETHEREUM - POLYGON - SOLANA - BASE - ARBITRUM - FLOW_EVM - CANTON - TRON - BSC example: POLYGON 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 BatchCryptoTransferDestination: type: object description: A resolved destination within a batch crypto transfer. 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 HIFI wallet (prefixed with `wlt_`). Present for HIFI-wallet destinations. example: wlt_9dQ2mNpXwZ7bV1aLcs3Kf externalWalletId: type: string nullable: true description: >- Public ID of the destination external wallet (prefixed with `extw_`). Present for external-wallet destinations. example: null amount: type: number description: Amount sent to this destination. example: 25 BatchCryptoTransferReceipt: type: object description: >- On-chain settlement references. Fields are null until the batch is submitted on-chain. properties: transactionHash: type: string nullable: true description: On-chain transaction hash. example: '0x9c8f7e6d5c4b3a2918f0e1d2c3b4a5968778695a4b3c2d1e0f9a8b7c6d5e4f30' userOpHash: type: string nullable: true description: User operation hash (for smart-contract wallet transfers). example: '0x1a2b3c4d5e6f70819293a4b5c6d7e8f90a1b2c3d4e5f60718293a4b5c6d7e8f9' securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT ````