> ## Documentation Index
> Fetch the complete documentation index at: https://docs.crown-brlv.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Asset Conversions

> Learn how to convert between different assets using the Crown API

## Overview

Converting assets with Crown API is a two-step process:

1. **Create a quote** between two assets to get exchange rates and pricing
2. **Create an order** using the quote ID with additional information based on the asset types

<Note>
  Wallet addresses are required only for token assets (like `eth-base/brlv`, `eth-base/usdc`). For fiat assets (`fiat/brl`), no wallet addresses are needed.
</Note>

## Step 1: Create a Quote

First, request a quote specifying your source and target assets, along with either the source or target amount.

### Supported Conversions

**BRL ↔ BRLV (same-currency conversions)**

* `fiat/brl` → `eth-base/brlv`
* `eth-base/brlv` → `fiat/brl`
* `fiat/brl` → `tempo/brlv`
* `tempo/brlv` → `fiat/brl`

**BRL ↔ USDC (FX conversions)**

* `fiat/brl` → `eth-base/usdc`
* `eth-base/usdc` → `fiat/brl`

<Info>
  FX conversions (BRL ↔ USDC) are subject to additional regulatory requirements. They require a `trade-reason` on the **quote request**, and the corresponding wallets must be FX-whitelisted for the account.
</Info>

### Request Examples

<CodeGroup>
  ```bash Fiat to Token theme={null}
  curl -X POST https://app.crown-brlv.com/api/v0/quotes \
    -H "X-API-Key: your_api_key" \
    -H "Authorization: Bearer your_jwt_token" \
    -H "Content-Type: application/json" \
    -d '{
      "source-asset": "fiat/brl",
      "target-asset": "eth-base/brlv",
      "source-amount": "100.00"
    }'
  ```

  ```bash Token to Fiat theme={null}
  curl -X POST https://app.crown-brlv.com/api/v0/quotes \
    -H "X-API-Key: your_api_key" \
    -H "Authorization: Bearer your_jwt_token" \
    -H "Content-Type: application/json" \
    -d '{
      "source-asset": "eth-base/brlv",
      "target-asset": "fiat/brl",
      "source-amount": "100.00"
    }'
  ```

  ```bash BRL to USDC (FX) theme={null}
  curl -X POST https://app.crown-brlv.com/api/v0/quotes \
    -H "X-API-Key: your_api_key" \
    -H "Authorization: Bearer your_jwt_token" \
    -H "Content-Type: application/json" \
    -d '{
      "source-asset": "fiat/brl",
      "target-asset": "eth-base/usdc",
      "source-amount": "1000.00",
      "trade-reason": "purchase-or-sale-of-other-services"
    }'
  ```

  ```bash USDC to BRL (FX) theme={null}
  curl -X POST https://app.crown-brlv.com/api/v0/quotes \
    -H "X-API-Key: your_api_key" \
    -H "Authorization: Bearer your_jwt_token" \
    -H "Content-Type: application/json" \
    -d '{
      "source-asset": "eth-base/usdc",
      "target-asset": "fiat/brl",
      "source-amount": "200.00",
      "trade-reason": "purchase-or-sale-of-other-services"
    }'
  ```
</CodeGroup>

<Info>
  You can specify either `source-amount` or `target-amount` in your quote request, but not both. The quote engine will calculate the other amount based on current exchange rates.
</Info>

### FX Quotes: trade-reason

`trade-reason` is required **only** for FX quotes (BRL ↔ USDC), where it carries the SISBACEN classification mandated by the Central Bank of Brazil. It must be **omitted** for same-currency BRL ↔ BRLV quotes — those conversions are not FX trades and do not need a SISBACEN reason.

Valid values (FX quotes only):

* `purchase-or-sale-of-merchandise`
* `purchase-or-sale-of-other-services`
* `purchase-or-sale-of-business-services`
* `purchase-or-sale-of-computing-services`
* `transfer-between-same-entity-accounts`
* `offshore-loans-principal`
* `offshore-loans-interest`
* `donation-without-counter-payment`
* `international-travels`
* `other-transactions`

The quote response echoes back `trade-reason` along with `trade-reason-code`, the corresponding regulatory code.

### Quote Response

Quote responses include a full pricing breakdown so you can audit the all-in cost before placing an order:

| Field                                | Description                                                                                                                                |
| ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `source-amount` / `target-amount`    | The amounts on each side of the conversion (10-decimal precision).                                                                         |
| `pricing.base-rate`                  | The commercial exchange rate before Crown's spread, expressed as `amount` of `quote` per 1 unit of `base`.                                 |
| `pricing.spread`                     | Crown's spread on the conversion. Includes `amount`, `asset`, and (when the percentage branch of the brokerage formula wins) a `bps` rate. |
| `pricing.fee`                        | Service fee charged on the conversion (`amount`, `asset`, `kind`).                                                                         |
| `pricing.iof`                        | IOF (Imposto sobre Operações Financeiras) treatment for the conversion, including whether it applies and the regulatory basis reference.   |
| `vet`                                | **Valor Efetivo Total** — the all-in effective rate including spread, fee, and IOF. Required disclosure for FX conversions.                |
| `trade-reason` / `trade-reason-code` | SISBACEN trade reason and the corresponding regulatory code. Present only for FX quotes (BRL ↔ USDC); absent for same-currency quotes.     |
| `expires-at`                         | Quote validity deadline (millisecond precision). Place the order before this timestamp.                                                    |

## Step 2: Create an Order

Once you have a quote ID, create an order to execute the conversion. The required fields depend on your source and target asset types.

### Wallet Address Requirements

| Scenario            | source-wallet-address | target-wallet-address |
| ------------------- | --------------------- | --------------------- |
| **Fiat → Token**    | Not required          | **Required**          |
| **Token → Fiat**    | **Required**          | Not required          |
| **BRL → USDC (FX)** | Not required          | **Required**          |
| **USDC → BRL (FX)** | **Required**          | Not required\*        |

<Info>
  Wallets managed by Crown can be used immediately. To use a wallet that **isn't** managed by Crown, you must first contact Crown's support team to register it. Registration is per-operation:

  * **Minting BRLV** to an external wallet requires that wallet to be registered for BRLV minting.
  * **FX orders** that deliver USDC to an external wallet (BRL → USDC) require that wallet to be registered for FX operations.

  These are separate registrations — a wallet enabled for BRLV minting is not automatically enabled for FX.
</Info>

*\* For USDC→BRL FX orders, you may optionally route BRL to a third-party recipient using `target-end-user-pix-key` (see [Delivering BRL to a third party](#delivering-brl-to-a-third-party)).*

### Delivering BRL to a third party

For USDC → BRL FX orders, you can have BRL delivered directly to a third-party recipient by setting `target-end-user-pix-key`. When this field is set, BRL is paid from Crown's FX pool straight to that PIX key — your own bank account is not touched.

This field is allowed **only** for USDC → BRL FX orders.

### Order Examples

<CodeGroup>
  ```bash Fiat to Token theme={null}
  curl -X POST https://app.crown-brlv.com/api/v0/orders \
    -H "X-API-Key: your_api_key" \
    -H "Authorization: Bearer your_jwt_token" \
    -H "Content-Type: application/json" \
    -d '{
      "quote-id": "550e8400-e29b-41d4-a716-446655440000",
      "target-wallet-address": "0x742d35Cc6635C0532925a3b8D295FD6C6e7e2c2c"
    }'
  ```

  ```bash Token to Fiat theme={null}
  curl -X POST https://app.crown-brlv.com/api/v0/orders \
    -H "X-API-Key: your_api_key" \
    -H "Authorization: Bearer your_jwt_token" \
    -H "Content-Type: application/json" \
    -d '{
      "quote-id": "550e8400-e29b-41d4-a716-446655440000",
      "source-wallet-address": "0x742d35Cc6635C0532925a3b8D295FD6C6e7e2c2c"
    }'
  ```

  ```bash BRL to USDC (FX) theme={null}
  curl -X POST https://app.crown-brlv.com/api/v0/orders \
    -H "X-API-Key: your_api_key" \
    -H "Authorization: Bearer your_jwt_token" \
    -H "Content-Type: application/json" \
    -d '{
      "quote-id": "550e8400-e29b-41d4-a716-446655440000",
      "target-wallet-address": "0x742d35Cc6635C0532925a3b8D295FD6C6e7e2c2c"
    }'
  ```

  ```bash USDC to BRL (FX, third-party PIX) theme={null}
  curl -X POST https://app.crown-brlv.com/api/v0/orders \
    -H "X-API-Key: your_api_key" \
    -H "Authorization: Bearer your_jwt_token" \
    -H "Content-Type: application/json" \
    -d '{
      "quote-id": "550e8400-e29b-41d4-a716-446655440000",
      "source-wallet-address": "0x742d35Cc6635C0532925a3b8D295FD6C6e7e2c2c",
      "target-end-user-pix-key": "user@example.com"
    }'
  ```
</CodeGroup>

### Order Fees

Every order response includes the fee Crown charged for the conversion:

* `fee-amount` — the fee amount (decimal string).
* `fee-asset` — the asset the fee is denominated in (e.g., `fiat/brl`).

The fee is also visible in the originating quote under `pricing.fee`.

## Order Status

After creating an order, it will go through several status states:

* `created` - Order has been created
* `processing` - Order is being processed
* `completed` - Order has been successfully completed
* `rolled-back` - Order was rolled back

You can track your order status by:

* Using the [Get Order endpoint](/api-reference/endpoint/orders/get-order)
* [Setting up webhooks](/guides/webhooks-setup) and listening to the [order-completed webhook](/api-reference/webhooks/order-completed)