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": "transfer-between-same-entity-accounts"
  }'

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": "transfer-between-same-entity-accounts"
  }'

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), with the regulatory code each one carries:

`trade-reason`	`trade-reason-code`
`transfer-between-same-entity-accounts`	`67995`
`international-travels`	`32999`
`international-card-or-electronic-payment-with-virtual-assets`	`34203`

Every reason other than transfer-between-same-entity-accounts must be enabled on the account. Contact Crown’s support team to request one. Without it, a quote with that reason is refused with Trade reason <trade-reason> is not enabled for this account.

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

FX Quotes: rate-lock

An FX quote is priced live and stays valid for five seconds: expires-at is the deadline to place the order. To hold the rate for longer, request a quote rate lock by name with rate-lock. Two locks are available: 15s keeps the quote valid for fifteen seconds and 10m for ten minutes. The extra time is charged as basis points added to the account’s spread, priced per lock. The rate lock is folded into pricing.spread, never shown as a separate line.

Rate locks must be enabled on the account, one by one. Contact Crown’s support team to request one. Without it, a quote with rate-lock is refused with Quote rate lock 10m is not enabled for this account (or 15s).

BRL to USDC (FX), rate locked for 10 minutes

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": "transfer-between-same-entity-accounts",
    "rate-lock": "10m"
  }'

The quote response echoes rate-lock when the lock was granted, and the order created from that quote carries it too. A quote can also be refused with:

rate-lock: quote rate locks apply only to FX conversions between BRL and a non-BRL-pegged asset when the field is sent on a BRL ↔ BRLV quote.
Quote rate lock 10m is currently unavailable when Crown is not offering that lock at the moment. Retry without it.

FX Quotes: payment-term

For a BRL → USDC order that will be paid with a PIX QR code (see pay after acceptance), payment-term says how long after accepting the quote the QR code may be paid:

Value	The QR code may be paid…	Priced
`d0` (default when omitted)	until the end of today’s trading day	at the account’s spread
`10m`	for ten minutes after acceptance	at the account’s spread plus the term’s rate
`d1`	until the end of the next business day	at the account’s spread plus the term’s rate

Payment terms must be enabled individually on your account, like rate locks; contact Crown’s support team for each one you need. A quote with 10m or d1 can only be accepted with source-payment-method: "brcode", and is refused with Payment term 10m is not enabled for this account (or d1) without the capability. The order response carries the resulting deadline in expiration. Like the rate lock, the term’s rate is folded into pricing.spread.

BRL to USDC (FX), pay within ten minutes

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": "transfer-between-same-entity-accounts",
    "payment-term": "10m"
  }'

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 total spread on the conversion, including the basis points of a granted rate lock. `amount` and `asset` are always present; `bps` is the total rate and is absent only when it does not describe the charge: on a minimum-ticket quote, where the floor set the amount instead of the percentage, and on pairs that carry no spread.
`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.
`rate-lock`	The quote rate lock granted (`15s` or `10m`). Present only when one was requested.
`payment-term`	The payment term the quote was priced under (`10m` or `d1`). Absent for the default term.
`expires-at`	Quote validity deadline (millisecond precision). Place the order before this timestamp. Five seconds after creation for an FX quote without a rate lock, fifteen seconds with `15s`, ten minutes with `10m`.

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 pending-payment state with the PIX payload to collect payment:

{
  "order": {
    "id": "660e8400-e29b-41d4-a716-446655440001",
    "state": "pending-payment",
    "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, and it follows the quote’s payment-term: the end of today’s trading day by default, ten minutes after acceptance for 10m, the end of the next business day for d1.
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": "pending-payment",
    "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",
    "payment-term": "d0"
  }
}

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 quote’s term would already have run out. Retry later, or fund the order from the account balance.Outside the trading day, only the 10m term is sold, and only to accounts enabled for off-market trading. A quote with no term, or with d1, cannot be paid after acceptance until the next trading day opens.

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:

pending-payment - A brcode order waiting for its PIX. An order paid from the account balance never waits here
pending-delivery - The order is paid and its target asset is on its way
rolling-back - The order is being undone
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
rejected - The order could not go ahead

You can track your order status by:

Using the Get Order endpoint
Listing orders by state with the List Orders by State endpoint
Setting up webhooks and listening to the order-completed and order-refund-initiated webhooks

Listing orders by state

The List Orders by State endpoint lists your orders in the states you pass in states, comma separated. If you manage sub-accounts, their orders are included, each with its account-id. Without states, it lists orders in every state. To see every order still waiting on a payment or a delivery:

curl "https://app.crown-brlv.com/api/v1/orders?states=pending-payment,pending-delivery" \
  -H "X-API-Key: your_api_key" \
  -H "Authorization: Bearer your_jwt_token"

Results come oldest first, in pages of up to limit orders. While next-cursor is not null, request the next page with cursor set to it.

Reconciling a day of orders

To check a day of orders against your own records, list every order that completed on that day. date is the calendar day in America/Sao_Paulo on which an order reached its state: the day it completed, for a completed order.

curl "https://app.crown-brlv.com/api/v1/orders?states=completed&date=2026-10-09&limit=100" \
  -H "X-API-Key: your_api_key" \
  -H "Authorization: Bearer your_jwt_token"

Getting started

Setup

Guides

Overview

Step 1: Create a Quote

Supported Conversions

Request Examples

FX Quotes: trade-reason

FX Quotes: rate-lock

FX Quotes: payment-term

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

Listing orders by state

Reconciling a day of orders

​Overview

​Step 1: Create a Quote

​Supported Conversions

​Request Examples

​FX Quotes: trade-reason

​FX Quotes: rate-lock

​FX Quotes: payment-term

​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

​Listing orders by state

​Reconciling a day of orders

Overview

Step 1: Create a Quote

Supported Conversions

Request Examples

FX Quotes: trade-reason

FX Quotes: rate-lock

FX Quotes: payment-term

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

Listing orders by state

Reconciling a day of orders