> ## 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.
# Get orders
**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).
### Requirements to consume the endpoint.
The user must be approved in at least one country.
### Retrieving several orders at once
Use the `ids` parameter to fetch up to 50 specific orders in a single request instead of calling `GET /api/orders/{id}` once per order. Separate the ids with commas.
```bash theme={null}
curl -G https://app.sandbox.rio.trade/api/orders \
-H "x-api-key: $RIO_API_KEY" \
--data-urlencode "ids=b49f4084b96e4fb76f5a496e,765f4084b96e4fb76f5a4fb0"
```
If you are polling order statuses, prefer this over one request per order. It is faster for you and it keeps response times stable for everyone.
When `ids` is present and `limit` is not, the limit defaults to the number of ids you sent, so a single page returns all of them. If you also pass `limit`, that value wins and the results are paginated as usual.
Ids you are not authorized to see are simply not returned, so a response may contain fewer orders than the number of ids you sent. The same applies to ids that do not exist or that fall outside the other filters you sent in the request. Invalid ids, or more than 50 of them, are rejected with a validation error.
## OpenAPI
````yaml v1/api-reference/orders-docs.json get /api/orders
openapi: 3.0.0
info:
version: v1.0.0
title: Orders API (legacy v1)
description: API for managing orders in the Rio platform
servers:
- url: https://app.sandbox.rio.trade
security:
- apiKeyAuth: []
paths:
/api/orders:
get:
summary: Get orders
parameters:
- $ref: '#/components/parameters/userIdQueryParameter'
- $ref: '#/components/parameters/brokerIdQueryParameter'
- $ref: '#/components/parameters/quoteIdQueryParameter'
- $ref: '#/components/parameters/startDateQueryParameter'
- $ref: '#/components/parameters/endDateQueryParameter'
- $ref: '#/components/parameters/fiatQueryParameter'
- $ref: '#/components/parameters/cryptoQueryParameter'
- $ref: '#/components/parameters/sideQueryParameter'
- $ref: '#/components/parameters/statusQueryParameter'
- $ref: '#/components/parameters/countryQueryParameter'
- $ref: '#/components/parameters/pageQueryParameter'
- $ref: '#/components/parameters/limitQueryParameter'
- $ref: '#/components/parameters/clientReferenceIdQueryParameter'
- $ref: '#/components/parameters/idsQueryParameter'
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/responseOrdersSchema'
description: OK
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/unauthorizedSchema'
description: Unauthorized
components:
parameters:
userIdQueryParameter:
name: userId
in: query
description: User id by which you want to filter.
schema:
type: string
example: 665f4084b96e4fb76f5a0e0c
brokerIdQueryParameter:
name: brokerId
in: query
description: Broker id by which you want to filter.
schema:
type: string
example: 655f4084b96e4fb76f5a0e6e
quoteIdQueryParameter:
name: quoteId
in: query
description: Quote id by which you want to filter.
schema:
type: string
example: 765f4084b96e4fb76f5a4fb0
startDateQueryParameter:
name: startDate
in: query
description: Start date by which you want to filter.
schema:
type: string
example: '2024-01-15'
endDateQueryParameter:
name: endDate
in: query
description: End date by which you want to filter.
schema:
type: string
example: '2024-05-30'
fiatQueryParameter:
name: fiat
in: query
description: Fiat by which you want to filter.
schema:
type: string
enum:
- USD
- MXN
- PEN
- COP
cryptoQueryParameter:
name: crypto
in: query
description: Crypto by which you want to filter.
schema:
type: string
enum:
- USDC
- USDC_POLYGON_NXTB
- SOL_USDC_PTHX
- XLM_USDC_5F3T
- USDC_BASECHAIN_ETH_5I5C
- USDCE_TEMPO_MXYR
- USDT_POLYGON
- USDT_ERC20
- TRX_USDT_S2UZ
- USDT_BSC
- SOL_USDT_EWAY
- EUROC_ETH_F5NG
- EURC_SOL
- EURC_B609K9QB_Y213
sideQueryParameter:
name: side
in: query
description: Side by which you want to filter.
schema:
type: string
enum:
- buy
- sell
statusQueryParameter:
name: status
in: query
description: >-
Status by which you want to filter. These are the statuses an order
moves through on a normal flow, and other statuses can be filtered on
depending on the circumstances of the order.
schema:
type: string
enum:
- awaitingTimeInForceToStart
- awaitingLimitPriceCondition
- timeInForceEnded
- created
- addressCheckPassed
- awaitingPayment
- processing
- paid
- incorrectAmountPaid
- sourcingLiquidity
- liquiditySourced
- filled
- complete
- depositAddressCreated
- awaitingBankPayoutDetails
- bankPayoutDetailsAdded
- depositConfirmed
- awaitingPayout
- bankPaymentDetailsAdded
- awaitingAsyncPayment
- awaitingAsyncPayout
- cancelled
- expired
countryQueryParameter:
name: country
in: query
description: Country by which you want to filter.
schema:
enum:
- MX
- PE
- CO
pageQueryParameter:
name: page
in: query
description: Used to specify the current page you want to get in the paging results.
schema:
type: integer
limitQueryParameter:
name: limit
in: query
description: >-
Used to specify the maximum number of records to be returned on a single
page.
schema:
type: integer
clientReferenceIdQueryParameter:
name: clientReferenceId
in: query
description: >-
Client reference ID by which you want to filter. Maximum length: 100
characters.
schema:
type: string
example: 03d5ec9af663fbd39a1fa
maxLength: 100
idsQueryParameter:
name: ids
in: query
description: >-
Comma separated list of order ids to retrieve in a single request. Up to
50 ids. Combines with the other filters and only returns orders you are
authorized to see.
schema:
type: string
example: b49f4084b96e4fb76f5a496e,765f4084b96e4fb76f5a4fb0
schemas:
responseOrdersSchema:
type: array
items:
type: object
properties:
fees:
type: object
description: Object containing detailed information about various fees
properties:
processingFeeFiat:
type: number
description: The processing fee amount in fiat currency
example: 0
transferFeeFiat:
type: number
description: The transfer fee amount in fiat currency
example: 0.17584797034499297
platformFeeFiat:
type: number
description: The platform's fee amount in fiat currency
example: 20
destinationOfFunds:
type: object
description: Details about the destination of funds
properties:
blockchainAddress:
type: string
description: The blockchain address
example: TS9kqAVq4PR7xNoQDJXSP6Kgz8GFbwUbzi
blockchainMemo:
type: string
description: >-
The memo for the blockchain transaction (USDC Stellar orders
only).
example: '1234567890'
accountHolderName:
type: string
description: The account holder name
example: John Doe
accountNumber:
type: string
description: The account number
example: '1234567890'
CCI:
type: string
description: >-
20-digit code used to identify bank accounts, only applies in
Peru
example: '00111233001112345678'
CLABE:
type: string
description: >-
18-digit code used to identify bank accounts, only applies in
Mexico
example: '014027000000000008'
quoteId:
type: string
description: The ID of the quote
example: 6660be85d6c964829d63fd05
userId:
type: string
description: The ID of the user
example: 65a99abb6a92bda6e52bf7af
status:
enum:
- awaitingTimeInForceToStart
- awaitingLimitPriceCondition
- timeInForceEnded
- created
- addressCheckPassed
- awaitingPayment
- processing
- paid
- incorrectAmountPaid
- sourcingLiquidity
- liquiditySourced
- filled
- complete
- depositAddressCreated
- awaitingBankPayoutDetails
- bankPayoutDetailsAdded
- depositConfirmed
- awaitingPayout
- bankPaymentDetailsAdded
- awaitingAsyncPayment
- awaitingAsyncPayout
- cancelled
- expired
description: >-
The status of the order. These are the statuses an order moves
through on a normal flow, and which ones it sees depends on
whether it is a buy or a sell and on whether payment is deferred.
Other statuses can appear depending on the circumstances of the
order.
crypto:
enum:
- USDC
- USDC_POLYGON_NXTB
- SOL_USDC_PTHX
- XLM_USDC_5F3T
- USDC_BASECHAIN_ETH_5I5C
- USDCE_TEMPO_MXYR
- USDT_POLYGON
- USDT_ERC20
- TRX_USDT_S2UZ
- USDT_BSC
- SOL_USDT_EWAY
- EUROC_ETH_F5NG
- EURC_SOL
- EURC_B609K9QB_Y213
description: The type of cryptocurrency used
side:
enum:
- buy
- sell
description: The side of the order
fiat:
enum:
- USD
- MXN
- PEN
- COP
description: The type of fiat currency used
createdAt:
type: string
description: The date and time the order was created
example: '2024-06-05T19:38:20.264Z'
country:
enum:
- MX
- PE
- CO
description: The country of the user
amountFiat:
type: number
description: The total amount in fiat currency involved in the transaction
example: 1000
amountCrypto:
type: number
description: The total amount of cryptocurrency involved in the transaction
example: 55.54
marketPrice:
type: number
description: The price of the cryptocurrency
example: 0.0568673040717
netPrice:
type: number
description: The net price of the cryptocurrency
example: 0.05554
notes:
type: string
description: Additional information or comments related to the order
example: Description Pt.1
payoutBankAccountId:
type: string
description: >-
The unique identifier of the bank account to which the payout will
be sent
example: 660c10c6eb4fbb235708b8e8
expiredQuotes:
type: array
description: Array of identifiers for quotes that have expired
items:
type: string
cryptoAddress:
type: string
description: The blockchain address for the cryptocurrency transaction
example: '0xAf56edF88c429F1D6858f9E47731FF53F6d34D0C'
id:
type: string
description: The unique identifier for the order
example: 6660beaccc4633bc6412318a
payoutAddressId:
type: string
description: The unique identifier of the payout address
example: 673b5cf6302b8444c78dd3d3
attributes:
type: array
description: List of attributes associated with the order
items:
type: string
example:
- fixedPrice
payoutTransferLimit:
type: number
description: The limit for payout transfer
example: 475000
paymentsReceived:
type: array
description: List of payments received
items:
type: object
properties:
amount:
type: number
description: The amount received
example: 100000
accountHolderName:
type: string
description: The name of the account holder
example: John Doe
accountNumber:
type: string
description: The account number
example: null
CCI:
type: string
description: >-
20-digit code used to identify bank accounts, only applies
in Peru
example: null
CLABE:
type: string
description: >-
18-digit code used to identify bank accounts, only applies
in Mexico
example: '123456789012345678'
receivedAt:
type: string
description: The date and time the payment was received
example: '2025-01-10T13:14:42.855Z'
payoutsSent:
type: array
description: List of payouts sent
items:
type: object
properties:
amount:
type: number
description: The amount sent
example: 4748.36
blockchainTxId:
type: string
description: The blockchain transaction ID
example: '0x66ECBd38905CC32249ddd6f4f0B4A3DdDDCbd608'
sentAt:
type: string
description: The date and time the payout was sent
example: '2025-01-10T13:14:48.240Z'
SPEITrackingNumber:
type: string
description: >-
Unique identifier for a SPEI transaction (also known as
clave de rastreo) (sell order only)
CEPLink:
type: string
description: >-
URL to view the CEP generated for the transaction (sell
order only)
reference:
type: string
description: The reference for the payment (sell order only)
paymentInstructions:
type: object
description: >-
Account information for the bank to which funds will be sent to in
a buy order or the blockchain address the funds will be sent to in
a sell order
properties:
dueDate:
type: string
description: The date on which the payment is due.
example: '2024-06-04T15:02:13.097Z'
bankName:
type: string
description: The name of the bank (buy order only)
example: Bank Name
companyName:
type: string
description: The name of the company (buy order only)
example: Company Name
companyAddress:
type: string
description: The address of the company (buy order only)
example: Company Address
bankAddress:
type: string
description: Bank Address (buy order only)
example: Sandbox Bank Address, 12345, Sandbox City, Sandbox Country
accountNumber:
type: string
description: Account Number
reference:
type: string
description: The reference for the payment (buy order only)
example: 9f5676
CLABE:
type: string
description: >-
18-digit code used to identify bank accounts, only applies in
Mexico (buy order only)
example: '01212345678901'
RUC:
type: string
description: >-
Registry containing the identification data of economic
activities in Peru (buy order only)
RFC:
type: string
description: The RFC of the company (buy order only)
example: RBL123456789
CCI:
type: string
description: >-
20-digit code used to identify bank accounts, only applies in
Peru (buy order only)
example: '00111233001112345678'
blockchainAddress:
type: string
description: The blockchain address (sell order only)
example: '0xAf56edF88c429F1D6858f9E47731FF53F6d34D0C'
blockchainMemo:
type: string
description: >-
VERY IMPORTANT: The memo for the blockchain transaction (USDC
Stellar sell orders only). Failure to include the memo will
result in the payment not being credited to your order and
your funds may be permanently lost.
example: '1234567890'
paymentReceivedAt:
type: string
description: The date and time the payment was received
example: '2025-01-10T13:14:42.855Z'
invoice:
type: object
description: order invoice details, only applies to Mexican orders.
properties:
PDFLink:
type: string
description: Link to the invoice pdf file.
XMLLink:
type: string
description: Link to the invoice xml file.
informationalFees:
type: object
description: Informational fees for the order (does not affect quote)
properties:
serviceFeeFiat:
type: number
description: The service fee in the order’s fiat currency
example: 0
serviceFeeFiatTax:
type: number
description: The tax amount on the service fee in the order’s fiat currency
example: 0
twoWaySettlementType:
type: string
description: >-
The type of settlement for the order. `default` means that the
order is settles regularly (usually this means upon receipt of the
payment), while `TPlusOffset` means that the order is settled
after a certain number of business days.
enum:
- default
- TPlusOffset
twoWaySettlementDateOffset:
type: number
description: >-
The number of business days until the order is settled. This is
only applicable for if the `twoWaySettlementType` is
`TPlusOffset`.
example: 1
twoWaySettlementDate:
type: string
description: The date on which the order is settled.
example: '2024-06-04T15:02:13.097Z'
effectiveTwoWaySettlementDateOffset:
type: number
description: >-
The number of billable days until the order is settled. This is
only applicable for if the `twoWaySettlementType` is
`TPlusOffset`.
example: 1
type:
type: string
description: >-
The type of order. `market` means that the order is executed at
the current market price, while `limit` means that the order is
executed at a specified limit net price.
enum:
- market
- limit
limitNetPrice:
type: number
description: >-
Limit price for `limit` orders, expressed like `netPrice` as units
of what you receive per unit of what you pay (crypto per fiat on a
buy, fiat per crypto on a sell). Only applicable when `orderType`
is `limit`.
example: 0.0555
timeInForceStartsAt:
type: string
description: >-
The date and time from which the order is scheduled to be executed
(optional).
example: '2024-06-04T15:02:13.097Z'
timeInForceEndsAt:
type: string
description: >-
The date and time until which the order is scheduled to be
executed (optional).
example: '2024-06-04T15:02:13.097Z'
parentOrderId:
type: string
description: >-
The ID of the parent order. This is only applicable for if the
order was spawned from a partial fill.
example: 6660beaccc4633bc6412318a
unauthorizedSchema:
type: object
properties:
errors:
type: array
items:
type: object
properties:
code:
type: number
example: 19
message:
type: string
example: Not authorized
securitySchemes:
apiKeyAuth:
type: apiKey
in: header
name: x-api-key
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.