> ## Documentation Index > Fetch the complete documentation index at: https://apidocs.ripio.com/llms.txt > Use this file to discover all available pages before exploring further. # Execute A Balance Swap From A Promise > Executes a swap using a previously created promise (the `uuid` token returned by `POST /transactions/quotes/`). The swap moves the user's balance: the `from_currency` is debited and, once the underlying trade completes, the `to_currency` is credited. The transaction is created in `PRO` (processing) status and completes asynchronously. The promise must be valid (not expired, not already used) and the account must have enough `from_currency` balance. **How to obtain the required values:** - `promise`: the `uuid` field returned by create_swap_promise. --- **Authorization** - Requires a valid API key. ## OpenAPI ````yaml post /wallet/transactions/swap/ openapi: 3.0.0 info: title: Ripio Gateway description: Ripio API - Services documentation. version: 0.1.0 x-logo: url: https://cwstatic.nyc3.digitaloceanspaces.com/1996/bitcointrade.png servers: - url: https://api.ripio.com description: Production environment security: [] paths: /wallet/transactions/swap/: post: tags: - Ripio Wallet summary: transactions - Execute a balance swap from a promise description: >- Executes a swap using a previously created promise (the `uuid` token returned by `POST /transactions/quotes/`). The swap moves the user's balance: the `from_currency` is debited and, once the underlying trade completes, the `to_currency` is credited. The transaction is created in `PRO` (processing) status and completes asynchronously. The promise must be valid (not expired, not already used) and the account must have enough `from_currency` balance. **How to obtain the required values:** - `promise`: the `uuid` field returned by create_swap_promise. --- **Authorization** - Requires a valid API key. parameters: - in: header name: authorization required: true description: The API key as a string. schema: type: string - in: header name: signature required: true description: >- See the [Generating Signature](/static/api/authentication#generating-signature) section for more details. schema: type: string - in: header name: timestamp required: true description: >- A timestamp in milliseconds. See the [Timestamp Security](/static/api/authentication#timestamp-security) section for more details. schema: type: number - in: header name: timstamp-tolerance required: false description: >- An additional, non-required parameter, that you can send to specify the number of milliseconds after the timestamp for the request to be valid. See the [Timestamp Security](/static/api/authentication#timestamp-security) section for more details. schema: type: number requestBody: content: application/json: schema: properties: promise: description: >- The swap promise token (`uuid`) returned by POST /transactions/quotes/. type: string example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... required: - promise type: object examples: default: value: promise: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... responses: '201': description: '' content: application/json: schema: description: Swap transaction created successfully. properties: error_code: type: string message: type: string data: description: >- Transaction object returned by the transactions list, detail and creation endpoints (`GET /transactions/`, `GET /transactions/{id}/`, and the 201 responses of every `/transactions/{rail}/{action}/` endpoint). All three surfaces share this exact shape. properties: id: description: >- Unique transaction identifier (source: `pk`). Same value returned by list, detail and creation endpoints. type: integer example: 12345 external_id: description: >- External provider reference for this transaction, when applicable. type: string example: null transaction_type: description: Canonical public transaction type. type: string example: withdrawal rail: description: Canonical rail. `null` for `swap`, which has no rail. type: string example: bank status: description: >- Transaction status. `WTG`=waiting, `WTR`=waiting receipt, `PEN`=pending, `PMA`=pending manual approval, `PRO`=processing, `PAP`=partially paid, `COM`=completed, `CAN`=cancelled, `EXP`=expired, `ERR`=error, `REF`=refunded, `REJ`=rejected, `HOLD`=hold, `SUS`=suspended. type: string example: PEN gateway_details: description: >- Extra gateway-specific detail. For `rail=crypto` this is the blockchain network. For `rail=ripio` transfers (`deposit`/`withdrawal`) this is the literal string `"ripio_tag"`. `null` for `swap` (a conversion, not a transfer) and for `bank`/`pix`. type: string example: null transaction_hash: description: >- Blockchain transaction hash, when applicable (crypto transactions). type: string example: null from_currency: description: Currency ticker being debited/converted from. type: string example: ARS to_currency: description: >- Currency ticker being credited/converted to. Equal to `from_currency` for transfers (deposit/withdrawal); different for `swap`. type: string example: ARS fiat_currency: description: >- Fiat currency used to express `amount_fiat`, regardless of `from_currency`/`to_currency`. type: string example: ARS fee_currency: description: >- Currency in which the fee is charged. `null` when no fee applies. type: string example: ARS fee: description: >- Fee amount as a decimal string, in `fee_currency`. `null` when no fee applies. type: string example: '0.00' fee_fiat: description: >- Fee amount expressed in `fiat_currency`, as a decimal string. `null` when no fee applies. type: string example: '0.00' rate: description: >- Exchange rate applied between `from_currency` and `to_currency`, as a decimal string. type: string example: '1' rate_usd: description: >- Exchange rate applied against USD, as a decimal string. type: string example: '1050.00' amount_from: description: >- Amount debited in `from_currency`, as a decimal string. type: string example: '5000.00' amount_to: description: Amount credited in `to_currency`, as a decimal string. type: string example: '5000.00' amount_fiat: description: >- Amount expressed in `fiat_currency`, as a decimal string. type: string example: '5000.00' amount_usd: description: Amount expressed in USD, as a decimal string. type: string example: '4.76' origin: description: >- Origin address/account of the transaction, when applicable. type: string example: null destination: description: >- Destination address/account of the transaction, when applicable (e.g. bank alias, blockchain address, `ripio_tag` handle). type: string example: some.bank.alias tax: description: Tax amount as a decimal string, when applicable. type: string example: null tax_currency: description: Tax currency, when applicable. type: string example: null created_at: description: ISO 8601 timestamp when the transaction was created. type: string example: '2026-04-13T12:00:00Z' updated_at: description: ISO 8601 timestamp of the last update. type: string example: '2026-04-13T12:01:00Z' extra_data: description: >- Allowlisted, per-key additional detail. Only the keys `provider_reference`, `bank_account` and `bank_name` may appear here — internal identifiers such as `person_id`, `person_name`, `user_full_name`, `user_id` or `user_uuid` are NEVER exposed, even if the backend computes them internally. Empty object (`{}`) when no allowlisted key applies. properties: provider_reference: description: >- External payment provider's reference for this transaction. type: string bank_account: description: >- Bank account identifier/alias involved in the transaction. type: string bank_name: description: Name of the bank involved in the transaction. type: string type: object example: bank_account: some.bank.alias required: - id - external_id - transaction_type - rail - status - gateway_details - transaction_hash - from_currency - to_currency - fiat_currency - fee_currency - fee - fee_fiat - rate - rate_usd - amount_from - amount_to - amount_fiat - amount_usd - origin - destination - tax - tax_currency - created_at - updated_at - extra_data type: object type: object example: error_code: null message: null data: id: 12348 external_id: null transaction_type: swap rail: null status: PRO gateway_details: null transaction_hash: null from_currency: BTC to_currency: ARS fiat_currency: ARS fee_currency: ARS fee: '50.00' fee_fiat: '50.00' rate: '65000000.00' rate_usd: '65000.00' amount_from: '0.001' amount_to: '64950.00' amount_fiat: '65000.00' amount_usd: '61.90' origin: null destination: null tax: null tax_currency: null created_at: '2026-04-13T12:00:00Z' updated_at: '2026-04-13T12:01:00Z' extra_data: {} '400': description: '' content: application/json: schema: description: Bad Request — invalid or expired promise token. type: string '401': description: Error response 401 '403': description: '' content: application/json: schema: description: >- Forbidden — missing `trading_write` permission or account not fully operative for crypto. type: string '409': description: '' content: application/json: schema: description: Conflict — promise expired/used or insufficient balance. type: string '503': description: Error response 503 ````