Pular para o conteúdo principal

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:

CampoTipoO que é
sidestringLado do dólar usado: ask (compra) ou bid (venda)
dollarBasestringDólar base (USD/BRL) cotado no provedor de câmbio, com 4 casas
iofPercentagestringIOF, em percentual com 4 casas ("1.1000" = 1,1%)
brokerageFeePercentagestringCorretagem do câmbio, em percentual com 4 casas
outsideBizHoursSpreadPercentagestringSpread de fora do horário comercial, em percentual com 4 casas
dollarWithFxFeesstringDólar com as taxas de câmbio, com 4 casas (fórmula abaixo)
feesIncludedByProviderbooleantrue 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.

aviso

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çãofxComposition
Cotação e ordem RFQ em exchange em dólarVem
Ordem a mercado ou a limite em exchange em dólar, antes de liquidarVem, com o dólar da criação
Ordem a mercado ou a limite em exchange em dólar, já liquidadaNã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 BRLNão vem
Ordem anterior a 25/11/2025, sem o dadoNão vem
Contingência entre duas exchanges em dólar com o dólar congeladoNã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​

  • fetchLimitOrders e 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:

ColunaConteúdo
dolar_basedollarBase
iof_pctiofPercentage
corretagem_pctbrokerageFeePercentage
fora_horario_pctoutsideBizHoursSpreadPercentage
dolar_com_taxas_cambiodollarWithFxFees
taxas_embutidas_provedorfeesIncludedByProvider, 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 evaluatedTickers registra o preço final de cada exchange avaliada; o fxComposition detalha a parcela de câmbio do dólar da operação.