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

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.

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

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.

Request Examples

Fiat to Token

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"
  }'

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.

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*

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.

* 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

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

Fiat to Token

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"
  }'

Funding a BRL → BRLV order with PIX

By default, a fiat/brl → */brlv order is funded from the account’s existing BRL balance. To instead let the account holder pay for the order with a one-time PIX QR code, set source-payment-method to brcode when creating the order.

source-payment-method accepts:

• account-balance (default, used when the field is omitted) — the order is funded from the account’s existing BRL balance.
• brcode — Crown issues a one-time PIX QR code for the exact order amount; BRLV is minted once the QR is paid.

This option applies only to BRL → BRLV orders.

When the order is created with brcode, the response carries the PIX payload to present to the payer:

• brcode — the EMV PIX copy-paste payload.
• qr-code-base64 — a base64-encoded PNG of the QR code.
• expiration — when the QR code expires.

The flow is:

1. Create a quote for fiat/brl → eth-base/brlv (or tempo/brlv).
2. Create the order with source-payment-method: "brcode" and the target-wallet-address that will receive BRLV. The order is parked awaiting payment, and the response carries the brcode / qr-code-base64.
3. Pay the QR code. Funds are pulled in via PIX rather than from the account balance.
4. BRLV is minted to the target wallet once payment is confirmed, and the order-completed webhook fires.

PIX on-ramp

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-payment-method": "brcode",
    "target-wallet-address": "0x742d35Cc6635C0532925a3b8D295FD6C6e7e2c2c"
  }'

The order is returned in the processing state with the PIX payload to collect payment:

{
  "order": {
    "id": "660e8400-e29b-41d4-a716-446655440001",
    "state": "processing",
    "source-asset": "fiat/brl",
    "target-asset": "eth-base/brlv",
    "source-amount": "100.00",
    "target-amount": "100.00",
    "brcode": "00020101021226890014br.gov.bcb.pix...",
    "qr-code-base64": "iVBORw0KGgoAAAANSUhEUgAA...",
    "expiration": "2024-01-15T11:30:00Z"
  }
}

The PIX QR code can only be paid from the bank account (tax ID) registered for the account that placed the order — the account holder funds their own QR code.

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
• Setting up webhooks and listening to the order-completed webhook