> For the complete documentation index, see [llms.txt](https://docs.txn.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.txn.io/exchange/exchange-concept.md).

# Exchange concept

An exchange converts a balance from one of your currency accounts into another: crypto to fiat, fiat to crypto, crypto to crypto, or fiat to fiat wherever a [currency pair](https://docs.txn.io/exchange/listing-exchange-currency-pairs.md) exists. Txn quotes a rate that is guaranteed for 30 seconds; you confirm within that window and both accounts are updated at once.

### Quotes

Every exchange starts with a quote for a fixed amount on one side of the pair.

* [Previewing quote](https://docs.txn.io/exchange/previewing-quote.md) prices the exchange without committing anything. Use it for an estimate screen, or to check an amount against the pair's limits.
* [Creating quote](https://docs.txn.io/exchange/creating-quote.md) locks the rate and the amounts. The quote is valid until `expiresAt`, 30 seconds after creation.
* [Confirming quote](https://docs.txn.io/exchange/confirming-quote.md) executes it. A quote that is not confirmed in time becomes `expired` and nothing moves; create a new one.

The quote states the exact figures: `amountCharged` is what leaves the account charged and `amountReceived` what arrives on the account received. The `rate` is the market rate with your spread applied, and `exchangeFee` is your exchange fee, a percentage of the amount, already included in those two figures. Show them to the end user as they are.

### Accounts

A quote names the account debited (`accountChargedId`) and the account credited (`accountReceivedId`). Pass a [subaccount](https://docs.txn.io/accounts/accounts-concept.md) ID to exchange from or into a subaccount. The account charged must hold `amountCharged` as available balance when you confirm; otherwise the confirmation fails with `account_has_insufficient_balance`.

### Pairs and limits

[Listing exchange currency pairs](https://docs.txn.io/exchange/listing-exchange-currency-pairs.md) returns the pairs available to your company, the direction of each, and the minimum and maximum amount per quote. An amount outside the limits is rejected when the quote is built, with `amount_below_minimum` or `amount_above_maximum`.

### What an exchange produces

Confirming a quote places an order with Txn's liquidity provider and books two transactions in the same moment: a debit on the account charged and a credit on the account received, both `completed`. They appear in each account's [transaction history](https://docs.txn.io/accounts/listing-account-transactions.md) with `transactionType` `ExchangeTransaction`, and [Reading quote](https://docs.txn.io/exchange/reading-quote.md) returns them together with the order in `included[]`.

A quote's `status` is `pending` until it is confirmed, `completed` once executed, `expired` if the window passed, and `failed` in the rare case the order could not be executed. A failed quote can be completed by Txn support.

### Exchanges Txn makes for you

Two other products convert currencies on your behalf: an invoice settled in a currency other than the one it is billed in, and a crypto-to-fiat [channel](https://docs.txn.io/channels/channels-concept.md) deposit. These conversions are priced at the spot rate with your spread at the moment the payment is applied, with no quote window. An invoice conversion appears in [Listing quotes](https://docs.txn.io/exchange/listing-quotes.md) as a quote with no transactions of its own; it carries no exchange fee, since the invoice fee is charged on the invoice.

### Rates

[Reading exchange rates](https://docs.txn.io/exchange/reading-exchange-rates.md) returns the current rate for one pair and [Reading exchange rates in bulk](https://docs.txn.io/exchange/reading-exchange-rates-in-bulk.md) the rates of one currency against every other supported currency. They are indicative: the rate you get is the one on the quote at the moment you create it.

### Webhooks

Txn sends an [exchange webhook](https://docs.txn.io/exchange/exchange-webhooks.md) when a quote you confirmed completes. Conversions Txn makes for invoices produce no exchange webhook; follow the invoice instead.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.txn.io/exchange/exchange-concept.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
