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

# Placing limit orders

<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" /> 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.

<Steps>
  <Step title="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.

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

  <Step title="Create a limit order quote">
    When creating a limit order quote, you need to specify an `orderType` of `limit`. You also need to specify the limit net price in the `limitNetPrice` field. Net prices are always expressed as units of what you receive per unit of what you pay, the same way `netPrice` is reported on every quote. On a buy that is crypto per unit of fiat, on a sell it is fiat per unit of crypto.

    For example, to buy USDC with MXN, but only at an all-in price of 0.0540 USDC per MXN (about 18.52 MXN per USDC) or better:

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

    Unlike market order quotes, limit order quotes do not expire, so there is no time pressure between this step and the next one.

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

    <Note>
      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.
    </Note>
  </Step>

  <Step title="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.

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

  <Step title="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

    You can monitor the order status by polling or subscribing to webhooks. There is nothing for you to do while the order waits, other than cancel it if you change your mind.

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

  <Step title="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`.
  </Step>

  <Step title="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.
  </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="exclamation-triangle" iconType="solid" /> Important notes about limit orders

<Note>
  **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.
</Note>

<Note>
  **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.459 MXN, it would need to be
      rounded to $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.
</Note>

<Note>
  **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`.
</Note>

<Note>
  **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.
</Note>

<Note>
  **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.

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

<Note>
  **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.
</Note>

<Note>
  **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.
</Note>

<Warning>
  **Geographic restriction**: Limit orders cannot be placed in the United
  States.
</Warning>

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