Asset Conversions

Overview

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

Create a quote between two assets to get exchange rates and pricing
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

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

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

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

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

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.
`off-market-pricing`	`true` when the quote was priced outside normal market conditions and the rate may differ from standard pricing. Always `false` for same-currency conversions (BRL ↔ BRLV). You can wait for conditions to normalize or proceed at the quoted rate.
`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

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

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

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

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

Funding an order with PIX

By default, a fiat/brl 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. The order settles once the QR is paid.

brcode is available for BRL → BRLV and for BRL → USDC (FX). The two behave differently after payment, see below.

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 stops being payable.

The PIX QR code can only be paid from a bank account under the tax ID registered for the account that placed the order: the account holder funds their own QR code. A payment from any other payer is refused by the bank.

BRL → BRLV

Create a quote for fiat/brl → eth-base/brlv (or tempo/brlv).
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.
Pay the QR code. Funds are pulled in via PIX rather than from the account balance.
BRLV is minted to the target wallet once payment is confirmed, and the order-completed webhook fires.

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

BRL → USDC: pay after acceptance

For FX orders, brcode lets you lock the rate first and pay afterwards. The account does not need BRL on balance when the order is created: accepting the quote fixes effective-rate, reserves the USDC, and returns a PIX QR code with a deadline. The USDC is delivered to the target wallet once the PIX arrives.

Paying after acceptance must be enabled on the account. Contact Crown’s support team to request it. Without it, a BRL → USDC order with source-payment-method: "brcode" is refused with This account cannot pay FX orders after acceptance. Pay from your BRL balance instead.

The flow is:

Create a quote for fiat/brl → eth-base/usdc with a trade-reason.
Create the order with source-payment-method: "brcode" and an FX-whitelisted target-wallet-address. The rate is locked at this point.
Pay the QR code before expiration. This is the funding deadline, not just the QR’s validity: it is up to one hour after acceptance, shorter when the order is placed close to the end of the trading day. An order whose remaining window would be under 15 minutes is refused instead of created.
USDC is delivered to the target wallet once the PIX is confirmed, and the order-completed webhook fires.

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

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

If the QR is not paid in time, the order moves to expired shortly after expiration. The reservation is released and nothing is charged or owed: the account simply did not take the rate. To convert, create a new quote. If the PIX arrives after expiration, it cannot be applied to an order that has already expired. Crown asks the bank to return the payment to the account it came from, the order moves to payment-returned, and the order-refund-initiated webhook fires with the deposit identifier. The webhook says the return was requested; the bank settles it afterwards.

The order can also be refused at creation with Paying after acceptance is not available right now. Pay from your BRL balance instead. This happens when the trading day is closed or when the funding window left before the day’s cut-off is too short. Retry later, or fund the order from the account balance.

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 undone for a reason other than funding
expired - A brcode order whose funding window closed with no payment. Nothing was charged and nothing is owed
payment-returned - A brcode order whose PIX arrived after the window. The payment is being returned to the account it came from

You can track your order status by:

Using the Get Order endpoint
Setting up webhooks and listening to the order-completed and order-refund-initiated webhooks

Getting started

Setup

Guides

Overview

Step 1: Create a Quote

Supported Conversions

Request Examples

FX Quotes: trade-reason

Quote Response

Step 2: Create an Order

Wallet Address Requirements

Delivering BRL to a third party

Order Examples

Funding an order with PIX

BRL → BRLV

BRL → USDC: pay after acceptance

Order Fees

Order Status

​Overview

​Step 1: Create a Quote

​Supported Conversions

​Request Examples

​FX Quotes: trade-reason

​Quote Response

​Step 2: Create an Order

​Wallet Address Requirements

​Delivering BRL to a third party

​Order Examples

​Funding an order with PIX

​BRL → BRLV

​BRL → USDC: pay after acceptance

​Order Fees

​Order Status

Overview

Step 1: Create a Quote

Supported Conversions

Request Examples

FX Quotes: trade-reason

Quote Response

Step 2: Create an Order

Wallet Address Requirements

Delivering BRL to a third party

Order Examples

Funding an order with PIX

BRL → BRLV

BRL → USDC: pay after acceptance

Order Fees

Order Status