> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rio.trade/llms.txt
> Use this file to discover all available pages before exploring further.

# Swap stablecoins

> Convert one stablecoin into another, including across networks

### Requirements to start the flow.

<CardGroup cols={2}>
  <Card title="API key" icon="shield-keyhole">
    Have an API key ([Tutorial here](/quickstart#api-key-generation)).
  </Card>
</CardGroup>

### <Icon icon="arrow-progress" iconType="solid" /> Order flow

A swap is a `cryptoToCrypto` order. You send one stablecoin to Rio and receive a different stablecoin, or the same stablecoin on a different network, at the address you registered. The process is done through the following steps:

<Steps>
  <Step title="Register the receiving crypto address">
    Before creating an order, you need to register the crypto address that will receive the funds. This only needs to be done once per address and stablecoin, so you can skip this step if the address is already registered.

    Send the wallet address in the `address` field and the stablecoin it will receive as `asset` and `network`. Keep the `id` from the response, since that is what you pass as `payoutAddressId` when creating the order.

    <Card title="Go to create a new crypto address" icon="square-code" href="/api-reference/address/create-address" />
  </Step>

  <Step title="Create a quote">
    A quote has two legs: `origin` is what you pay and `destination` is what you receive. Both legs of a swap are stablecoins, so each one needs an `asset` and a `network`. Set `amount` on the leg you want to fix: on `origin` if you know how much you want to send, or on `destination` if you know how much you want to receive.

    For example, to swap \$150,000 USDC (Ethereum) into USDC (Solana):

    ```json theme={null}
    {
      "origin": { "asset": "USDC", "network": "ethereum", "amount": 150000 },
      "destination": { "asset": "USDC", "network": "solana" },
      "country": "MX"
    }
    ```

    Or to convert USDT (Tron) into exactly 100,000 USDC (Base):

    ```json theme={null}
    {
      "origin": { "asset": "USDT", "network": "tron" },
      "destination": { "asset": "USDC", "network": "base", "amount": 100000 },
      "country": "MX"
    }
    ```

    The `country` field is required. Both stablecoins must be enabled for trading on their networks, see [supported currencies](/currencies).

    The response has `flow` set to `cryptoToCrypto`. Check `destination.amount` for the stablecoin you will receive, `pricingDetails.fees` for the fee breakdown and `netPrice` for the all-in rate. Keep the `id`, since that is the `quoteId` you pass when creating the order.

    Quotes expire. The `expiresAt` field is the date and time after which the quote can no longer be used to create an order, so read that field rather than assuming a fixed duration.

    <Note>
      Swap quotes do not accept `orderType`, `limitNetPrice`, the `timeInForce`
      fields, `settlement.timing` or `settlement.valueDateOffset`.
    </Note>

    <Card title="Go to create quote endpoint" icon="square-code" href="/api-reference/quotes/create-quote" />

    <Card title="Learn more about how quotes work" icon="file-invoice-dollar" href="/quotes" />
  </Step>

  <Step title="Create order">
    Once you are satisfied with a quote, create an order for the quoted amount. Pass the quote through the `quoteId` field and the address that should receive the funds through the `payoutAddressId` field. The address must hold the same `asset` and `network` as the quote's `destination`, and the quote must not have expired.

    Swap orders do not accept `payoutBankAccountId`, `wireMessage` or the bulk payment ids.

    <Card title="Go to create order" icon="square-code" href="/api-reference/orders/create-order" />
  </Step>

  <Step title="Wait for the order to be ready to accept your payment">
    Poll the order or subscribe to our webhooks. Wait for the order to have a status of `awaitingPayment`. Until then there is nothing for you to do.

    <Card title="Go to check order status" icon="square-code" href="/api-reference/orders/get-order" />
  </Step>

  <Step title="Pay for the order (skip if placing the order in our sandbox environment)">
    Everything about the leg you pay lives under `settlement.payment` on the order. Send the amount in `settlement.payment.amount`, on the network in `settlement.payment.network`, to the address in `settlement.payment.instructions.blockchainAddress`.

    Read the address from each order rather than reusing one you saved earlier, since the address you are given can differ between orders.

    <Warning>
      If you are sending USDC (Stellar), you must include the memo specified in
      `settlement.payment.instructions.blockchainMemo`. Failure to include the
      memo will result in the payment not being credited to your order and your
      funds may be permanently lost.
    </Warning>
  </Step>

  <Step title="Confirm payment (optional)">
    This step is only necessary to simulate a successful payment in our sandbox environment. In production Rio detects the incoming transfer on its own.

    <Card title="Go to confirm payment" icon="square-code" href="/api-reference/crypto-payments/check-crypto-payment" />
  </Step>

  <Step title="Wait for funds">
    Rio will send the stablecoin to the address you registered in the next few minutes. The order ends up in `complete`, `settlement.payout.status` becomes `settled`, and you can see the transaction hash in `settlement.payout.transactions`.
  </Step>
</Steps>

#### <Icon icon="check-to-slot" iconType="solid" /> Poll order status or subscribe to webhooks

<Card title="Go to check order status" icon="square-code" href="/api-reference/orders/get-order" />

<Card title="Go to register a webhook" icon="arrow-progress" href="/workflows/register-webhook">
  Subscribe to `orders` webhooks to get order updates pushed to you instead of
  polling.
</Card>

<Note>
  **Disclaimer**: All technical documentation is subject to the terms and
  conditions, which apply supplementarily and take precedence over the
  documentation.
</Note>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.