<!-- tempo-docs-context -->
> Source: [/docs/routes/fx](https://tempo.com/developers/docs/routes/fx.md)
> Section: [Routes](https://tempo.com/developers/docs/routes.md). Move stablecoins between Tempo and other networks: try a route, set up API access, choose a supported route, quote it, accept deposits or make a transfer, and track delivery. Routes is in beta; see the introduction for access.
> [Documentation index](https://tempo.com/developers/llms.txt) · [Docs skill](https://tempo.com/developers/SKILL.md)

> Tempo MCP: Use `search`, `find_pages`, `read_page`, and `code` at `https://mcp.tempo.xyz` for Tempo and related documentation.
> If an indexed page is missing or reflects an older site, read this site’s [documentation index](https://tempo.com/developers/llms.txt) and Markdown pages directly.

# Swap currencies

Swap a stablecoin in one currency for a stablecoin in another on Tempo, such as OUSD for EURC.e.

An FX route is a [Routes](https://tempo.com/developers/docs/routes) route with both ends on Tempo and a different currency on each end. You quote it, create a transfer, and sign the returned calls, as in [Make a transfer](https://tempo.com/developers/docs/routes/transfers). The source transaction is the swap, so the sender receives the destination stablecoin when it confirms.

:::warning
FX routes fill swaps only from listed accounts. [Contact Tempo](https://tempo.com/contact) to enable a route and set up your organization's account list.
:::

## How FX routes differ

* **Listed senders.** Only accounts on your organization's [account list](https://tempo.com/developers/docs/routes/fx#account-lists-on-fx-routes) can swap. A quote for an unlisted `sender` returns `404`.
* **Same sender and recipient.** The swap pays the account that sends it. Set `recipient` to the `sender` address.
* **Short quotes.** A quote expires within seconds. The swap call carries that expiry and reverts after it.
* **Price in the amounts.** The quoted source and destination amounts include the price. The route adds no separate fee.

## Account lists on FX routes

An account list names the accounts that can swap on one pair of a pool. The pool is the contract that fills an FX route's swaps. A pair is the two stablecoins it swaps.

* **Default list.** Every pool has a default list with sponsor ID `0`. The pool's owner manages it.
* **Organization lists.** A pool can have further lists. Each has its own sponsor ID and its own admin account.

A swap runs under exactly one list, and the sender must be on that list. Your organization uses either the pool's default list or its own list. Tempo saves that choice for each pool and pair when it enables your access. You can't change it through the API.

Routes quotes and creates swaps for your organization's API keys under the saved list. Quote and transfer requests take no list parameter. An organization with no saved list uses the pool's default list.

Once your organization has its own list on a pair, the default list no longer applies to your keys there. An account that's only on the default list gets no quote through your keys on that pair.

## Prepare an FX swap

Before you start, have:

* A Tempo API key with `routes:read`, `routes:write`, and `data:read` from [Set up Routes](https://tempo.com/developers/docs/routes/api-setup).
* An FX route from [Supported routes](https://tempo.com/developers/docs/routes/networks), such as OUSD to EURC.e on Tempo, and its two token addresses.
* The route's pool address. Tempo provides it when it enables your access.
* A signer for a listed account that holds the source stablecoin and a fee token.

Every step also runs from a terminal with curl and jq, as the [FX swap example](https://tempo.com/developers/docs/routes/examples/fx) shows.

## Swap one stablecoin for another

:::steps
### Check the account

Send your pool address and listed account in place of the example's `0xbe05…039e` and `0x2222…2222`. Name the pair by its two token addresses, in either order.

`GET /v1/prop-amms/{address}/accounts/{account}/access`

Read account access by tokens

[API reference](https://tempo.com/developers/docs/api/propamms#getpropammtokensaccountaccess) — request parameters, authentication, and response schema. The examples below use editable sample values.

Requires a [Tempo API key](https://tempo.com/developers/docs/api/console/api-keys). Replace `YOUR_API_KEY` before running this request.

**cURL**

```bash
curl 'https://api.tempo.xyz/v1/prop-amms/0xbe058e1c4df8a4366a387bf595b284246a93039e/accounts/0x2222222222222222222222222222222222222222/access?tokens=0x20c0000000000000000000006a37da5c996874be,0x20c0000000000000000000001621e21f71cf12fb' \
  --header 'tempo-api-key: YOUR_API_KEY'
```

**TypeScript**

```ts
fetch('https://api.tempo.xyz/v1/prop-amms/0xbe058e1c4df8a4366a387bf595b284246a93039e/accounts/0x2222222222222222222222222222222222222222/access?tokens=0x20c0000000000000000000006a37da5c996874be,0x20c0000000000000000000001621e21f71cf12fb', {
  headers: {
    'tempo-api-key': 'YOUR_API_KEY'
  }
})
```

The API checks the account against your organization's saved list. A listed account returns `"member": true`, `"allowed": true`, and `"reason": "allowed"`. Routes runs the same check when it quotes. Otherwise `reason` and `explanation` name what's missing, such as `notListed`.

Without a saved list, the request returns `400` with code `propamm_invalid`. If your organization uses the pool's default list, add `sponsorId=0`.

### Get a quote

Send your listed account as both `sender` and `recipient`, in place of the example's `0x2222…2222`. Amounts are in base units. Routes quotes under your organization's list, so the request names no pool or list.

`GET /v1/routes/transfers/quote`

Quote transfer

[API reference](https://tempo.com/developers/docs/api/routes/transfers#quoteroutestransfer) — request parameters, authentication, and response schema. The examples below use editable sample values.

Requires a [Tempo API key](https://tempo.com/developers/docs/api/console/api-keys). Replace `YOUR_API_KEY` before running this request.

**cURL**

```bash
curl 'https://api.tempo.xyz/v1/routes/transfers/quote?amount=1000000&destinationChain=tempo&destinationToken=0x20c0000000000000000000001621e21f71cf12fb&mode=exactSource&recipient=0x2222222222222222222222222222222222222222&sender=0x2222222222222222222222222222222222222222&sourceChain=tempo&sourceToken=0x20c0000000000000000000006a37da5c996874be' \
  --header 'tempo-api-key: YOUR_API_KEY'
```

**TypeScript**

```ts
fetch('https://api.tempo.xyz/v1/routes/transfers/quote?amount=1000000&destinationChain=tempo&destinationToken=0x20c0000000000000000000001621e21f71cf12fb&mode=exactSource&recipient=0x2222222222222222222222222222222222222222&sender=0x2222222222222222222222222222222222222222&sourceChain=tempo&sourceToken=0x20c0000000000000000000006a37da5c996874be', {
  headers: {
    'tempo-api-key': 'YOUR_API_KEY'
  }
})
```

Show the source amount, the destination amount, and `destinationAmountMin`. Create the transfer before `quote.expiresAt`.

### Create the transfer

Send the same inputs with an [idempotency key](https://tempo.com/developers/docs/routes/api-setup#set-idempotency-keys).

`POST /v1/routes/transfers`

Create transfer

[API reference](https://tempo.com/developers/docs/api/routes/transfers#createroutestransfer) — request parameters, authentication, and response schema. The examples below use editable sample values.

Requires a [Tempo API key](https://tempo.com/developers/docs/api/console/api-keys). Replace `YOUR_API_KEY` before running this request.

**cURL**

```bash
curl https://api.tempo.xyz/v1/routes/transfers \
  --request POST \
  --header 'idempotency-key: routes_01k1c5j8q8p0be6j5v9m6d1e4r' \
  --header 'tempo-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "sourceChain": "tempo",
  "sourceToken": "0x20c0000000000000000000006a37da5c996874be",
  "destinationChain": "tempo",
  "destinationToken": "0x20c0000000000000000000001621e21f71cf12fb",
  "sender": "0x2222222222222222222222222222222222222222",
  "recipient": "0x2222222222222222222222222222222222222222",
  "amount": "1000000",
  "mode": "exactSource"
}'
```

**TypeScript**

```ts
fetch('https://api.tempo.xyz/v1/routes/transfers', {
  method: 'POST',
  headers: {
    'idempotency-key': 'routes_01k1c5j8q8p0be6j5v9m6d1e4r',
    'tempo-api-key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    sourceChain: 'tempo',
    sourceToken: '0x20c0000000000000000000006a37da5c996874be',
    destinationChain: 'tempo',
    destinationToken: '0x20c0000000000000000000001621e21f71cf12fb',
    sender: '0x2222222222222222222222222222222222222222',
    recipient: '0x2222222222222222222222222222222222222222',
    amount: '1000000',
    mode: 'exactSource'
  })
})
```

This request swaps 1 OUSD for EURC.e from one account to itself.

Save the transfer `id` and its `action`. For an exact-source swap, `action.calls` holds two calls. The first approves the source stablecoin. The second swaps it.

### Sign and submit

Submit both calls from the sender account before the transfer's `quote.expiresAt`. Send them as one [Tempo Transaction](https://tempo.com/developers/docs/guide/tempo-transaction) so the approval and the swap land together. [Tempo Wallet](https://tempo.com/developers/docs/accounts/wallets#connect-tempo-wallet) does this for you.

If the swap call reverts after the expiry, create a new transfer from a new quote.

### Register the source transaction

`POST /v1/routes/transfers/{id}/source-transactions`

Register source transaction

[API reference](https://tempo.com/developers/docs/api/routes/transfers#registerroutestransfersourcetransaction) — request parameters, authentication, and response schema. The examples below use editable sample values.

Requires a [Tempo API key](https://tempo.com/developers/docs/api/console/api-keys). Replace `YOUR_API_KEY` before running this request.

**cURL**

```bash
curl https://api.tempo.xyz/v1/routes/transfers/rtr_001785729600000_2ZPE2gvateYEQ0dQslgvkhjx/source-transactions \
  --request POST \
  --header 'tempo-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "transactionHash": "0x5151515151515151515151515151515151515151515151515151515151515151"
}'
```

**TypeScript**

```ts
fetch('https://api.tempo.xyz/v1/routes/transfers/rtr_001785729600000_2ZPE2gvateYEQ0dQslgvkhjx/source-transactions', {
  method: 'POST',
  headers: {
    'tempo-api-key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    transactionHash: '0x5151515151515151515151515151515151515151515151515151515151515151'
  })
})
```

The API checks the swap onchain and links it to the transfer.

### Confirm the swap

`GET /v1/routes/transfers/{id}`

Get transfer

[API reference](https://tempo.com/developers/docs/api/routes/transfers#getroutestransfer) — request parameters, authentication, and response schema. The examples below use editable sample values.

Requires a [Tempo API key](https://tempo.com/developers/docs/api/console/api-keys). Replace `YOUR_API_KEY` before running this request.

**cURL**

```bash
curl https://api.tempo.xyz/v1/routes/transfers/rtr_001785729600000_2ZPE2gvateYEQ0dQslgvkhjx \
  --header 'tempo-api-key: YOUR_API_KEY'
```

**TypeScript**

```ts
fetch('https://api.tempo.xyz/v1/routes/transfers/rtr_001785729600000_2ZPE2gvateYEQ0dQslgvkhjx', {
  headers: {
    'tempo-api-key': 'YOUR_API_KEY'
  }
})
```

Keep the payment pending until `status` is `completed`. Reconcile `destinationAmount` against the account's balance change.
:::

## Manage the account list

A list has one admin account. The admin adds or removes up to 50 accounts in one request. The key needs `propamm:write`, which an organization owner issues.

:::steps
### Prepare the change

Send the list's admin account as `sender`, in place of the example's `0x1111…1111`. Name the pair by its two token addresses, in either order.

`POST /v1/prop-amms/{address}/access/prepare`

Prepare access change

[API reference](https://tempo.com/developers/docs/api/propamms#preparepropammaccess) — request parameters, authentication, and response schema. The examples below use editable sample values.

Requires a [Tempo API key](https://tempo.com/developers/docs/api/console/api-keys). Replace `YOUR_API_KEY` before running this request.

**cURL**

```bash
curl https://api.tempo.xyz/v1/prop-amms/0xbe058e1c4df8a4366a387bf595b284246a93039e/access/prepare \
  --request POST \
  --header 'tempo-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "sender": "0x1111111111111111111111111111111111111111",
  "action": {
    "type": "setMembers",
    "tokens": [
      "0x20c0000000000000000000006a37da5c996874be",
      "0x20c0000000000000000000001621e21f71cf12fb"
    ],
    "accounts": [
      "0x2222222222222222222222222222222222222222"
    ],
    "allowed": true
  }
}'
```

**TypeScript**

```ts
fetch('https://api.tempo.xyz/v1/prop-amms/0xbe058e1c4df8a4366a387bf595b284246a93039e/access/prepare', {
  method: 'POST',
  headers: {
    'tempo-api-key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    sender: '0x1111111111111111111111111111111111111111',
    action: {
      type: 'setMembers',
      tokens: ['0x20c0000000000000000000006a37da5c996874be', '0x20c0000000000000000000001621e21f71cf12fb'],
      accounts: ['0x2222222222222222222222222222222222222222'],
      allowed: true
    }
  })
})
```

The API applies the change to your organization's saved list. It simulates the change and returns an unsigned `transaction`. `effect` names the resolved pair index and sponsor ID, such as `List 1 account(s) on pair 0 under sponsor 5.`

To remove accounts, send the same request with `"allowed": false`.

### Sign and send the transaction

The admin account sends a transaction to `transaction.to` with `transaction.data`. The API doesn't sign or send it.

### Confirm the listing

Repeat the [account check](https://tempo.com/developers/docs/routes/fx#check-the-account) after the transaction confirms. A listed account returns `"allowed": true`.
:::

## Name a pair or list

Requests that omit `sponsorId` use your organization's saved list. Requests with `tokens` resolve the pair from its two token addresses. Name either explicitly when the API can't resolve it, such as a pool with two pairs for the same tokens.

* **Sponsor ID.** Pass `sponsorId` as a decimal string to name a list, such as `"0"` for the pool's default list. The account check takes it as a query parameter. The access change takes it in `action`.
* **Pair index.** Pass `pairIndex` in place of `tokens` in the access change. Send exactly one of the two. The account check takes the pair index in its path.

`GET /v1/prop-amms/{address}/pairs/{pairIndex}/accounts/{account}/access`

Read account access

[API reference](https://tempo.com/developers/docs/api/propamms#getpropammaccountaccess) — request parameters, authentication, and response schema. The examples below use editable sample values.

Requires a [Tempo API key](https://tempo.com/developers/docs/api/console/api-keys). Replace `YOUR_API_KEY` before running this request.

**cURL**

```bash
curl 'https://api.tempo.xyz/v1/prop-amms/0xbe058e1c4df8a4366a387bf595b284246a93039e/pairs/0/accounts/0x2222222222222222222222222222222222222222/access?sponsorId=0' \
  --header 'tempo-api-key: YOUR_API_KEY'
```

**TypeScript**

```ts
fetch('https://api.tempo.xyz/v1/prop-amms/0xbe058e1c4df8a4366a387bf595b284246a93039e/pairs/0/accounts/0x2222222222222222222222222222222222222222/access?sponsorId=0', {
  headers: {
    'tempo-api-key': 'YOUR_API_KEY'
  }
})
```

## Account list errors

An access change the API can't resolve or simulate returns one of these errors. The account check returns the same `400` when your organization has no saved list.

| Status | Code | Cause | Fix |
| --- | --- | --- | --- |
| `400` | `propamm_invalid` | The request omits `sponsorId`, and your organization has no saved list on that pool and pair. | Pass `sponsorId`, or ask Tempo to set the list. |
| `404` | `propamm_not_found` | The pool has no active pair for the two tokens. | Check both token addresses against the route. |
| `409` | `propamm_conflict` | More than one pair swaps the two tokens. | Pass `pairIndex` in place of `tokens`. |
| `409` | `propamm_rejected` | `sender` isn't the list's admin account. | Send the list's admin account as `sender`. |

## FX quote errors

A refused quote returns `404` with code `quote_not_available`. Its `details` name the field to change.

| `details` path | Cause | Fix |
| --- | --- | --- |
| `sender` | The account isn't on your organization's list. | Check the account, then ask the list admin to add it. |
| `recipient` | The recipient differs from the sender. | Set `recipient` to the `sender` address. |
| `amount` | The pool can't fill that size now. | Lower the amount or retry later. |

An FX transfer reports the same [transfer statuses](https://tempo.com/developers/docs/routes/delivery) as other Routes transfers, such as `action-required` when it needs attention.
