Requirements to start the flow.
API key
Have an API key (Tutorial here).
Order flow
The process of buying stablecoins on Rio is done through the following steps:1
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 stablecoin it holds as asset and network, for example "asset": "USDC", "network": "polygon". Keep the id from the response, since that is what you pass as settlement.payout.addressId when creating the order.Go to create a new crypto address
2
Create a quote
You can create as many quotes as necessary before creating an order. A quote has two legs: The response tells you what you would get. Check
origin is what you pay and destination is what you receive, and each leg carries its country. Name the fiat you pay in origin.asset, and the stablecoin you want in destination.asset and destination.network. Then set amount on the leg you want to fix: on origin if you know how much fiat you want to spend, or on destination if you know how much stablecoin you want to receive.For example, to spend $1,000,000 MXN on USDC (Ethereum):destination.amount for the stablecoin you will receive, pricingDetails.fees for the fee breakdown 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.Go to create quote endpoint
Learn more about how quotes work
3
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 settlement.payout.addressId field. The quote must not have expired.Go to create order
4
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.Go to check order status
5
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 to the bank account described in settlement.payment.instructions. 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 settlement.payment.instructions, 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.6
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.
Go to confirm payment
7
Wait for funds
Rio will send the funds to your wallet 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.Poll order status or subscribe to webhooks
Go to check order status
Go to register a webhook
Subscribe to
orders webhooks to get order updates pushed to you instead of
polling.Disclaimer: All technical documentation is subject to the terms and
conditions, which apply supplementarily and take precedence over the
documentation.