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

# Migrating to v2

> How v1 fields map to v2.

This page lists the fields that changed in the v2 update and how to move an existing integration. The v1 reference is available by switching to **v1 (legacy)** in the version selector.

<Note>
  v2 fields are returned to everyone. v1 fields are only returned to accounts
  where v1 has been enabled, which you can ask your account manager for while
  you migrate. v1 request fields are still accepted, so you can migrate
  responses first and requests second.
</Note>

### <Icon icon="coins" iconType="solid" /> Naming currencies

`crypto` becomes `asset` plus `network`. Fiat codes are unchanged and are `asset` values without a network. The current list is in [supported currencies](/currencies).

| v1 `crypto` | `asset` | `network` |
| :- | :- | :- |
| `USDC` | `USDC` | `ethereum` |
| `USDC_POLYGON_NXTB` | `USDC` | `polygon` |
| `SOL_USDC_PTHX` | `USDC` | `solana` |
| `XLM_USDC_5F3T` | `USDC` | `stellar` |
| `USDC_BASECHAIN_ETH_5I5C` | `USDC` | `base` |
| `USDCE_TEMPO_MXYR` | `USDCe` | `tempo` |
| `EUROC_ETH_F5NG` | `EURC` | `ethereum` |
| `EURC_SOL` | `EURC` | `solana` |
| `EURC_B609K9QB_Y213` | `EURC` | `base` |
| `USDT_ERC20` | `USDT` | `ethereum` |
| `USDT_POLYGON` | `USDT` | `polygon` |
| `TRX_USDT_S2UZ` | `USDT` | `tron` |
| `USDT_BSC` | `USDT` | `bsc` |
| `SOL_USDT_EWAY` | `USDT` | `solana` |

### <Icon icon="file-invoice-dollar" iconType="solid" /> Creating a quote

A buy becomes a quote whose `origin` is fiat and whose `destination` is a stablecoin. A sell is the reverse. The amount you want to fix goes on the matching leg, and exactly one leg carries an `amount`.

<CodeGroup>
  ```json v1 buy theme={null}
  {
    "side": "buy",
    "crypto": "SOL_USDC_PTHX",
    "fiat": "MXN",
    "country": "MX",
    "amountFiat": 1000000
  }
  ```

  ```json v2 buy theme={null}
  {
    "origin": { "asset": "MXN", "amount": 1000000 },
    "destination": { "asset": "USDC", "network": "solana" },
    "country": "MX"
  }
  ```

  ```json v1 sell theme={null}
  {
    "side": "sell",
    "crypto": "SOL_USDC_PTHX",
    "fiat": "MXN",
    "country": "MX",
    "amountCrypto": 150000
  }
  ```

  ```json v2 sell theme={null}
  {
    "origin": { "asset": "USDC", "network": "solana", "amount": 150000 },
    "destination": { "asset": "MXN" },
    "country": "MX"
  }
  ```
</CodeGroup>

Fiat legs must not carry a `network`. The settlement inputs move under a `settlement` object with the same paths the response uses: `twoWaySettlementType` becomes `settlement.timing` and `twoWaySettlementDateOffset` becomes `settlement.valueDateOffset`. Every other request field (`orderType`, `limitNetPrice`, `timeInForceStartsAt`, `timeInForceEndsAt`, `userId`) keeps its name.

When creating an order, the address Rio pays out to is `payoutAddressId` (v1: `userAddressId`).

A stablecoin on both legs is a [swap](/workflows/swap-order), which has no v1 equivalent.

### <Icon icon="table" iconType="solid" /> Quote and order fields

| v1 field | v2 field |
| :- | :- |
| `side` | `flow` (`fiatToCrypto`, `cryptoToFiat`, `cryptoToCrypto`) |
| `crypto`, `fiat` | `origin.asset`, `destination.asset`, plus `settlement.payment.network` or `settlement.payout.network` for the stablecoin leg |
| `country` | `origin.country`, `destination.country` |
| `amountFiat`, `amountCrypto` | `origin.amount`, `destination.amount` |
| `quoteInCrypto` | `fixedLeg` (`origin` or `destination`) |
| `fees` | `pricingDetails.fees[]`, each with `type`, `amount`, `asset` and optional `tax` |
| `twoWaySettlementType` | `settlement.timing` (`default` or `TPlusOffset`) |
| `twoWaySettlementDateOffset` | `settlement.valueDateOffset` |
| `effectiveTwoWaySettlementDateOffset` | `settlement.effectiveValueDateOffset` |
| `twoWaySettlementDate` | `settlement.valueDate` |
| `paymentDueDate`, `paymentInstructions.dueDate` | `settlement.payment.dueDate` |
| `paymentInstructions` | `settlement.payment.instructions` |
| `destinationOfFunds` | `settlement.payout.instructions` |
| `cryptoAddress`, `depositAddress` | `settlement.payout.instructions.blockchainAddress` on a buy, `settlement.payment.instructions.blockchainAddress` on a sell |
| `paymentMethod`, `payoutMethod` | `settlement.payment.rail`, `settlement.payout.rail` (`bankTransfer` or `blockchain`) |
| `payoutAddressId`, `payoutBankAccountId` | `settlement.payout.accountId` |
| `paymentAddressId` | `settlement.payment.accountId` |
| `bulkBankPaymentId`, `bulkCryptoPaymentId` | `settlement.payment.bulkTransferId` |
| `paymentsReceived` | `settlement.payment.transactions[]` |
| `payoutsSent` | `settlement.payout.transactions[]` |
| `amountFiatReceived`, `amountCryptoReceived` | `settlement.payment.amountSettled`, `settlement.payout.amountSettled` |

`id`, `status`, `quoteId`, `userId`, `expiresAt`, `marketPrice`, `netPrice`, `orderType`, `limitNetPrice`, `clientReferenceId`, `notes` and the `createdAt` and `updatedAt` timestamps are unchanged.

Prices are expressed as units of the destination asset per unit of the origin asset, so `destination.amount = origin.amount * netPrice`. Pass `limitNetPrice` in the same orientation.

### <Icon icon="wallet" iconType="solid" /> Addresses, bulk payments and payouts

Crypto addresses and bulk crypto payments are created with `asset` and `network` instead of `crypto`, and return both fields. Their responses still include `crypto`. The memo of a Stellar address is registered in the `memo` field.

Bank accounts, bank payments and bank payouts are unchanged and keep using `fiat`, whose values are the same codes used as fiat `asset` values.

### <Icon icon="magnifying-glass" iconType="solid" /> Filtering and exporting orders

The orders list, the export endpoint and the spot market price accept `asset` and an optional `network` in addition to the `crypto`, `fiat` and `side` filters. The list also accepts `flow`.

### <Icon icon="list-check" iconType="solid" /> Checklist

<Steps>
  <Step title="Read the new fields">
    Switch your parsing of quotes, orders and `orders` webhooks to `flow`, `origin`, `destination`, `pricingDetails` and `settlement` using the table above. You can compare both side by side while v1 fields are enabled on your account.
  </Step>

  <Step title="Send the new fields">
    Replace `side`, `crypto`, `fiat`, `amountFiat` and `amountCrypto` in quote requests with `origin` and `destination` legs, and replace `crypto` with `asset` and `network` when creating addresses and bulk crypto payments.
  </Step>

  <Step title="Drop the v1 fields">
    Once nothing reads them, ask your account manager to disable v1 fields on your account.
  </Step>
</Steps>

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