Requirements to start the flow.
API key
Have an API key (Tutorial here).
Limit order flow
Limit orders on Rio allow you to specify a limit net price, which is the all-in price including all taxes and fees that you are targeting. In this walkthrough, we will go through the process of creating a limit buy order.1
Register the deposit crypto address
Before creating a buy 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.Go to create a new crypto address
2
Create a limit order quote
When creating a limit order quote, you need to specify an Unlike market order quotes, limit order quotes do not expire, so there is no time pressure between this step and the next one.
orderType of limit. You also need to specify the limit net price in the limitNetPrice field.For example, to buy USDC with MXN, but only at an all-in price of $18.75 MXN or better:Go to create quote endpoint
The quote response will include a
marketPrice field. This is the mid market price that will trigger the order, calculated backwards from your specified limitNetPrice using your account’s taxes and fees.3
Place the limit order
No extra parameters are needed to create a limit order. Pass the quote through the
quoteId field and the crypto address that should receive the funds through the userAddressId field, the same as you would for a market order.Go to create order endpoint
4
Order enters 'Waiting for target price' status
After placing the limit order, it will enter a status called
awaitingLimitPriceCondition. The order will remain in this status until:- The market organically reaches your target mid market price, OR
- The Rio ops team or one of Rio’s trading algorithms decide to trigger your order early if they can stretch to that price
Go to check order status
5
Order execution and trigger
Once the target price is reached and the order is triggered, you’ll receive an
email notification and the order will continue with the normal order
lifecycle. Wait for the order to have a status of
awaitingPayment.6
Pay for the order
Send the amount specified in the
amountFiat field of the order to the bank
account specified in the paymentInstructions field of the order. Do not
forget to include the reference number, since a transfer that arrives without
it cannot be matched to your order. The payment instructions are part of the
order itself, so get the order and read that field rather than looking for a
separate endpoint.7
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
8
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.Important notes about limit orders
Price protection: You cannot specify a limit order at a price that is
worse than the current mid market price. If you attempt to do so, the system
will automatically adjust the limit net price to what it would be in a market
order.
Price rounding: In limit order quotes, you may notice that the
limitNetPrice is not exactly the same as the netPrice (may differ by a few
decimals). This is due to rounding requirements for banking rails compliance -
for example, we cannot send nor receive 543.46 MXN. Because of this, some net prices are mathematically
impossible. The system ensures the limitNetPrice and netPrice are as close
to identical as mathematically possible.Scheduling orders: You can specify a
timeInForceStartsAt and
timeInForceEndsAt to schedule a limit order to be executed from a specific
time and/or to a specific time. An order waiting for its start time sits in
awaitingTimeInForceToStart, and one that reached its end time without
triggering ends up in timeInForceEnded.Daily re-quoting for T+n orders: For T+n orders, the system will re-quote
the order every day at 12:00 AM in the time zone of the corresponding order
country. This means you may see a new quoteId in the order document as well as
a new
marketPrice field. The limitNetPrice, however, will remain
unchanged. This is to account for any changes in schedule. This does not
affect regular default settlement orders.Order cancellation: You can cancel a limit order while it’s in
awaitingLimitPriceCondition status at any time. Doing so will permanently
cancel and delete the order, so it will no longer be returned when you list
your orders.Go to cancel order
Early execution: While limit orders are primarily triggered when the
market organically reaches your target price, the Rio ops team or one of Rio’s
trading algorithms may decide to trigger your order early if they can achieve
your specified price.
Partial fills: Limit orders can get partially filled. When this happens,
the order gets split into two. The original order gets updated with the new
amount that was filled and the new order has the remainder at the same limit
price. The new order also has a
parentOrderId field that references the
original order.Disclaimer: All technical documentation is subject to the terms and
conditions, which apply supplementarily and take precedence over the
documentation.