> ## Documentation Index > Fetch the complete documentation index at: https://docs.ca.cryptoprocessing.com/llms.txt > Use this file to discover all available pages before exploring further. # Withdraw crypto instantly with conversion > Make an [instant withdrawal](/withdrawals#instant-withdrawals) from a cryptocurrency or fiat balance with conversion to cryptocurrency. > [!NOTE] > > CryptoProcessing is required to collect sender data in compliance with local regulations. For more details, see [User data collection](https://docs.ca.cryptoprocessing.com/user-data-collection.md). The `sender_data` and the `end_user_reference` you provide must be associated with the same customer. For every error this endpoint returns and what it means, see [API errors: Withdraw crypto instantly with conversion](https://docs.ca.cryptoprocessing.com/api-reference/errors.md#withdraw-crypto-instantly-with-conversion). ## OpenAPI ````yaml POST /v2/crypto/withdrawal_instant_exchange openapi: 3.1.0 info: title: Merchant Backend V2 version: '1.0' description: Documentation for merchant backend processing endpoints servers: - url: https://app.ca.cryptoprocessing.com/api security: - xProcessingKey: [] tags: - name: Status - name: Balance - name: Currencies - name: Deposit addresses - name: Withdrawal - name: Exchange - name: Invoices - name: Transactions paths: /v2/crypto/withdrawal_instant_exchange: post: tags: - Withdrawal summary: Withdraw BTC with conversion from USD description: >- Make an [instant withdrawal](/withdrawals#instant-withdrawals) from a cryptocurrency or fiat balance with conversion to cryptocurrency. operationId: post-crypto-withdrawal-instant-exchange parameters: - $ref: '#/components/parameters/XProcessingSignatureHeader' requestBody: content: application/json: schema: type: object properties: sender_currency: type: string description: >- Currency to withdraw from your balance — a cryptocurrency or a fiat currency. For a list of all available currencies, see [API currency codes](/api-reference/currency-codes). received_currency: type: string description: >- Cryptocurrency to convert the funds into before sending. It must support [instant withdrawals](/withdrawals#instant-withdrawals), and instant withdrawals must be enabled for your account in this currency. `sender_currency` doesn't need to support instant withdrawals. sender_amount: oneOf: - type: string - type: number description: "Amount to withdraw in `sender_currency`, as a decimal string (for example, `\"500\"`) or a number. For a fiat currency, at most\_2\_decimal places are allowed; for a cryptocurrency, digits after the 8th\_decimal place are dropped." address: type: string description: Cryptocurrency address where you want to send funds. foreign_id: type: string maxLength: 255 description: >- Unique ID of the withdrawal request. It must be unique among your withdrawals and exchanges, and it's case-insensitive. end_user_reference: $ref: '#/components/schemas/end_user_reference.withdrawals' sender_type: $ref: '#/components/schemas/sender_type.withdrawals' sender_data: $ref: '#/components/schemas/sender_data.withdrawals' receiver_type: $ref: '#/components/schemas/receiver_type' receiver_data: $ref: '#/components/schemas/receiver_data' required: - sender_currency - received_currency - sender_amount - address - foreign_id - sender_data - sender_type - receiver_type - end_user_reference examples: Convert USD and withdraw BTC to an individual: value: sender_currency: USD received_currency: BTC sender_amount: '500' address: bc1qvad39lhdk64gymr78szh4zflf8uk5gtzkdh2eq foreign_id: withdrawal_123 end_user_reference: user_12345 sender_type: legal sender_data: legal_name: Example Customer country_of_registration: CAN receiver_type: natural receiver_data: first_name: Chris last_name: Customer date_of_birth: '1970-01-01' Convert USDC and withdraw BTC to a company: value: sender_currency: USDC received_currency: BTC sender_amount: '800' address: bc1qvz5ymwdaydckyuvh039jxnjgwfalm5ckm2am6m foreign_id: withdrawal_124 end_user_reference: user_12345 sender_type: legal sender_data: legal_name: Example Customer country_of_registration: CAN receiver_type: legal receiver_data: legal_name: Example Recipient Ltd country_of_registration: CAN responses: '201': description: Created content: application/json: schema: type: object required: - data properties: data: type: object required: - id - foreign_id - type - status - sender_currency - sender_amount - receiver_currency - receiver_amount properties: id: type: integer description: Transaction ID. foreign_id: type: string description: Unique ID of the withdrawal request. end_user_reference: type: string description: The `end_user_reference` from the request. type: type: string description: 'Transaction type: `withdrawal_instant_exchange`.' status: type: string description: >- Transaction status. A [withdrawal callback](/api-reference/callbacks/withdrawal-callbacks) is sent when the status changes to `pending` (held for approval), `confirmed`, `declined` or `cancelled`. sender_currency: type: string description: Source currency ISO code. sender_amount: type: string description: Withdrawal amount in `sender_currency`. receiver_currency: type: string description: >- Destination currency ISO code (the `received_currency` from the request). receiver_amount: type: string description: >- `0.00000000` in this response: the converted amount isn't known until the exchange is made. The amount sent to the address is in `currency_received` of the [withdrawal callback](/api-reference/callbacks/withdrawal-callbacks). examples: Convert USD and withdraw BTC to an individual: value: data: id: 134702815 foreign_id: withdrawal_123 end_user_reference: user_12345 type: withdrawal_instant_exchange status: processing sender_currency: USD sender_amount: '500.00000000' receiver_currency: BTC receiver_amount: '0.00000000' Convert USDC and withdraw BTC to a company: value: data: id: 134702816 foreign_id: withdrawal_124 end_user_reference: user_12345 type: withdrawal_instant_exchange status: processing sender_currency: USDC sender_amount: '800.00000000' receiver_currency: BTC receiver_amount: '0.00000000' '400': description: Bad Request. content: application/json: schema: $ref: '#/components/schemas/ValidationOrMalformedJson' examples: Missing required field: value: errors: sender_currency: The sender currency field is required. Missing sender_amount: value: errors: sender_amount: The sender amount field is required. Missing foreign_id: value: errors: foreign_id: The foreign id field is required. Sender currency doesn't exist: value: errors: sender_currency: The selected sender currency is invalid. Received currency doesn't exist: value: errors: received_currency: The selected received currency is invalid. Currency not supported for instant withdrawals: value: errors: received_currency: >- Instant withdrawals are not supported for the specified received_currency. Instant withdrawals not enabled for the currency: value: errors: received_currency: Instant withdrawals are disabled for this merchant. Same currency on both sides: value: errors: convert_to: Invalid currency Sender currency not a string: value: errors: sender_currency: The sender currency must be a string. Received currency not a string: value: errors: received_currency: The received currency must be a string. Amount not a number: value: errors: sender_amount: The sender amount must be a number. Amount zero or negative: value: errors: sender_amount: The sender amount must be greater than 0. "Fiat amount with more than\_2\_decimals": value: errors: sender_amount: 'The amount is invalid. Max decimal places allowed: 2' Amount below the minimum: value: errors: amount: The amount must be at least . Not enough balance: value: errors: amount: The requested amount exceeds the available balance. Conversion unavailable for the amount: value: errors: amount: >- Unable to exchange the requested amount at the moment. Specify a smaller amount or try again later. Address not a string: value: errors: address: The address must be a string. Address not valid for the currency: value: errors: address: Invalid address "Foreign ID longer than\_255\_characters": value: errors: foreign_id: The foreign id may not be greater than 255 characters. Foreign ID already used: value: errors: foreign_id: The foreign id has already been taken. Email in the end-user reference: value: errors: end_user_reference: The end user reference must not contain email. End-user reference not a string: value: errors: end_user_reference: The end user reference must be a string. Multiple validation errors: value: errors: sender_currency: The sender currency field is required. received_currency: The received currency field is required. address: The address field is required. Malformed JSON: value: error: Bad content format code: bad_content_format '403': $ref: '#/components/responses/WithdrawalHeaderAuthorization' '422': description: > Unprocessable entity. An internal error occurred during processing. The request was understood but could not be completed. The `errors` field is an array of error messages. The `error_code` is always the string `"internal_error"`. For other causes of this error, see [Internal error](/api-reference/errors#internal-error-422-unprocessable-entity). content: application/json: schema: type: object required: - errors - error_code properties: errors: type: array description: Array of error messages items: type: string error_code: type: string description: Error code identifier examples: Amount as a string in scientific notation: value: errors: - Internal error error_code: internal_error '429': $ref: '#/components/responses/TooManyRequests' components: parameters: XProcessingSignatureHeader: name: X-Processing-Signature in: header required: true description: >- Hex-encoded HMAC-SHA512 signature of the request body, [generated using your secret key](/api-reference/authentication). schema: type: string schemas: end_user_reference.withdrawals: type: string description: > Persistent internal ID of the merchant's customer who initiates the withdrawal. Use the same value for the same customer across all requests. This value must refer to the same customer described in `sender_data`. Do not include personal data, such as the customer's name or email address. Put personal details in `sender_data`. sender_type.withdrawals: type: string enum: - natural - legal description: > Type of the merchant's customer who initiates the withdrawal. The sender must be the same customer identified by `end_user_reference`. Use `natural` if the sender is an individual person and `legal` if the sender is a legal entity. The selected type determines which fields must be included in `sender_data`. sender_data.withdrawals: description: > Must contain the details of the merchant's customer who initiates the withdrawal. Which fields are required depends on `sender_type`. oneOf: - title: Natural person type: object required: - first_name - last_name properties: first_name: type: string maxLength: 255 description: The sender's first name. last_name: type: string maxLength: 255 description: The sender's last name. date_of_birth: type: string description: >- The sender's date of birth, YYYY-MM-DD. Optional for a natural person. - title: Legal entity type: object required: - legal_name - country_of_registration properties: legal_name: type: string maxLength: 255 description: The company's name. country_of_registration: type: string description: >- The company's country of registration (ISO alpha-3 format, three characters). receiver_type: type: string enum: - natural - legal - self description: > Type of the withdrawal recipient. Use `natural` if the recipient is an individual person, `legal` if the recipient is a legal entity, or `self` if the recipient is the same person or legal entity as the sender. The selected type determines whether `receiver_data` is required and which fields it must contain. receiver_data: description: > Details of the withdrawal recipient. Omit this field entirely if `receiver_type` is `self`. Otherwise, which fields are required depends on `receiver_type`. oneOf: - title: Natural person type: object required: - first_name - last_name properties: first_name: type: string description: The recipient's first name. last_name: type: string description: The recipient's last name. date_of_birth: type: string description: >- The recipient's date of birth, YYYY-MM-DD. Optional for a natural person. - title: Legal entity type: object required: - legal_name - country_of_registration properties: legal_name: type: string maxLength: 255 description: The company's name. country_of_registration: type: string description: >- The company's country of registration (ISO alpha-3 format, three characters). ValidationOrMalformedJson: oneOf: - type: object title: ValidationError description: One or more request parameters failed validation. properties: errors: type: object description: > A map of request field names to a human-readable validation error message for that field. The exact set of possible keys and messages is endpoint-specific — see [API errors](/api-reference/errors#errors-by-endpoint) for the full reference. additionalProperties: type: string description: Human-readable validation error message for this field. - type: object title: MalformedJson description: >- The request body is not valid JSON or the Content-Type header is not set to `application/json`. properties: error: type: string code: type: string responses: WithdrawalHeaderAuthorization: description: | Forbidden content: application/json: schema: type: object properties: error: type: string description: Human-readable error message. code: type: string description: Error code. description: >- Invalid or missing headers, the API key does not have access to the endpoint, or withdrawals are disabled for the merchant or the API key. Refer to [Errors](/api-reference/errors#general-errors) for troubleshooting steps. examples: Bad signature header: value: error: Bad signature header code: bad_header_signature API key does not have the required ability: value: error: The API key does not have access to this endpoint. code: api_key_ability_required No signature header: value: error: No signature header code: required_header_signature No key header: value: error: No key header code: required_header_key Withdrawals disabled for your account: value: error: Withdrawal functionality is currently unavailable code: withdrawal_functionality_unavailable Withdrawals disabled for the API key: value: error: Withdrawals are disabled for this API key. code: api_key_withdrawals_disabled TooManyRequests: description: > Too Many Requests You sent too many requests in a short time. The limit is counted per API key, so requests from all your servers that use the same key count together. Wait before you send the request again, increasing the delay if you get `429` again, and handle this error by its status code, not by a particular response body. See [Too many requests](/api-reference/errors#too-many-requests-429-too-many-requests). securitySchemes: xProcessingKey: type: apiKey description: Your [API key](/merchant-administration/generate-and-activate-api-keys). in: header name: X-Processing-Key ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.