Composição do dólar
Quando a operação é liquidada em uma exchange em dólar, o preço em reais depende do dólar usado na conversão. O bloco fxComposition mostra de que é feito o dólar de câmbio daquela operação: o dólar base cotado, o IOF, a corretagem, o spread de fora do horário comercial e o dólar resultante com essas taxas. O bloco é retornado por createQuote, fetchQuote, fetchOrder e fetchOrders (em cada item), e acompanha a ordem publicada no canal watchOrders.
Para que serve
O bloco é um registro de transparência: permite conferir, depois da operação, qual dólar base e quais taxas de câmbio compõem o dólar com taxas. Ele não é parâmetro de entrada, não altera o preço e não precisa ser habilitado: é produzido sempre que se aplica.
Estrutura
fxComposition é uma chave opcional de topo, irmã de operationalFees. Quando não se aplica, a chave não vem na resposta — nunca vem como null. Os 7 campos, nesta ordem:
| Campo | Tipo | O que é |
|---|---|---|
side | string | Lado do dólar usado: ask (compra) ou bid (venda) |
dollarBase | string | Dólar base (USD/BRL) cotado no provedor de câmbio, com 4 casas |
iofPercentage | string | IOF, em percentual com 4 casas ("1.1000" = 1,1%) |
brokerageFeePercentage | string | Corretagem do câmbio, em percentual com 4 casas |
outsideBizHoursSpreadPercentage | string | Spread de fora do horário comercial, em percentual com 4 casas |
dollarWithFxFees | string | Dólar com as taxas de câmbio, com 4 casas (fórmula abaixo) |
feesIncludedByProvider | boolean | true quando o provedor de câmbio já entrega o dólar com as taxas embutidas |
O bloco não traz o nome do provedor de câmbio nem outros componentes do preço, como customerSpread, taxa de pool, taxa de rede, spread, taxa total ou o dólar aplicado na liquidação.
Como o dólar com taxas é calculado
O dollarWithFxFees parte do dollarBase e soma os três percentuais do próprio bloco:
- Compra (
ask):dollarBase × (1 + (iofPercentage + brokerageFeePercentage + outsideBizHoursSpreadPercentage) / 100) - Venda (
bid):dollarBase × (1 − (iofPercentage + brokerageFeePercentage + outsideBizHoursSpreadPercentage) / 100)
A conta usa os valores já truncados que aparecem no bloco, e o resultado é truncado (não arredondado) em 4 casas. Assim, você consegue reproduzi-lo a partir da resposta.
Exemplo de compra, com IOF de 1,10%, corretagem de 0,25% e sem spread de fora do horário:
{
"fxComposition": {
"side": "ask",
"dollarBase": "5.4321",
"iofPercentage": "1.1000",
"brokerageFeePercentage": "0.2500",
"outsideBizHoursSpreadPercentage": "0.0000",
"dollarWithFxFees": "5.5054",
"feesIncludedByProvider": false
}
}
Conferindo: 5,4321 × (1 + 1,35 / 100) = 5,505433... e o truncamento em 4 casas dá 5,5054. Na venda (bid) com o mesmo dólar base, o resultado seria 5,4321 × (1 − 1,35 / 100) = 5,358766... , truncado em 5,3587.
O dollarWithFxFees é o dólar com as taxas de câmbio. Ele não é o dólar de liquidação da ordem, que tem outros componentes da Liqi. Para conciliar o que o cliente pagou ou recebeu, use os campos de liquidação da ordem (RFQ ou settlement), e não este bloco.
Provedor que já entrega o dólar com taxas
Quando feesIncludedByProvider é true, o provedor de câmbio já entrega o dólar com as taxas embutidas. Nesse caso iofPercentage, brokerageFeePercentage e outsideBizHoursSpreadPercentage vêm "0.0000" e dollarWithFxFees é igual a dollarBase. Os zeros significam que as taxas estão dentro do dólar base, e não que a operação não pagou taxas de câmbio.
Fora do horário comercial
O spread de fora do horário comercial vale aos sábados, domingos e, em dia útil, antes das 9h02 ou a partir das 17h, quando a regra está ativa. Hoje a regra está desativada: o campo outsideBizHoursSpreadPercentage sai "0.0000". Feriado não conta como fora do horário comercial.
Quando o bloco aparece
O bloco aparece em ordem e cotação em exchange em dólar (hoje Crypto.com, Coinbase Prime e Circle; vale também para novas exchanges em dólar).
| Situação | fxComposition |
|---|---|
| Cotação e ordem RFQ em exchange em dólar | Vem |
| Ordem a mercado ou a limite em exchange em dólar, antes de liquidar | Vem, com o dólar da criação |
| Ordem a mercado ou a limite em exchange em dólar, já liquidada | Não vem: o dólar de liquidação é o dólar ao vivo do momento, e o bloco do momento da criação não o representa |
| Ordem ou cotação em exchange em BRL | Não vem |
| Ordem anterior a 25/11/2025, sem o dado | Não vem |
| Contingência entre duas exchanges em dólar com o dólar congelado | Não vem: vale a composição da cotação, que o cliente já recebeu |
RFQ: o dólar é congelado na cotação
No RFQ o dólar é congelado quando a cotação é emitida. Por isso o bloco da ordem é igual ao da cotação que a originou. A única diferença é na contingência com troca de exchange (por exemplo, a cotação era em uma exchange em BRL e a ordem foi executada em uma exchange em dólar): nesse caso o bloco da ordem mostra a exchange que executou.
Em contingência entre duas exchanges em dólar, o dólar permanece congelado e o bloco não é reemitido na ordem: vale a composição da cotação.
Rotas e canais sem o bloco
fetchLimitOrderse as rotas/orders/limit/*.fetchConciliationOrders.- O frame de fallback do
watchOrders: quando a releitura da ordem falha, o canal publica o frame mesmo assim (melhor esforço) e esse frame não traz o bloco. A mensagem seguinte, com a ordem relida, traz.
CSV do histórico de ordens
O CSV de histórico de ordens (a exportação e o CSV por cliente) ganha 6 colunas no final, nesta ordem:
| Coluna | Conteúdo |
|---|---|
dolar_base | dollarBase |
iof_pct | iofPercentage |
corretagem_pct | brokerageFeePercentage |
fora_horario_pct | outsideBizHoursSpreadPercentage |
dolar_com_taxas_cambio | dollarWithFxFees |
taxas_embutidas_provedor | feesIncludedByProvider, como Sim ou Nao |
As colunas só são preenchidas em ordem RFQ em exchange em dólar e ficam vazias nas demais. Os números têm 4 casas e vírgula decimal (por exemplo, 5,5054).
Relação com outras páginas
- Melhor execução: o
evaluatedTickersregistra o preço final de cada exchange avaliada; ofxCompositiondetalha a parcela de câmbio do dólar da operação.