> ## 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.

# Buy stablecoins

<Warning>
  **v1 (legacy).** This page documents the API before the v2 update. The v1
  format is not enabled for new accounts and must be enabled on your account by
  your account manager. New integrations should use the
  [current documentation](/introduction). To update an existing integration,
  follow the [migration guide](/migration).
</Warning>

### 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

The process of buying stablecoins on Rio is done through the following steps:

<Steps>
  <Step title="Register the deposit 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-currency pair, so you can skip this step if the address is already registered.

    Send the wallet address in the `address` field and the currency it is for in the `crypto` field. Keep the `id` from the response, since that is what you pass as `userAddressId` when creating the order.

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

    <Warning>
      If you are registering a USDC (Stellar) address, check whether your wallet
      requires a memo for deposits. If it does, send it in the `blockchainMemo`
      field. Failure to include the memo will result in the payout not being
      credited to your wallet and your funds may be permanently lost.
    </Warning>
  </Step>

  <Step title="Create a quote">
    You can create as many quotes as necessary before creating an order. Specify what you are buying with the `side`, `crypto`, `fiat` and `country` fields, then specify the size with either `amountFiat`, if you know how much fiat you want to spend, or `amountCrypto`, if you know how much crypto you want to receive.

    For example, to spend \$1,000,000 MXN on USDC:

    ```json theme={null}
    {
      "side": "buy",
      "crypto": "USDC",
      "fiat": "MXN",
      "country": "MX",
      "amountFiat": 1000000
    }
    ```

    The response tells you what you would get. Check `amountCrypto` for the crypto you will receive and `netPrice` for the all-in price including taxes and fees. 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, and the window is short, so read that field rather than assuming a fixed duration.

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

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

  <Step title="Create order">
    Once you are satisfied with a quote, you can create an order for the quoted amount. Pass the quote through the `quoteId` field and the crypto address that should receive the funds through the `userAddressId` field. The quote must not have expired.

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

  <Step title="Wait for the order to be ready to accept 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, and the intermediate statuses do not require any action.

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

  <Step title="Pay for the order (skip if placing the order in our sandbox environment)">
    Please send the amount specified in the `amountFiat` field of the order object to the bank account specified in the `paymentInstructions` field of the order. Do not forget to send the reference.

    The payment instructions are part of the order itself, so there is no separate endpoint to call. Get the order and read its `paymentInstructions` field, which holds `bankName`, `companyName`, `accountNumber`, the `reference` you must include with the transfer, and the country specific identifiers that apply, such as `CLABE` in Mexico or `CCI` in Peru. A transfer that arrives without the reference cannot be matched to your order.
  </Step>

  <Step title="Confirm payment (optional)">
    This final step is only necessary if the payment is made in USD, or if the order was placed in our sandbox environment and you want to simulate a successful payment. Everywhere else Rio detects the incoming transfer on its own.

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

  <Step title="Wait for funds">
    Rio will send the funds to your wallet in the next few minutes. The order ends up in `complete`, and you can see the details of the transfer in its `payoutsSent` field.
  </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="/v1/api-reference/orders/get-order" />

<Card title="Go to register a webhook" icon="arrow-progress" href="/v1/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.