> ## 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 crypto transfer > Create a single crypto transfer that moves a stablecoin from a source wallet to a destination wallet or external wallet. The chain is derived from the source wallet. Provide exactly one of `destination.walletId` or `destination.externalWalletId`. `requestId` is an idempotency key: reusing one for an in-flight transfer returns a conflict, and the transfer is processed asynchronously after creation. ## OpenAPI ````yaml https://production.hifi.com/api/v3/openapi.json post /v3/crypto-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/crypto-transfers: post: tags: - Crypto Transfer summary: Create a crypto transfer description: > Create a single crypto transfer that moves a stablecoin from a source wallet to a destination wallet or external wallet. The chain is derived from the source wallet. Provide exactly one of `destination.walletId` or `destination.externalWalletId`. `requestId` is an idempotency key: reusing one for an in-flight transfer returns a conflict, and the transfer is processed asynchronously after creation. operationId: v3CreateCryptoTransfer requestBody: $ref: '#/components/requestBodies/CreateCryptoTransferBody' responses: '200': $ref: '#/components/responses/CreateCryptoTransferResponse' '400': $ref: '#/components/responses/BadRequestResponse' '401': $ref: '#/components/responses/UnauthorizedResponse' '409': $ref: '#/components/responses/ConflictResponse' '500': $ref: '#/components/responses/InternalServerErrorResponse' components: requestBodies: CreateCryptoTransferBody: required: true description: > Crypto transfer details. Provide exactly one of `destination.walletId` or `destination.externalWalletId`. The chain is derived from the source wallet. content: application/json: schema: $ref: '#/components/schemas/CryptoTransferCreate' examples: InternalWalletExample: summary: Transfer to another HIFI wallet value: requestId: b1e6f0c2-1a2b-4c3d-9e8f-0a1b2c3d4e5f currency: USDC amount: 100.5 source: walletId: wlt_1aLcs3Kf9dQ2mNpXwZ7bV destination: walletId: wlt_9dQ2mNpXwZ7bV1aLcs3Kf requireApproval: false ExternalWalletExample: summary: Transfer to an external wallet value: requestId: c2f7a1d3-2b3c-4d5e-8f90-1a2b3c4d5e6f currency: USDT amount: 50 source: walletId: wlt_1aLcs3Kf9dQ2mNpXwZ7bV destination: externalWalletId: extw_4mNpXwZ7bV1aLcs3Kf9dQ responses: CreateCryptoTransferResponse: description: Crypto transfer created successfully. content: application/json: schema: $ref: '#/components/schemas/CryptoTransferObject' example: id: ctx_3Kf9dQ2mNpXwZ7bV1aLcs requestId: b1e6f0c2-1a2b-4c3d-9e8f-0a1b2c3d4e5f status: CREATED currency: USDC amount: '100.5' failedReason: null source: userId: usr_3Kf9dQ2mNpXwZ7bV1aLcs walletId: wlt_1aLcs3Kf9dQ2mNpXwZ7bV destination: userId: usr_7bV1aLcs3Kf9dQ2mNpXwZ walletId: wlt_9dQ2mNpXwZ7bV1aLcs3Kf externalWalletId: null 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: CryptoTransferCreate: type: object description: > Create a single crypto transfer. The `chain` is derived from the source wallet — it is not supplied in the request. Exactly one of `destination.walletId` or `destination.externalWalletId` must be provided. required: - requestId - currency - amount - source - destination 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 description: Stablecoin to transfer. enum: - USDC - USDT - USDG - PYUSD - PYUSD0 - USDCX example: USDC amount: type: number minimum: 0.000001 maximum: 999999999 description: Amount to transfer, greater than zero. example: 100.5 source: type: object required: - walletId properties: walletId: type: string description: Public ID of the source wallet (prefixed with `wlt_`). example: wlt_1aLcs3Kf9dQ2mNpXwZ7bV destination: type: object description: Provide exactly one of `walletId` or `externalWalletId`. 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 requireApproval: type: boolean description: >- When true, the transfer is created in a pending-approval state and must be approved before execution. example: false CryptoTransferObject: type: object description: A single crypto transfer. properties: id: type: string description: Public ID of the crypto transfer (prefixed with `ctx_`). example: ctx_3Kf9dQ2mNpXwZ7bV1aLcs requestId: type: string format: uuid description: Client-supplied idempotency key. example: b1e6f0c2-1a2b-4c3d-9e8f-0a1b2c3d4e5f status: type: string enum: - NOT_INITIATED - CREATED - PENDING_APPROVAL - APPROVED - REJECTED - EXPIRED - INITIATED - PENDING - COMPLETED - FAILED - QUOTE_FAILED - OPEN_QUOTE - UNKNOWN - CANCELLED example: CREATED currency: type: string enum: - USDC - USDT - USDG - PYUSD - PYUSD0 - USDCX example: USDC amount: type: string description: Transfer amount as a string. example: '100.5' failedReason: type: string nullable: true description: Reason the 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 destination: type: object properties: userId: type: string nullable: true description: >- Public ID of the destination user (prefixed with `usr_`). Null for external-wallet destinations without an associated user. example: usr_7bV1aLcs3Kf9dQ2mNpXwZ walletId: type: string nullable: true description: >- Public ID of the destination HIFI wallet (prefixed with `wlt_`). Null when the destination is an external wallet. example: wlt_9dQ2mNpXwZ7bV1aLcs3Kf externalWalletId: type: string nullable: true description: >- Public ID of the destination external wallet (prefixed with `extw_`). Null when the destination is a HIFI wallet. example: null contractAddress: type: string nullable: true description: Token contract address for the transferred currency. example: '0x3c499c542cef5e3811e1192ce70d8cc03d5c3359' receipt: $ref: '#/components/schemas/CryptoTransferReceipt' chain: type: string description: Blockchain the 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 CryptoTransferReceipt: type: object description: >- On-chain settlement references. Fields are null until the transfer 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 ````