> ## Documentation Index > Fetch the complete documentation index at: https://docs.vitawallet.io/llms.txt > Use this file to discover all available pages before exploring further. # Create exchange > Create a crypto exchange transaction. This endpoint converts funds between a crypto and a fiat currency (in either direction) or between two cryptocurrencies, directly from your business wallet at the rate retrieved from `GET /crypto_prices`. > **Note:** This endpoint shares a URL with the other transaction creation flows (`vita_sent`, `withdrawal`, `crypto_payout`). The `transactions_type` field is the discriminator — set it to `"exchange"` for a crypto exchange. #### Request Structure | Key | Description | | --- | --- | | `transactions_type` | Must be set to `"exchange"` for a crypto exchange. | | `currency_sent` | Source currency to exchange from (e.g., `"usd"`, `"btc"`, `"usdt"`). Must be active in your wallet. | | `currency_received` | Destination currency to exchange to (e.g., `"btc"`, `"usdt"`, `"usd"`). | | `amount_sent` | Amount to exchange from the source currency (e.g., `100`, `105.65`). | | `order` | Unique order identifier for this exchange transaction. Used as idempotency key. | --- #### Supported Exchange Types | Type | Direction | | --- | --- | | **Fiat → Crypto** | USD, CLP, COP, MXN, ARS → BTC, USDT, USDC | | **Crypto → Fiat** | BTC, USDT, USDC → USD, CLP, COP, MXN, ARS | | **Crypto → Crypto** | BTC ↔ USDT, BTC ↔ USDC, USDT ↔ USDC | > ⚠️ **Not supported:** Fiat → Fiat exchanges (e.g., USD → CLP, COP → MXN) are rejected with a `305` error. At least one of `currency_sent` or `currency_received` must be a cryptocurrency. --- #### Important Considerations ##### Price Validity - Exchange rates come exclusively from `GET /crypto_prices`, which returns a `valid_until` timestamp. - If the price has expired when you submit, the API returns `"Los precios han caducado, por favor intente de nuevo"`. Request `/crypto_prices` again before retrying. - The `rate` returned in the exchange response reflects the price used from the most recent `/crypto_prices` consultation. ##### Balance Requirements - Both the source and destination currencies must be **active** in your wallet. - The source balance must be enough to cover `amount_sent`. ##### Minimum Amount - Each `currency_sent` has a minimum exchange amount. Submitting below the minimum returns an error with `min_exchange_amount` and `min_exchange_currency` so you can present it to the end user. ##### Processing Time - Exchanges settle **instantly** once a valid price is confirmed. ##### Signature Coverage - All exchange parameters — including `transactions_type` — must be included in the signature validation. --- #### Request Example ```json { "transactions_type": "exchange", "currency_sent": "usd", "currency_received": "usdt", "amount_sent": 10, "order": "AAA0008" } ``` #### Quick Recap 1. Confirm crypto exchange is enabled on your business account. 2. Call `GET /api/businesses/crypto_prices` to retrieve the current `_sell` rate and `valid_until`. 3. Verify `amount_sent` meets the minimum for `currency_sent` and that your source balance covers it. 4. Make sure at least one of `currency_sent` / `currency_received` is a cryptocurrency. 5. Generate a unique `order` ID and submit the exchange to `POST /api/businesses/transactions` with `transactions_type: "exchange"` **before `valid_until` expires**. 6. If the response times out, query `GET /api/businesses/transactions?order=` before retrying — never reuse the request with a new `order`. ## OpenAPI ````yaml /openapi.yaml post /api/businesses/transactions openapi: 3.0.0 info: title: Vita Business API description: >- Vita Wallet Business API — integra payins, payouts, exchange, transactions, users y webhooks para operar pagos en LatAm y el mundo. version: 1.0.0 contact: name: Vita Wallet Support url: https://vitawallet.io email: empresas@vitawallet.io servers: - url: https://api.vitawallet.io description: Production - url: https://api.stage.vitawallet.io description: Sandbox security: - xLogin: [] xTransKey: [] xDate: [] hmacSignature: [] tags: - name: Create Payin - name: Direct Payment - name: Exchange - name: Vita Sent - name: Bank Payouts - name: External Crypto Payouts - name: Transactions - name: Users Creation - name: User Information - name: Webhooks externalDocs: url: https://vitawallet.io description: Vita Wallet paths: /api/businesses/transactions: post: tags: - Exchange summary: Create exchange description: >- Create a crypto exchange transaction. This endpoint converts funds between a crypto and a fiat currency (in either direction) or between two cryptocurrencies, directly from your business wallet at the rate retrieved from `GET /crypto_prices`. > **Note:** This endpoint shares a URL with the other transaction creation flows (`vita_sent`, `withdrawal`, `crypto_payout`). The `transactions_type` field is the discriminator — set it to `"exchange"` for a crypto exchange. #### Request Structure | Key | Description | | --- | --- | | `transactions_type` | Must be set to `"exchange"` for a crypto exchange. | | `currency_sent` | Source currency to exchange from (e.g., `"usd"`, `"btc"`, `"usdt"`). Must be active in your wallet. | | `currency_received` | Destination currency to exchange to (e.g., `"btc"`, `"usdt"`, `"usd"`). | | `amount_sent` | Amount to exchange from the source currency (e.g., `100`, `105.65`). | | `order` | Unique order identifier for this exchange transaction. Used as idempotency key. | --- #### Supported Exchange Types | Type | Direction | | --- | --- | | **Fiat → Crypto** | USD, CLP, COP, MXN, ARS → BTC, USDT, USDC | | **Crypto → Fiat** | BTC, USDT, USDC → USD, CLP, COP, MXN, ARS | | **Crypto → Crypto** | BTC ↔ USDT, BTC ↔ USDC, USDT ↔ USDC | > ⚠️ **Not supported:** Fiat → Fiat exchanges (e.g., USD → CLP, COP → MXN) are rejected with a `305` error. At least one of `currency_sent` or `currency_received` must be a cryptocurrency. --- #### Important Considerations ##### Price Validity - Exchange rates come exclusively from `GET /crypto_prices`, which returns a `valid_until` timestamp. - If the price has expired when you submit, the API returns `"Los precios han caducado, por favor intente de nuevo"`. Request `/crypto_prices` again before retrying. - The `rate` returned in the exchange response reflects the price used from the most recent `/crypto_prices` consultation. ##### Balance Requirements - Both the source and destination currencies must be **active** in your wallet. - The source balance must be enough to cover `amount_sent`. ##### Minimum Amount - Each `currency_sent` has a minimum exchange amount. Submitting below the minimum returns an error with `min_exchange_amount` and `min_exchange_currency` so you can present it to the end user. ##### Processing Time - Exchanges settle **instantly** once a valid price is confirmed. ##### Signature Coverage - All exchange parameters — including `transactions_type` — must be included in the signature validation. --- #### Request Example ```json { "transactions_type": "exchange", "currency_sent": "usd", "currency_received": "usdt", "amount_sent": 10, "order": "AAA0008" } ``` #### Quick Recap 1. Confirm crypto exchange is enabled on your business account. 2. Call `GET /api/businesses/crypto_prices` to retrieve the current `_sell` rate and `valid_until`. 3. Verify `amount_sent` meets the minimum for `currency_sent` and that your source balance covers it. 4. Make sure at least one of `currency_sent` / `currency_received` is a cryptocurrency. 5. Generate a unique `order` ID and submit the exchange to `POST /api/businesses/transactions` with `transactions_type: "exchange"` **before `valid_until` expires**. 6. If the response times out, query `GET /api/businesses/transactions?order=` before retrying — never reuse the request with a new `order`. operationId: create-exchange requestBody: content: application/json: schema: type: object required: - transactions_type - currency_sent - currency_received - amount_sent - order properties: transactions_type: type: string enum: - exchange description: Must be `"exchange"` for a crypto exchange transaction. currency_sent: type: string description: >- Source currency (ISO code, lowercase). Must be active in your wallet. example: usd currency_received: type: string description: Destination currency (ISO code, lowercase). example: usdt amount_sent: type: number description: Amount to exchange from the source currency. example: 10 order: type: string description: Unique order identifier (idempotency key). example: AAA0008 example: transactions_type: exchange currency_sent: usd currency_received: usdt amount_sent: 10 order: AAA0008 responses: '200': description: Exchange created successfully. content: application/json: example: id: 7b16a281-450c-40e9-978eedc17483-02273 type: business_transaction attributes: status: completed origin_currency: usd destination_currency: usdt amount_sent: 10 amount_received: 9.96 rate: 0.9965 order: AAA000811 created_at: '2026-04-28T18:51:13.188Z' '400': description: >- Validation error. Common causes include expired prices, Fiat→Fiat exchange, inactive currency, insufficient balance, amount below minimum, or a duplicated `order`. content: application/json: examples: PricesExpired: summary: Prices expired value: error: error: Los precios han caducado, por favor intente de nuevo FiatToFiat: summary: Fiat→Fiat not supported value: error: code: 305 message: At least one currency must be a cryptocurrency InsufficientBalance: summary: Insufficient balance value: error: error: User does not have enough balance for this transaction InactiveCurrency: summary: Inactive currency value: error: error: Undefined exchange price for user MinimumAmount: summary: Below minimum amount value: error: error: >- Invalid amount, you must enter an amount greater than the minimum amount min_exchange_amount: '1000.0' min_exchange_currency: clp OrderUsed: summary: Duplicated order value: error: code: 503 message: Order is used components: securitySchemes: xLogin: type: apiKey in: header name: x-login description: Business xLogin xTransKey: type: apiKey in: header name: x-trans-key description: Business xTransKey xDate: type: apiKey in: header name: x-date description: ISO8601 datetime hmacSignature: type: apiKey in: header name: Authorization description: 'V2-HMAC-SHA256 signature. Example: `V2-HMAC-SHA256, Signature: `' ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.