> ## Documentation Index
> Fetch the complete documentation index at: https://docs.arbitragem-crypto.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Ranking de funding rate

> Taxas de funding, APR bruto e histórico local por contrato e exchange

O ranking está em `/funding-rates` no aplicativo e atende Binance, BingX, BitMEX,
Gate.io e MEXC. A coleta começa na inicialização do backend, com ciclos de cinco
minutos. `ENABLED_FUNDING_RATES=false` (ou `0`) desativa a coleta.

## Taxa e APR

`fundingRate` é uma fração: `0.0001` corresponde a **0,01% por pagamento**.
O APR é percentual e segue a fórmula:

```text theme={null}
aprPercent = fundingRate × (31.536.000 / fundingIntervalSeconds) × 100
```

Exemplo: 0,01% a cada oito horas corresponde a **10,95% ao ano**.
É uma projeção bruta da taxa observada, sem capitalização, taxas de negociação,
custos de empréstimo ou garantia de manutenção do funding.

O ranking ordena APR assinado em ordem decrescente. Funding positivo indica long
spot + short perpétuo; negativo indica short spot + long perpétuo, operação que
depende de disponibilidade de empréstimo do ativo spot. A calculadora existente
permanece disponível apenas para a direção positiva e pares compatíveis.

O preço spot é o ponto médio do bid/ask da mesma exchange e do mesmo par.
USD e USDT não são tratados como equivalentes. Ausência de preço, taxa ou
intervalo é representada por `null`, nunca por zero. Intervalo não confirmado
impede o cálculo do APR e coloca a linha ao final do ranking.

## Histórico e atualização

O histórico começa na implantação, sem importação retroativa. MongoDB mantém a
primeira observação válida de cada janela UTC de 15 minutos durante 30 dias.
Essas observações **não são pagamentos liquidados**. O gráfico apresenta APR
observado em períodos de 24 horas, sete ou 30 dias.

Falhas de uma exchange preservam seu último snapshot com o timestamp original.
Após 15 minutos, os dados são marcados como desatualizados. Reinícios recuperam
o último snapshot persistido. O histórico não cria pontos novos a partir de
snapshots antigos. Falhas de MongoDB são registradas; o ranking em memória
continua disponível. Consultas de histórico sem banco retornam 503.

As coleções `funding_rates_latest` e `funding_rate_history` e seus índices são
criadas automaticamente. O usuário MongoDB precisa poder criar índices. A
retenção usa TTL e a consulta também exclui dados expirados, pois a remoção TTL
é assíncrona. O processo deve ter um único coletor ativo por ambiente.

## Fontes e limitações por exchange

Fontes oficiais verificadas em **17/09/2026**:

* [Binance USDⓈ-M](https://developers.binance.com/docs/derivatives/usds-margined-futures/market-data/rest-api/Get-Funding-Rate-Info): `premiumIndex` e `fundingInfo.fundingIntervalHours`. O endpoint de intervalo documenta contratos com ajustes; ausência do contrato mantém APR indisponível, sem assumir oito horas.
* [Gate.io](https://www.gate.com/docs/developers/apiv4/en/futures/): `funding_interval` em segundos e `funding_next_apply` no contrato USDT.
* [BitMEX](https://docs.bitmex.com/api-explorer/get-active-instruments): contratos perpétuos ativos, `fundingInterval` em duração ISO 8601 temporal, `fundingTimestamp` e `fundingRate`. Formatos não reconhecidos não recebem intervalo presumido.
* [MEXC](https://mexcdevelop.github.io/apidocs/contract_v1_en/): ticker e `funding_rate/{symbol}`, `collectCycle` em horas e `nextSettleTime` em milissegundos. Enriquecimento limitado a oito requisições por segundo; falhas deixam campos indisponíveis.
* [BingX](https://github.com/BingX-API/api-ai-skills/blob/main/skills/swap-market/api-reference.md): `premiumIndex` e `fundingRate`. A diferença positiva entre `fundingTime` e `nextFundingTime` na mesma resposta é uma derivação da integração (`derived_schedule`), não um campo explícito de intervalo. Respostas sem ambos os campos deixam APR indisponível.

As consultas são somente de leitura. São limitadas a quatro requisições HTTP
simultâneas, com timeout de oito segundos e limite global de quatro minutos por
ciclo. BingX usa no máximo uma requisição por segundo. O enriquecimento MEXC
pode terminar parcialmente quando o orçamento do ciclo se esgota.

Preços spot usam os tickers públicos documentados por
[Binance](https://developers.binance.com/docs/binance-spot-api-docs/rest-api/market-data-endpoints),
[MEXC](https://mexcdevelop.github.io/apidocs/spot_v3_en/),
[Gate.io](https://www.gate.com/docs/developers/apiv4/en/spot/),
[BingX](https://github.com/BingX-API/api-ai-skills/blob/main/skills/spot-market/api-reference.md)
e os instrumentos spot BitMEX. Falhas de spot não removem funding disponível.

## API e verificação

* [Ranking](/api-reference/endpoint/get-funding-rates)
* [Histórico](/api-reference/endpoint/get-funding-rates-history)

Testes de adaptadores usam fixtures, sem rede. Para validar persistência em
MongoDB descartável, execute `RUN_FUNDING_MONGO_TESTS=1 go test ./internal/infra/db -run TestFunding`.
Sem `MONGO_URI`, o helper de testes inicia um container MongoDB. Não use banco de produção.