Create order

curl --request POST \
  --url https://app.sandbox.rio.trade/api/orders \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "quoteId": "60d5ec9af682fbd39a1fa614",
  "settlement": {
    "payout": {
      "addressId": "50d5ec9af663fbd39a1fa629"
    }
  },
  "clientReferenceId": "my-reference-1234"
}
'

{
  "id": "6660bdefd6c964829d63fcb8",
  "quoteId": "6660bdefd6c964829d63fcb7",
  "userId": "66290ac8bd3903485989f82e",
  "clientReferenceId": "my-reference-1234",
  "status": "awaitingPayment",
  "flow": "fiatToCrypto",
  "origin": {
    "asset": "MXN",
    "amount": 1000,
    "country": "MX"
  },
  "destination": {
    "asset": "USDC",
    "amount": 54.76,
    "country": "MX"
  },
  "fixedLeg": "origin",
  "pricingDetails": {
    "fees": [
      {
        "type": "processing",
        "amount": 20,
        "asset": "MXN",
        "tax": 3.2
      }
    ]
  },
  "settlement": {
    "mode": "deliverable",
    "timing": "default",
    "valueDateOffset": 1,
    "effectiveValueDateOffset": 1,
    "valueDate": "2026-10-12T18:00:00.000Z",
    "payment": {
      "asset": "MXN",
      "amount": 1000,
      "rail": "bankTransfer",
      "network": "polygon",
      "dueDate": "2026-10-12T18:00:00.000Z",
      "status": "awaitingFunds",
      "amountSettled": 0,
      "bankAccountId": "66733d33222710ab2785dc62",
      "addressId": "66733d33222710ab2785dc62",
      "instructions": {
        "blockchainAddress": "0xAf56edF88c429F1D6858f9E47731FF53F6d34D0C",
        "blockchainMemo": "<string>",
        "bankName": "STP",
        "companyName": "Rio Transfer S.A.P.I. de C.V.",
        "companyAddress": "<string>",
        "bankAddress": "<string>",
        "accountHolderName": "John Doe",
        "accountNumber": "99998888",
        "routingNumber": "<string>",
        "reference": "9f5676",
        "CLABE": "646180000000000001",
        "CCI": "<string>",
        "RUC": "<string>",
        "RFC": "RBL123456789",
        "NIT": "<string>",
        "USBankTransferMethod": "wire"
      },
      "transactions": [
        {
          "amount": 1000,
          "createdAt": "2026-10-12T18:00:00.000Z",
          "blockchainTxId": "0x66ec2a9d4e1f6b7c8d9e0f1a2b3c4d5e6f708192a3b4c5d6e7f8091a2b3c4d5e",
          "blockchainAddress": "0xAf56edF88c429F1D6858f9E47731FF53F6d34D0C",
          "SPEITrackingNumber": "TRK20261012001",
          "SPIDTrackingNumber": "<string>",
          "CEPLink": "https://www.banxico.org.mx/cep/",
          "reference": "9f5676",
          "accountHolderName": "John Doe",
          "accountNumber": "<string>",
          "CCI": "<string>",
          "CLABE": "014027000000000008"
        }
      ],
      "bulkBankPaymentId": "<string>",
      "bulkCryptoPaymentId": "<string>"
    },
    "payout": {
      "asset": "USDC",
      "amount": 54.76,
      "rail": "blockchain",
      "network": "polygon",
      "dueDate": "2026-10-12T18:00:00.000Z",
      "status": "awaitingFunds",
      "amountSettled": 0,
      "bankAccountId": "66733d33222710ab2785dc62",
      "addressId": "66733d33222710ab2785dc62",
      "instructions": {
        "blockchainAddress": "0xAf56edF88c429F1D6858f9E47731FF53F6d34D0C",
        "blockchainMemo": "<string>",
        "bankName": "STP",
        "companyName": "Rio Transfer S.A.P.I. de C.V.",
        "companyAddress": "<string>",
        "bankAddress": "<string>",
        "accountHolderName": "John Doe",
        "accountNumber": "99998888",
        "routingNumber": "<string>",
        "reference": "9f5676",
        "CLABE": "646180000000000001",
        "CCI": "<string>",
        "RUC": "<string>",
        "RFC": "RBL123456789",
        "NIT": "<string>",
        "USBankTransferMethod": "wire"
      },
      "transactions": [
        {
          "amount": 1000,
          "createdAt": "2026-10-12T18:00:00.000Z",
          "blockchainTxId": "0x66ec2a9d4e1f6b7c8d9e0f1a2b3c4d5e6f708192a3b4c5d6e7f8091a2b3c4d5e",
          "blockchainAddress": "0xAf56edF88c429F1D6858f9E47731FF53F6d34D0C",
          "SPEITrackingNumber": "TRK20261012001",
          "SPIDTrackingNumber": "<string>",
          "CEPLink": "https://www.banxico.org.mx/cep/",
          "reference": "9f5676",
          "accountHolderName": "John Doe",
          "accountNumber": "<string>",
          "CCI": "<string>",
          "CLABE": "014027000000000008"
        }
      ],
      "bulkBankPaymentId": "<string>",
      "bulkCryptoPaymentId": "<string>"
    }
  },
  "marketPrice": 0.056,
  "netPrice": 0.05476,
  "type": "market",
  "limitNetPrice": 0.0555,
  "timeInForceStartsAt": "2026-10-12T18:00:00.000Z",
  "timeInForceEndsAt": "2026-10-12T18:00:00.000Z",
  "attributes": [
    "fixedPrice"
  ],
  "notes": "Note",
  "payoutTransferLimit": 475000,
  "paymentReceivedAt": "2026-10-12T18:00:00.000Z",
  "expiredQuotes": [],
  "parentOrderId": "<string>",
  "invoice": {
    "PDFLink": "<string>",
    "XMLLink": "<string>"
  },
  "informationalFees": {
    "serviceFeeFiat": 0,
    "serviceFeeFiatTax": 0
  },
  "createdAt": "2026-10-12T18:00:00.000Z"
}

{
  "errors": [
    {
      "code": 19,
      "message": "Not authorized"
    }
  ]
}

POST

api

orders

curl --request POST \
  --url https://app.sandbox.rio.trade/api/orders \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "quoteId": "60d5ec9af682fbd39a1fa614",
  "settlement": {
    "payout": {
      "addressId": "50d5ec9af663fbd39a1fa629"
    }
  },
  "clientReferenceId": "my-reference-1234"
}
'

{
  "id": "6660bdefd6c964829d63fcb8",
  "quoteId": "6660bdefd6c964829d63fcb7",
  "userId": "66290ac8bd3903485989f82e",
  "clientReferenceId": "my-reference-1234",
  "status": "awaitingPayment",
  "flow": "fiatToCrypto",
  "origin": {
    "asset": "MXN",
    "amount": 1000,
    "country": "MX"
  },
  "destination": {
    "asset": "USDC",
    "amount": 54.76,
    "country": "MX"
  },
  "fixedLeg": "origin",
  "pricingDetails": {
    "fees": [
      {
        "type": "processing",
        "amount": 20,
        "asset": "MXN",
        "tax": 3.2
      }
    ]
  },
  "settlement": {
    "mode": "deliverable",
    "timing": "default",
    "valueDateOffset": 1,
    "effectiveValueDateOffset": 1,
    "valueDate": "2026-10-12T18:00:00.000Z",
    "payment": {
      "asset": "MXN",
      "amount": 1000,
      "rail": "bankTransfer",
      "network": "polygon",
      "dueDate": "2026-10-12T18:00:00.000Z",
      "status": "awaitingFunds",
      "amountSettled": 0,
      "bankAccountId": "66733d33222710ab2785dc62",
      "addressId": "66733d33222710ab2785dc62",
      "instructions": {
        "blockchainAddress": "0xAf56edF88c429F1D6858f9E47731FF53F6d34D0C",
        "blockchainMemo": "<string>",
        "bankName": "STP",
        "companyName": "Rio Transfer S.A.P.I. de C.V.",
        "companyAddress": "<string>",
        "bankAddress": "<string>",
        "accountHolderName": "John Doe",
        "accountNumber": "99998888",
        "routingNumber": "<string>",
        "reference": "9f5676",
        "CLABE": "646180000000000001",
        "CCI": "<string>",
        "RUC": "<string>",
        "RFC": "RBL123456789",
        "NIT": "<string>",
        "USBankTransferMethod": "wire"
      },
      "transactions": [
        {
          "amount": 1000,
          "createdAt": "2026-10-12T18:00:00.000Z",
          "blockchainTxId": "0x66ec2a9d4e1f6b7c8d9e0f1a2b3c4d5e6f708192a3b4c5d6e7f8091a2b3c4d5e",
          "blockchainAddress": "0xAf56edF88c429F1D6858f9E47731FF53F6d34D0C",
          "SPEITrackingNumber": "TRK20261012001",
          "SPIDTrackingNumber": "<string>",
          "CEPLink": "https://www.banxico.org.mx/cep/",
          "reference": "9f5676",
          "accountHolderName": "John Doe",
          "accountNumber": "<string>",
          "CCI": "<string>",
          "CLABE": "014027000000000008"
        }
      ],
      "bulkBankPaymentId": "<string>",
      "bulkCryptoPaymentId": "<string>"
    },
    "payout": {
      "asset": "USDC",
      "amount": 54.76,
      "rail": "blockchain",
      "network": "polygon",
      "dueDate": "2026-10-12T18:00:00.000Z",
      "status": "awaitingFunds",
      "amountSettled": 0,
      "bankAccountId": "66733d33222710ab2785dc62",
      "addressId": "66733d33222710ab2785dc62",
      "instructions": {
        "blockchainAddress": "0xAf56edF88c429F1D6858f9E47731FF53F6d34D0C",
        "blockchainMemo": "<string>",
        "bankName": "STP",
        "companyName": "Rio Transfer S.A.P.I. de C.V.",
        "companyAddress": "<string>",
        "bankAddress": "<string>",
        "accountHolderName": "John Doe",
        "accountNumber": "99998888",
        "routingNumber": "<string>",
        "reference": "9f5676",
        "CLABE": "646180000000000001",
        "CCI": "<string>",
        "RUC": "<string>",
        "RFC": "RBL123456789",
        "NIT": "<string>",
        "USBankTransferMethod": "wire"
      },
      "transactions": [
        {
          "amount": 1000,
          "createdAt": "2026-10-12T18:00:00.000Z",
          "blockchainTxId": "0x66ec2a9d4e1f6b7c8d9e0f1a2b3c4d5e6f708192a3b4c5d6e7f8091a2b3c4d5e",
          "blockchainAddress": "0xAf56edF88c429F1D6858f9E47731FF53F6d34D0C",
          "SPEITrackingNumber": "TRK20261012001",
          "SPIDTrackingNumber": "<string>",
          "CEPLink": "https://www.banxico.org.mx/cep/",
          "reference": "9f5676",
          "accountHolderName": "John Doe",
          "accountNumber": "<string>",
          "CCI": "<string>",
          "CLABE": "014027000000000008"
        }
      ],
      "bulkBankPaymentId": "<string>",
      "bulkCryptoPaymentId": "<string>"
    }
  },
  "marketPrice": 0.056,
  "netPrice": 0.05476,
  "type": "market",
  "limitNetPrice": 0.0555,
  "timeInForceStartsAt": "2026-10-12T18:00:00.000Z",
  "timeInForceEndsAt": "2026-10-12T18:00:00.000Z",
  "attributes": [
    "fixedPrice"
  ],
  "notes": "Note",
  "payoutTransferLimit": 475000,
  "paymentReceivedAt": "2026-10-12T18:00:00.000Z",
  "expiredQuotes": [],
  "parentOrderId": "<string>",
  "invoice": {
    "PDFLink": "<string>",
    "XMLLink": "<string>"
  },
  "informationalFees": {
    "serviceFeeFiat": 0,
    "serviceFeeFiatTax": 0
  },
  "createdAt": "2026-10-12T18:00:00.000Z"
}

{
  "errors": [
    {
      "code": 19,
      "message": "Not authorized"
    }
  ]
}

Requirements to consume the endpoint.

Create and modify role

The user must have the role to create and modify.

User approved

The user must be approved in at least one country.

Authorizations

x-api-key

string

header

required

Body

application/json

quoteId

string

required

Id of the quote to book.

Example:

"60d5ec9af682fbd39a1fa614"

settlement

object

Settlement references, named as they are reported in the response.

Show child attributes

clientReferenceId

string

Your own unique reference for tracking this order in your system.

Maximum string length: 100

Example:

"my-reference-1234"

notes

string

Optional note stored on the order for your reference.

Example:

"Note"

Response

Created

string

Id of the order.

Example:

"6660bdefd6c964829d63fcb8"

quoteId

string

Id of the quote the order is priced on. Changes when the order is re-quoted.

Example:

"6660bdefd6c964829d63fcb7"

userId

string

Id of the user the order belongs to.

Example:

"66290ac8bd3903485989f82e"

clientReferenceId

string

Your own reference for the order.

Example:

"my-reference-1234"

status

enum<string>

Current status. These are the statuses an order moves through on a normal flow. Which ones it sees depends on the flow. Other statuses can appear depending on the circumstances of the order.

Available options:

awaitingTimeInForceToStart,

awaitingLimitPriceCondition,

timeInForceEnded,

created,

addressCheckPassed,

awaitingPayment,

processing,

paid,

incorrectAmountPaid,

sourcingLiquidity,

liquiditySourced,

filled,

complete,

depositAddressCreated,

awaitingBankPayoutDetails,

bankPayoutDetailsAdded,

depositConfirmed,

awaitingPayout,

bankPaymentDetailsAdded,

awaitingAsyncPayment,

awaitingAsyncPayout,

cancelled,

expired

Example:

"awaitingPayment"

flow

enum<string>

Direction of the conversion, derived from the two assets. fiatToCrypto buys stablecoins, cryptoToFiat sells them, cryptoToCrypto swaps one stablecoin or network for another.

Available options:

fiatToCrypto,

cryptoToFiat,

cryptoToCrypto

Example:

"fiatToCrypto"

origin

object

What the customer pays. The amount is in the leg's own asset.

Show child attributes

destination

object

What the customer receives. The amount is in the leg's own asset.

Show child attributes

fixedLeg

enum<string>

Which leg's amount you specified. The other leg was derived from the price and fees.

Available options:

origin,

destination

Example:

"origin"

pricingDetails

object

How the destination amount was derived from the origin amount.

Show child attributes

settlement

object

How and when the two legs settle.

Show child attributes

marketPrice

number

Market price at the time the order was created, in units of the destination asset per unit of the origin asset.

Example:

0.056

netPrice

number

Final price including fees and taxes.

Example:

0.05476

type

enum<string>

market executes at the current price, limit waits for limitNetPrice.

Available options:

market,

limit

Example:

"market"

limitNetPrice

number

Limit price for limit orders, expressed like netPrice as units of the destination asset per unit of the origin asset. Only applicable when orderType is limit.

Example:

0.0555

timeInForceStartsAt

string<date-time>

Earliest execution time of a limit order.

Example:

"2026-10-12T18:00:00.000Z"

timeInForceEndsAt

string<date-time>

Latest execution time of a limit order.

Example:

"2026-10-12T18:00:00.000Z"

attributes

string[]

List of attributes associated with the order.

Example:

["fixedPrice"]

notes

string

Notes you attached to the order.

Example:

"Note"

payoutTransferLimit

number

Maximum amount per payout transfer. Larger payouts are split.

Example:

475000

paymentReceivedAt

string<date-time>

When your payment was received.

Example:

"2026-10-12T18:00:00.000Z"

expiredQuotes

string[]

Ids of quotes the order went through before the current one.

Example:

[]

parentOrderId

string

Id of the parent order when this order was spawned from a partial fill.

invoice

object

Invoice details, Mexican orders only.

Show child attributes

informationalFees

object

Informational fees (do not affect the quote).

Show child attributes

createdAt

string<date-time>

Creation time.

Example:

"2026-10-12T18:00:00.000Z"

API Documentation

API List

Create order

Requirements to consume the endpoint.

Create and modify role

User approved

Authorizations

Body

Response

​Requirements to consume the endpoint.

Create and modify role

User approved

Authorizations

Body

Response

Requirements to consume the endpoint.