Comum a todos os endpoints get_alpha / get_exposure de cripto:
period — tamanho da barra, {n}min / {n}h / {n}d ({n}m é lido como minutos). Os valores documentados são 5min, 15min, 1h, 4h, 8h, 1d; os indicadores com um mínimo maior informam isso no próprio bloco. Um period ausente ou que não pode ser interpretado resulta em 403 {"error": "period is required"} (400 em unusual_movement e liquidation).
start_date / end_date — YYYY-MM-DD (UTC). O padrão de end_date é hoje; o de start_date é end_date − 365 dias. Um intervalo maior que 365 dias é limitado silenciosamente (start_date é movido para end_date − 365 dias). Uma data malformada não é validada e termina em 500 — envie sempre YYYY-MM-DD.
symbol — perpétuo USDT-M da Binance, p. ex. BTCUSDT; BTC, btc, BTC/USDT, BTC-USDT também são aceitos (um token sem sufixo recebe USDT no final). Os endpoints get_symbols listam os símbolos cobertos.
Apenas barras fechadas são retornadas — a última barra, ainda em formação, é descartada.
A resposta é {"data": {"timestamp": [...], "alpha": [...], ...}} — arrays paralelos, um elemento por barra. timestamp é em segundos Unix (UTC), o rótulo da barra.
Para históricos além de 365 dias, envie uma requisição por ano e concatene.
Objeto stat — retornado pelos indicadores cujo bloco o lista. Um modelo logístico ajustado com o último ano deste indicador para o símbolo contra o movimento de preço das 24h seguintes:
Campo
Tipo
Descrição
up_prob
float
Probabilidade de alta em 24h dado o valor mais recente do indicador (0–1)
avg_up_return
float
Retorno médio de 24h nos movimentos de alta passados (decimal, 0.02 = +2%)
avg_down_return
float
Retorno médio de 24h nos movimentos de baixa passados (decimal, negativo)
data é indexado por token (BTC, 1INCH, …). Cada token mapeia nome do indicador → {param: value} ("-" quando o indicador não tem parâmetro). "" = dados insuficientes. Além dos indicadores:
Chave
Descrição
statistics
up_prob (prob. de alta em 24h), exp_value (retorno esperado), avg_up_return, avg_down_return, return_ratio, is_data_sufficient
price
{"-": 70000} — preço atual
price_change
{"15min": ..., "1h": ..., "24h": ...} — variação em %
market_cap
{"-": 1234567890} — capitalização de mercado em USD
market_cap_percentile
{"-": 85.3} — percentil entre todas as moedas listadas
funding_rate
{"binance": -0.01, ...} — por exchange
oi_imbalance
{"-": 0.12} — desequilíbrio de OI (detalhe completo: /oi_imbalance/get_overview_data)
fields — uma entrada por indicador: id, name (chave usada em data), param (nome do parâmetro ou null), name_en, name_zh.
note — indexado pelo id do indicador: uma lista de faixas de valor {min, max, note: {en, zh}, direction: {en, zh}, color, background_color} usada para rotular um valor (p. ex. max: -3 → "Overly Bearish").
Erros
Apenas os erros comuns.
Observações
Use este endpoint primeiro para qualquer filtro ou ranking com várias moedas — uma requisição cobre todos os símbolos.
Verifique sempre statistics.is_data_sufficient antes de usar statistics.
Busque sempre dados novos; não reutilize uma resposta anterior.
2020-01-01, ou a data de listagem do contrato, se posterior
Atualização
Cerca de um minuto após o fechamento de cada barra
Cobertura. Todos os perpétuos USDⓈ-M da Binance cujo símbolo termina em USDT — 740 contratos em outubro de 2026, incluindo ações tokenizadas, commodities e outros perpétuos USDT de TradFi. Todos os 740 têm o histórico completo de 1 minuto armazenado no servidor, desde 2020-01-01 ou desde a data de listagem. Um perpétuo recém-listado fica consultável cerca de 5–10 minutos depois da listagem.
Sem cobertura: contratos cotados em USDC, USD1, U ou BTC (p. ex. BTCUSDC, ETHBTC) e contratos trimestrais com entrega — estes retornam o erro 400 unknown symbol or no data abaixo. Contratos deslistados não são garantidos: um deles pode responder com o histórico que ainda estiver armazenado ou com esse mesmo 400 (os deslistados antes de outubro de 2026 não têm histórico de 1min–4min).
Parâmetros
Nome
Descrição
Valores permitidos
Padrão
symbol
string · queryObrigatório
Perpétuo USDT USDⓈ-M da Binance. Um token sem sufixo recebe USDT no final; um token sem sufixo que só existe com um prefixo multiplicador é resolvido para ele (PEPE → 1000PEPEUSDT)
BTCUSDT; também BTC, btc, BTC/USDT, BTC-USDT
period
string · queryObrigatório
Tamanho da barra. Qualquer tamanho em minutos inteiros é aceito, não apenas os exemplos listados
end_date − 365 dias (period ≥ 5min); end_date − 30 dias (period < 5min)
end_date
string · query
Último dia, inclusive (barras até o fim desse dia UTC)
YYYY-MM-DD (UTC)
agora
Janela por requisição: period ≥ 5min → no máximo 365 dias; um intervalo maior é limitado silenciosamente (start_date é movido para end_date − 365 dias, sem erro). Period < 5min → no máximo 30 dias; um intervalo maior resulta em 400.
Um array JSON simples (não envolvido em {"data": ...}), em ordem crescente de tempo.
Campo
Tipo
Unidade
Descrição
time
float
Segundos Unix (UTC)
Horário de abertura da barra
open / high / low / close
float
moeda de cotação (USDT)
Preços
volume
float | null
ativo base
Volume negociado; null quando a fonte não tem volume para aquela barra
Erros
Status
Corpo
Quando
403
{"error": "symbol is required"}
symbol ausente
403
{"error": "period is required"}
period ausente ou impossível de interpretar
400
{"error": "minimum supported period is 1min"}
period abaixo de um minuto
400
{"error": "periods below 5min must be a whole number of minutes"}
e.g. 90s
400
{"error": "date range exceeds max 30 days for periods below 5min"}
Period < 5min e intervalo > 30 dias
400
{"error": "invalid date format, expected YYYY-MM-DD"}
start_date / end_date malformados
400
{"error": "unknown symbol or no data: <symbol>"}
Símbolo sem cobertura (veja Sem cobertura) ou que não é um contrato real, p. ex. BTCUSDC, ETHBTC, um erro de digitação. <symbol> repete o valor que você enviou. Não é transitório — não tente novamente
Observações
Uma janela inteiramente anterior à data de listagem de um contrato coberto retorna 200 com [], não um erro.
Em 1min, toda barra retornada está fechada. Um período maior pode terminar em uma barra parcial quando end_date é hoje — ela é montada com as barras fechadas até o momento (às 07:09 UTC, a barra 1h das 07:00 contém 07:00–07:05); descarte-a se precisar apenas de barras fechadas.
Para históricos além de uma janela, envie uma requisição por janela e concatene (p. ex. 3 anos de 5min = 3 requisições; 1 ano de 1min = 13 requisições de ≤30 dias).
Todos os 740 perpétuos USDT têm o histórico completo de 1 minuto em disco, então uma requisição profunda é respondida a partir dos dados armazenados — não há uma primeira busca lenta.
A data de início vale para todos os intervalos, incluindo 1min.
A última barra fechada de 1 minuto normalmente fica disponível no minuto seguinte; em raros casos de degradação, as barras mais novas podem atrasar cerca de 5–10 minutos.
Cache do servidor: 30 s (1min), 300 s (1h / 4h / 1d), 60 s (todos os outros períodos); apenas 5 s quando a última barra fechada ainda não chegou.
Sem symbol: alpha é uma única série do mercado inteiro, não uma por moeda. BTCUSDT é usado internamente apenas para alinhar as barras; não é retornado e não altera alpha. Veja Convenções dos indicadores de cripto.
{"data": {<condition_id>: {...}}}, indexado pelo id da condição (uma chave string do JSON, p. ex. "12"; envie-o de volta como o inteiro condition_id). Apenas as condições da própria conta.
Campo
Tipo
Descrição
filters
object[]
Os filtros da condição, todos combinados com AND: indicator_id (int), indicator_name ({"en", "zh"}), param (string; "-" = o padrão do indicador), operator_id (int), operator_symbol (string, p. ex. >), value (limiar)
note
string
O nome que você deu à condição ao salvá-la
name_en / name_zh
string | null
Definido apenas em condições oficiais / da comunidade; nas suas próprias condições, espere vazio ou null e leia note no lugar
description_en / description_zh
string | null
Definido apenas em condições oficiais / da comunidade; pode ser vazio ou null
Erros
Status
Corpo
Quando
403
{"error": "unsupported api feature"}
Chave não vinculada a uma conta de usuário
Observações
Cada requisição lê em tempo real as condições salvas da conta.
Um por indicador de filtro distinto, na ordem dos filtros: en / zh (nome de exibição, com o parâmetro entre parênteses quando houver), name (chave do indicador), type, url; mais value_format, value_decimals, polarity quando o indicador os define
symbols
object[]
Tokens que atendem a todos os filtros
symbols[].symbol
string
Token sem USDT (p. ex. BTC)
symbols[].id
int
Id do token (0 quando desconhecido)
symbols[].user_selected
bool
O token está na Watchlist da conta
symbols[].price
float
Preço mais recente em USDT (mesmo feed de /price; 0 quando indisponível)
symbols[].24h_chg
float
Variação de 24h como fração (0.025 = +2.5%)
symbols[].alphas
float[]
O valor do token para cada indicador de filtro, em paralelo com alpha_names
symbols[].alpha_notes
object[]
Por indicador: indicator_id, color, direction, note (mais background_color quando uma regra foi atendida; colornull e strings vazias quando nenhuma foi)
Erros
Status
Corpo
Quando
400
{"error": "Missing parameter: condition_id is required."}
Ausente
400
{"error": "Invalid parameter: condition_id must be an integer."}
Não é um inteiro
404
{"error": "Invalid condition_id: <id> not found for user."}
{"data": {"alpha": {<sector>: {"data": [...], "name_en": ..., "name_zh": ...}}, "timestamp": [...]}}. timestamp fica ao lado de alpha no topo de data, não dentro de cada setor; é o eixo de tempo comum às séries de todos os setores.
Campo
Tipo
Descrição
timestamp
float[]
Segundos Unix (UTC), um por ponto — 366 pontos diários na resposta observada
alpha.<sector>.data
float[]
A série do setor, com o mesmo tamanho e a mesma ordem de timestamp (366); o primeiro elemento é 0.0
alpha.<sector>.name_en / name_zh
string
Nome de exibição do setor
Erros
Apenas os erros comuns.
Observações
A série é uma janela diária do último ano (366 pontos diários), e todo setor começa em 0.0. Não há parâmetros, e cada reconstrução recalcula apenas os últimos 365 dias, então não existe histórico mais longo.
Reconstruído por um job agendado, com reconstruções a cada 50–60 minutos; servido a partir da saída do job, sem cache adicional do servidor.
Z-score da variação de OI (ou do volume) somada em timeframe contra a sua média de 30 dias
stat
object
Veja objeto stat
Erros
Status
Corpo
Quando
403
{"error": "symbol is required"} / {"error": "period is required"}
Parâmetro ausente
403
{"error": "Invalid score_type"}
score_type não permitido
Observações
Cobre apenas a Binance — open interest e volume de perpétuos USDT-M.
timeframe não é validado no servidor. Um valor fora da lista foi testado, 2h, e retornou 200 com dados. Essa é uma única observação — ela não estabelece que qualquer {n}h funciona. Fique nos valores listados, a menos que você verifique o que precisa.
2021-12-01 é a primeira barra 1d de BTCUSDT; outros símbolos podem começar depois.
black = squeeze ativo (Bandas de Bollinger dentro dos Canais de Keltner), grey = squeeze inativo
stat
object
Veja objeto stat
Erros
Status
Corpo
Quando
403
{"error": "symbol is required"}
Parâmetro ausente
Observações
Cobre apenas a Binance — preço de perpétuos USDT-M.
A série é preenchida: existem linhas de BTCUSDT desde 2020-01-01, mas alpha é 0.0 até 2020-02-09. Uma requisição que começa antes da data de Dados desde retorna essas linhas de preenchimento — elas são enchimento, não sinal. Descarte os zeros iniciais ou comece na data de Dados desde.
2020-02-09 é o primeiro alpha diferente de zero de BTCUSDT; outros símbolos podem começar depois.
Sem symbol: alpha é uma única série do mercado inteiro, não uma por moeda. BTCUSDT é usado internamente apenas para alinhar as barras; não é retornado e não altera alpha. Veja Convenções dos indicadores de cripto.
{"data": {"timestamp": [...], "alpha": [...]}}. Sem stat.
Campo
Tipo
Descrição
timestamp
float[]
Segundos Unix (UTC)
alpha
float[]
Exposição líquida dos top traders da Blave (os 10% maiores por ativos da conta) — a mediana, entre esses traders, da posição nocional líquida de cada trader ÷ seus próprios ativos, ×100 (positivo = líquido comprado). Uma razão bruta, não um z-score
Erros
Status
Corpo
Quando
403
{"error": "period is required"}
Parâmetro ausente
Observações
Uma única série do mercado inteiro, cobrindo todas as moedas que esses traders detêm; não há dimensão de símbolo.
(liquidações de vendidos − de comprados, em moedas) somadas em timeframe ÷ o seu desvio padrão móvel de 30 dias; a média não é subtraída. > 0 = mais vendidos do que comprados liquidados, < 0 = mais comprados
stat
object
Veja objeto stat
Erros
Status
Corpo
Quando
400
{"error": "symbol is required"} / {"error": "period is required"}
Parâmetro ausente
Observações
A série é preenchida: existem linhas de BTCUSDT desde 2020-01-01, mas alpha é 0.0 até 2023-01-01. Uma requisição que começa antes da data de Dados desde retorna essas linhas de preenchimento — elas são enchimento, não sinal. Descarte os zeros iniciais ou comece na data de Dados desde. Os símbolos que não são BTC/ETH passam a ter valores diferentes de zero ainda mais tarde, então verifique símbolo a símbolo.
Alocação estimada do open interest da Binance em cada bucket (estimativa do modelo, não posições reais)
cumsum
float[]
USD
Exposição acumulada a liquidações entre os buckets
liquidation
object
USD
{"24h": {"buy_liq": [...], "sell_liq": [...]}} — liquidações reais de ordens forçadas da Binance nas últimas 24 h por bucket, cada uma dividida por uma premissa fixa de 0.3 de participação da Binance: buy_liq = liquidações de vendidos, sell_liq = liquidações de comprados
Nova exposição estimada a liquidações nas últimas 0–1 h, por bucket: diferença positiva entre snapshots do mapa do modelo, não liquidações reais
hist_1_8h
float[]
USD
Últimas 1–8 h
hist_8_24h
float[]
USD
Últimas 8–24 h
Erros
Status
Corpo
Quando
400
{"error": "symbol is required"}
Parâmetro ausente
Observações
Cada requisição reconstrói o mapa atual (cache do servidor de 5 s) e o compara com snapshots do mapa salvos há cerca de 1 h, 8 h e 24 h. Os snapshots são salvos a cada 30 minutos para todos os símbolos, além de a cada requisição do mapa.
As liquidações forçadas de uma moeda em todos os feeds de exchanges que a Blave coleta: quatro janelas móveis com a divisão por exchange, uma série horária de 24 pontos e as observações de cobertura de cada feed. Este é o fluxo real de liquidações (como a entrada de get_alpha), não a estimativa do modelo por trás de get_map.
Parâmetros
Nome
Descrição
Valores permitidos
Padrão
symbol
string · queryObrigatório
Moeda. O sufixo de cotação é removido; o symbol da resposta é o nome normalizado da moeda
Somado entre as exchanges; long = posições compradas liquidadas (o preço caiu), short = vendidas liquidadas (o preço subiu)
windows.<h>.long_pct / short_pct
float / null
razão 0–1
Participação no total da janela; null quando o total da janela é 0
windows.<h>.covered_hours
float
h
Quantas horas da janela realmente têm buckets (< h logo depois de um reinício do coletor)
windows.<h>.by_exchange
object
USD
{exchange: {total_liq_usd, long_liq_usd, short_liq_usd}}. Uma exchange sem evento na janela não tem chave — leia exchanges[] para distinguir "feed ativo, esta moeda sem movimento" de "feed ausente"
exchanges[]
object[]
—
Uma linha por feed (seis hoje, presentes mesmo sem evento), ordenadas pelo total de 24 h decrescente e depois pela ordem da lista de feeds
exchanges[].exchange
string
—
binance, bybit, gate, okx, htx, bitfinex
exchanges[].listed
bool / null
—
Se essa exchange lista um perpétuo com margem em USDT para a moeda; null quando a lista de contratos não pôde ser obtida (Bitfinex sempre null)
exchanges[].last_event_at
string / null
ISO 8601 UTC
Último bucket visto desse feed (qualquer moeda); null se nunca foi visto
exchanges[].price_basis
string
—
Preço usado na conversão para USD: trade_avg, bankruptcy, unverified
exchanges[].coverage
string
—
Completude do feed: full, full_unstated, sampled_1s, aggregated_1s, sampled_undisclosed
exchanges[].time_basis
string
—
event — agrupado em buckets pelo timestamp do próprio evento
detail_complete
bool
—
false quando a moeda pode ter sido cortada de uma lista de detalhes completa por bucket (os feeds mantêm as 100 maiores moedas por bucket de 5 minutos): nesse caso, windows pode contar a menos. As 50 maiores moedas são quase sempre true
series.bucket_seconds
int
s
Sempre 3600
series.points
object[]
—
Sempre 24 entradas, da mais antiga → para a mais recente, em horas cheias; a última é a hora corrente até updated_at (o snapshot é reconstruído a cada 5 min, então pode ficar alguns minutos atrás da requisição). Cada uma é {ts, long_liq_usd, short_liq_usd}; horas sem evento são 0, nunca ausentes
windows["24"] é a mesma janela móvel da matriz de exchanges, então a mesma moeda mostra lá o mesmo número de 24 h. series está em horas cheias, então Σ points ≠ windows["24"] por construção: tire os totais de windows e a distribuição no tempo de series.
Erros
Status
Corpo
Quando
400
{"error": "symbol is required"}
symbol ausente, em branco, com mais de 32 caracteres, ou sem nada restante depois que o sufixo de cotação é removido (p. ex. symbol=USDT)
404
{"error": "<SYMBOL> is not a collected symbol"}
Nenhuma exchange lista a moeda e nenhum feed a reportou nas últimas 24 h — uma resposta, não uma falha transitória
503
{"error": "liquidation data unavailable"}
Os buckets do upstream não responderam — tente novamente mais tarde; nunca leia isso como "0 liquidações"
Observações
Cobre os feeds de liquidações de Binance, Bybit, Gate.io, OKX, HTX e Bitfinex.
Apenas snapshot: sem start_date / end_date, e nada com mais de 24 h. Para histórico, use get_alpha (um desequilíbrio long/short normalizado, não valores em USD).
O tratamento de símbolos difere dos outros endpoints de liquidações: get_alpha / get_map precisam do formato do perpétuo da Binance (BTCUSDT); aqui, BTC e BTCUSDT são a mesma moeda.
Cache do servidor: 5 minutos.
O nocional em USD é convertido no momento da coleta, então as exchanges podem ser somadas.
Janela móvel, alinhada a 5 minutos (padrão: últimas 24 h)
Atualização
A cada 5 minutos
Liquidações forçadas do mercado inteiro, agregadas por exchange e como uma matriz moeda × exchange — o complemento, para o mercado inteiro, de /liquidation/get_coin. Mesma janela móvel alinhada a 5 minutos, então o total de 24 h de uma moeda é o mesmo número nos dois.
Parâmetros
Nome
Descrição
Valores permitidos
Padrão
hours
int · query
Tamanho da janela. Fora do intervalo → 400 (não é limitado); um valor não inteiro recai silenciosamente no padrão
1–168
24
top_n
int · query
Quantas moedas listar individualmente; as demais vão para others. Mesmas regras de intervalo / valor não inteiro de hours
Uma linha por feed, em ordem decrescente de total: exchange, total_liq_usd, long_liq_usd, short_liq_usd, long_pct, short_pct, events, last_event_at. Todos os feeds são sempre listados: valores null = nenhum dado recebido desse feed na janela (ordenados por último), 0.0 = conectado, mas sem liquidações
exchanges[].price_basis / .coverage / .time_basis
string
—
Quão comparável é essa linha: trade_avg / bankruptcy / unverified; full, full_unstated, sampled_1s, aggregated_1s, sampled_undisclosed; event. Mantenha esses campos ao republicar os números — um feed amostrado não é um feed completo
coins[]
object[]
—
As top_n maiores pelo total entre exchanges: token, token_id (0 quando o símbolo não tem id de token), total_liq_usd, long_liq_usd, short_liq_usd, by_exchange{name: {total/long/short_liq_usd}}. by_exchange é esparso — um feed sem nada para aquela moeda não tem chave; leia como 0 quando o total desse feed em exchanges[] não for null
others
object
—
Tudo o que top_n cortou, com os mesmos campos mais coin_count, de modo que coins[] + others volta a somar o total de cada exchange
Horas da janela que realmente têm buckets (< hours logo depois de um reinício do coletor)
buckets
int
—
Número de buckets de 5 minutos agregados
window_hours / window_start / window_end
int / string
h / ISO 8601 UTC
A janela conforme resolvida pelo servidor
updated_at
string
ISO 8601 UTC
Último bucket usado
long_liq_usd = posições compradas liquidadas (o preço caiu); short_liq_usd = vendidas liquidadas (o preço subiu).
Erros
Status
Corpo
Quando
400
{"error": "hours must be between 1 and 168"} / {"error": "top_n must be between 1 and 50"}
Parâmetro fora do intervalo
Observações
Cobre os feeds de liquidações de Binance, Bybit, Gate.io, OKX, HTX e Bitfinex.
A ausência total de dados (feeds fora do ar, ou fonte de dados inacessível) ainda é um 200 com a mesma estrutura e todos os valores null, buckets: 0 — nunca uma tabela de zeros. Verifique total.total_liq_usd antes de usar os números.
Apenas totais — sem série temporal. O perfil horário de uma moeda está em /liquidation/get_coin; um sinal normalizado com histórico longo está em /liquidation/get_alpha.
A janela é móvel, não um dia civil, e é a mesma janela que /liquidation/get_coin usa em windows["24"].
Cache do servidor: 5 minutos.
O nocional em USD é convertido no momento da coleta, então as exchanges podem ser somadas.
Todas as moedas coletadas × todas as fontes de ratio long/short, no momento atual. Dez fontes: Binance, OKX e Gate.io publicam três tipos cada — todas as contas, contas de top traders, posições de top traders — e a Bybit publica apenas contas. As linhas são ordenadas pelo nocional de open interest da Binance. Apenas as moedas que correspondem a uma entrada na lista de tokens da Blave são listadas; a resposta com chave de API é a tabela completa (full: true), e a versão anônima do Studio traz apenas as linhas da sua whitelist de 30 moedas.
Parâmetros
Nenhum.
Exemplo
Python
data = requests.get(f"{BASE_URL}/long_short_ratio/get_table", headers=headers, timeout=30).json()["data"]keys = [s["key"] for s in data["sources"] ifnot s["stale"]]btc = next(c for c in data["coins"] if c["token"] == "BTC")print({k: btc[k] for k in keys if btc[k] is notNone})#Live capture 2026-09-22 via the anonymous studio twin (/studio/charts/long_short_ratio/table) —#same inner shape; the API-key response wraps it in "data" and has full: true with every row.#{"coins": [{"binance_account": 0.8818, "binance_top_account": 1.0149, "binance_top_position": 2.2666,#"bybit_account": 1.0375, "gate_account": 0.7294, "gate_top_account": 0.6944,#"gate_top_position": 1.6436, "okx_account": 0.9084, "okx_top_account": 0.8655,#"okx_top_position": 1.0222, "token": "BTC", "token_id": 1}, ...],#"sources": [{"exchange": "binance", "key": "binance_account", "last_at": "2026-09-22T05:50:00+00:00",#"stale": false, "type": "account"}, ...,#{"exchange": "bybit", "key": "bybit_account", "last_at": "2026-09-22T05:50:00+00:00",#"stale": false, "type": "account"}],#"summary": {"binance_long_majority": 436, "binance_tokens": 509},#"tokens_shown": 30, "tokens_total": 611, "full": false, "updated_at": "2026-09-22T05:50:00+00:00"}
Início da coleta (primeiro bucket armazenado, medido no BTC em 2026-09-22)
Todas as fontes já são mais antigas do que os 7 dias que este dataset fornece, então nenhuma delas limita uma consulta — as datas só importam se lhe disserem que uma fonte "não tem histórico".
Uma linha por moeda: token, token_id, mais um valor por chave de fonte
coins[].<source key>
float / null
razão
Contas (ou posições) compradas ÷ vendidas. null = essa exchange não tem esse feed para a moeda. Participação comprada = r / (1 + r) — a API não a calcula previamente
sources[]
object[]
—
Os dez feeds, na ordem das colunas. Leia este campo, nunca uma lista de chaves fixa no código
sources[].key
string
—
<exchange>_<type>, p. ex. binance_top_position — a chave usada em coins[]
A amostra mais nova desse feed tem mais de 1 hora (medida em relação a agora). O updated_at de nível superior é o da fonte mais nova e não diz nada sobre nenhuma fonte isolada — avalie uma fonte pelo seu próprio last_at / stale
summary.binance_tokens / .binance_long_majority
int
—
Moedas com um ratio de contas da Binance / dessas, quantas estão acima de 1. Calculado sobre a tabela inteira, não sobre as linhas exibidas
tokens_shown / tokens_total
int
—
Linhas retornadas / linhas na tabela. Iguais com uma chave de API
full
bool
—
true com uma chave de API; false na versão anônima do Studio
updated_at
string
ISO 8601 UTC
Bucket mais novo entre as fontes
"Top trader" é uma população diferente em cada exchange — não compare os níveis entre exchanges.
Exchange
Quem conta como top trader (texto oficial original)
Binance
"the top 20% users with the highest margin balance"
OKX
"the top 5% of traders with the largest open position value"
Gate.io
Nunca publicado — a documentação apenas nomeia os campos
Portanto, binance_top_account acima de okx_top_account não diz nada sobre em qual exchange os grandes traders estão mais comprados. Compare cada fonte com o seu próprio histórico.
Erros
Status
Corpo
Quando
503
{"error": "long short ratio data unavailable"}
Sem snapshot recente — tente novamente mais tarde; nunca leia isso como um mercado vazio
Observações
Um corte transversal, não um histórico. Para uma série, use /long_short_ratio/get_coin (7 dias) — não há endpoint de histórico longo para este dataset.
A granularidade é de 5 minutos, mas cada fonte publica no seu próprio relógio — não descreva como "atualiza a cada 5 minutos".
O snapshot é o último bucket que cada fonte publicou; os buckets da Gate.io e da OKX chegam com cerca de 10 minutos de atraso.
Últimos 7 dias, por hora + o ponto de 5 minutos mais recente
Atualização
Buckets de 5 minutos
Uma moeda, todas as dez fontes: o valor de 5 minutos mais recente de cada uma, uma série horária de 7 dias por fonte e o fechamento do perpétuo da Binance na mesma janela.
Parâmetros
Nome
Descrição
Valores permitidos
Padrão
symbol
string · queryObrigatório
Moeda. O sufixo de cotação é removido; o symbol da resposta é o nome normalizado da moeda
BTC, BTCUSDT, btc (≤ 32 caracteres)
Exemplo
Python
params = {"symbol": "BTC"}data = requests.get(f"{BASE_URL}/long_short_ratio/get_coin", headers=headers, params=params, timeout=30).json()["data"]latest = data["latest"]["binance_top_position"] # null when Binance does not list the coinif latest is notNone:r = latest["value"]print("top-trader long share:", round(r / (1 + r), 4))#Live capture 2026-09-22 (abridged with ...; anonymous studio twin, same inner shape):#{"latest": {"binance_account": {"ts": "2026-09-22T05:50:00+00:00", "value": 0.8818},#"binance_top_account": {"ts": "2026-09-22T05:50:00+00:00", "value": 1.0149}, ... 10 keys},#"series": {"bucket_seconds": 3600, "days": 7, "price_symbol": "BTCUSDT", "price_multiplier": 1,#"provisional_from": 1790053200,#"timestamp": [..., 1790049600, 1790053200],#"binance_account": [..., 0.8699, 0.8818], "price": [..., 85424.7, 85495.8], ... one array per source},#"sources": [{"exchange": "binance", "key": "binance_account", "last_at": "2026-09-22T05:50:00+00:00",#"listed": true, "stale": false, "type": "account"}, ... 10 rows],#"symbol": "BTC", "token_id": 1, "updated_at": "2026-09-22T05:50:00+00:00"}
{value, ts} — a amostra de 5 minutos mais nova dessa fonte; null quando a fonte não lista a moeda
series.bucket_seconds / .days
int
s / d
3600 / 7
series.timestamp
int[]
epoch s
168 slots, do mais antigo → para o mais recente, um por hora
series.<source key>
float[] / null
razão
Última amostra de cada hora; null para uma hora sem amostra. O campo inteiro é um único null (não um array) para uma fonte que não lista a moeda
series.price
float[] / null
USD
Fechamento do perpétuo da Binance na mesma janela. Um único null (com price_symbol / price_multiplier também null) quando a moeda não tem perpétuo na Binance
series.price_symbol / .price_multiplier
string / int
—
De qual perpétuo veio o preço e o seu multiplicador de contrato (1000PEPEUSDT → 1000; price ÷ price_multiplier = preço por moeda)
series.provisional_from
int / null
epoch s
Primeiro slot que ainda pode mudar (as fontes finalizam com até ~10 min de atraso); null quando nenhuma fonte tem dados
sources[]
object[]
—
A lista completa de fontes, com os mesmos campos da tabela mais listed
sources[].listed
bool
—
false = essa exchange não tem esse feed para esta moeda; suas entradas em latest e series são null
symbol / token_id / updated_at
—
—
Como na tabela
Erros
Status
Corpo
Quando
400
{"error": "symbol is required"}
symbol ausente, em branco, com mais de 32 caracteres, ou sem nada restante depois que o sufixo de cotação é removido
404
{"error": "<SYMBOL> is not a collected symbol"}
Nenhuma fonte coleta a moeda — uma resposta, não uma falha transitória
503
{"error": "long short ratio data unavailable"}
Uma fonte listada não pôde ser lida. null sempre significa apenas "essa exchange não lista a moeda"
Observações
Cobre os feeds de ratio long/short de Binance, OKX, Gate.io e Bybit.
A ressalva sobre "top trader" entre exchanges de /long_short_ratio/get_table vale aqui também.
7 dias é todo o histórico que este endpoint fornece; não há start_date / end_date.
Sobre a "versão anônima do Studio" em todas as capturas dos endpoints de dados brutos desta página: as páginas do Studio (/studio/charts/...) servem o mesmo payload, do mesmo construtor, sem chave, e foi delas que estes exemplos foram tirados. Elas não substituem os endpoints com chave de API: as tabelas são cortadas em 30 moedas (full: false), e uma moeda fora da whitelist do Studio responde 403 {"error_code": "ERR001", ..., "anon_whitelist": [...]} em vez de dados. Os endpoints com chave de API documentados aqui não têm whitelist nem corte de linhas.
Os buckets da Gate.io e da OKX chegam com cerca de 10 minutos de atraso.
Todas as moedas coletadas × cinco exchanges, em nocional USD. Base: apenas perpétuos com margem em USDT, nocional em USD, um lado. Uma exchange que reporta os dois lados é dividida pela metade (exchanges[].side_factor, Gate.io = 0.5). Como todo valor já é nocional em USD, os contratos com multiplicador (1000PEPE e similares) se somam entre exchanges sem reescala.
Parâmetros
Nenhum.
Exemplo
Python
data = requests.get(f"{BASE_URL}/oi_imbalance/get_table", headers=headers, timeout=30).json()["data"]crowded = sorted((c for c in data["coins"] if c["oi_mcap"] is notNone), key=lambda c: -c["oi_mcap"])[:10]print(data["total"]["oi"], [(c["token"], round(c["oi_mcap"], 4)) for c in crowded])#Live capture 2026-09-22 (abridged with ...; anonymous studio twin, same inner shape):#{"coins": [{"token": "BTC", "token_id": 1, "oi_total": 18645450917.48, "chg_1h": -0.001775,#"chg_4h": -0.001046, "chg_24h": 0.128725, "market_cap": 1629947967503.241, "oi_mcap": 0.011439,#"by_exchange": {"binance": {"oi": 9417422808.02, "chg_1h": 2e-05, "chg_4h": 0.010203, "chg_24h": 0.067527},#"bingx": {"oi": 1328003926.8, ...},#"bybit": {"oi": 2569097877.96, "chg_1h": -0.008636, "chg_4h": -0.030159, "chg_24h": null},#"gate": {...}, "okx": {"oi": 2575361192.92, ..., "chg_24h": null}}}, ...],#"exchanges": [{"key": "binance", "oi": 24712717530.01, "side_factor": 1.0, "since": null, "full_7d": true,#"last_at": "2026-09-22T05:25:00+00:00", "stale": false}, ... 5 rows],#"total": {"oi": 47428938620.05, "chg_1h": -0.008919, "chg_4h": -0.010508, "chg_24h": 0.073881,#"n_exchanges": 5, "n_full_7d": 3},#"summary": {"oi_mcap_leader": "SAGA", "oi_mcap_leader_value": 1.718336},#"tokens_shown": 30, "tokens_total": 622, "full": false, "updated_at": "2026-09-22T05:30:00+00:00"}
Início da coleta (primeiro bucket armazenado, medido no BTC em 2026-09-22)
Exchange
Coletando desde
binance
2021-12-01
bingx
2025-04-15
gate
2026-08-12
okx
2026-09-21
bybit
2026-09-21
OKX e Bybit são o motivo de n_full_7d ser 3 de 5 e de o chg_24h delas ainda ser null em 2026-09-22 — leia exchanges[].since / full_7d em vez destas datas, que ficam desatualizadas.
Variação decimal (0.0675 = +6.75 %). Cada janela conta apenas as exchanges que têm uma linha de base no início dessa janela, com numerador e denominador sobre o mesmo conjunto; null quando nenhuma tem
coins[].market_cap
float / null
USD
Capitalização de mercado; null quando não há uma utilizável
coins[].oi_mcap
float / null
razão
oi_total ÷ market_cap; null quando o token não tem capitalização de mercado
coins[].by_exchange
object
—
{exchange: {oi, chg_1h, chg_4h, chg_24h}}, uma chave por exchange; null quando a moeda não é listada lá. Um null em uma janela significa que essa exchange não tinha linha de base tão antiga — um feed mais novo do que a janela
exchanges[]
object[]
—
binance, okx, bingx, bybit, gate — oi do mercado inteiro, side_factor, since, full_7d, last_at, stale
exchanges[].since / .full_7d
string / bool
data
O primeiro dia do feed quando ele tem menos de 7 dias de histórico (full_7d: false); caso contrário, null / true. Apenas informativo nesta tabela (ela não tem janela de 7 dias); em /oi_imbalance/get_coin, um feed assim não tem linha de base de 7 d e fica fora de series.total
total
object
—
oi, chg_1h/4h/24h, n_exchanges, n_full_7d do mercado inteiro
summary.oi_mcap_leader / _value
string / float
—
Maior OI ÷ capitalização de mercado entre as 100 maiores moedas por OI
tokens_shown / tokens_total / full / updated_at
—
—
Como na tabela de ratio long/short
Não é o mesmo número do indicador OI 失衡./oi_imbalance/get_overview_data (e o alpha oi_imbalance por trás das condições do Screener e dos alertas) é um agregado de três exchanges — Binance + OKX + BingX. Esta tabela é de cinco exchanges, na base descrita acima. Os dois valores de oi_total diferem, então um limiar ajustado em um não vale para o outro.
Erros
Status
Corpo
Quando
503
{"error": "open interest data unavailable"}
O job não tem resultado recente (ausente ou com mais de uma hora) — nunca uma tabela de zeros
Observações
chg_24h: null em OKX / Bybit na captura acima é a regra do feed novo, não uma lacuna no mercado: as duas começaram em 2026-09-21, então ainda não tinham linha de base de 24 h.
Um corte transversal, não um histórico. Os últimos 7 dias de uma moeda (por hora, todas as cinco exchanges) estão em /oi_imbalance/get_coin; o histórico com extensão para backtest de uma moeda em uma exchange está em /oi_imbalance/get_history.
O snapshot traz as variações de 1 h / 4 h / 24 h. É reconstruído por um job agendado a cada 15 minutos, aproximadamente, a partir de buckets de origem de 5 minutos; os buckets da Gate.io e da OKX chegam com cerca de 10 minutos de atraso.
O open interest de uma moeda por exchange, na mesma base da tabela: valor atual e participação, quatro janelas de variação com as exchanges contadas em cada uma, e uma linha de total horário de 7 dias.
Parâmetros
symbol, exatamente como em /long_short_ratio/get_coin.
A lista completa das cinco exchanges: key, oi (USD), share (de oi_total), chg_1h/4h/24h/7d, side_factor, listed, since, full_7d, last_at, stale
exchanges[].listed
bool
—
false = a moeda não é listada lá; seus valores são null
oi_total / market_cap / oi_mcap
float
USD / razão
Como na tabela
oi_mcap_rank / tokens_total
int / null
—
Posição por oi_mcap na última rodada do job da tabela; null quando esse job não tem resultado recente
windows.<1h|4h|24h|7d>.chg / .chg_usd
float / null
fração / USD
Variação do total das exchanges contadas
windows.<w>.exchanges
string[]
—
Quais exchanges foram contadas nessa janela — um feed novo fica ausente, então 24 h / 7 d podem contar menos exchanges do que 1 h
series.timestamp
int[]
epoch s
168 slots horários, do mais antigo → para o mais recente
series.total
float[] / null
USD
OI total por slot — apenas as series.total_exchanges (os feeds full_7d) entram nesta linha, então ela não é comparável em nível com oi_total. Um slot é null quando alguma dessas exchanges não tem amostra naquela hora; o campo inteiro é null quando nenhuma exchange é full_7d para a moeda
400 / 404 / 503 exatamente como em /long_short_ratio/get_coin, com {"error": "open interest data unavailable"} no 503.
Observações
Cobre o open interest de Binance, OKX, BingX, Bybit e Gate.io.
windows["1h"]["exchanges"] ter cinco entradas enquanto windows["24h"] tem três é a regra do feed novo, não dados faltando — leia essa lista antes de comparar janelas.
A ressalva sobre o OI 失衡 de /oi_imbalance/get_table vale também para este oi_total.
Apenas sete dias. Para uma série mais longa para backtest, use /oi_imbalance/get_history (uma exchange, em moedas em vez de USD — uma base diferente da de oi_total).
Os buckets da Gate.io e da OKX chegam com cerca de 10 minutos de atraso.
O open interest de uma moeda em uma exchange, como uma série temporal que pode ser usada em backtest — a mesma base do card 未平倉量 do dashboard do Studio. alpha é o open interest de um lado, em moedas, não em USD. Os contratos com multiplicador são convertidos de volta para moedas (1000PEPE retorna uma quantidade de PEPE). Cada bucket é a última leitura do seu período — o open interest é um estoque, nunca é somado.
Parâmetros
Nome
Descrição
Valores permitidos
Padrão
symbol
string · queryObrigatório
Moeda, mesma regra de /oi_imbalance/get_coin
BTC, BTCUSDT, btc
period
string · queryObrigatório
Tamanho do bucket. 1w resulta em 400 (unidade não suportada); 1m é lido como 1min, então resulta em 400 por estar abaixo de 5min
binance, bybit, gate (sem diferenciar maiúsculas de minúsculas)
binance
Janela por requisição: no máximo 365 dias; um intervalo maior é limitado silenciosamente (start_date é movido para end_date − 365 dias, sem erro), como em /kline.
{"data": {"timestamp", "alpha", "close", "exchanges"}}, arrays paralelos, do mais antigo → para o mais recente.
Campo
Tipo
Unidade
Descrição
timestamp
float[]
Segundos Unix (UTC)
Início do bucket
alpha
float[]
moedas
Open interest de um lado em oi_exchange, última leitura do bucket
close
float[]
USDT
Preço do perpétuo USDT-M da Binance — por unidade de contrato, ou seja, por 1000 moedas no caso de 1000PEPE
exchanges
string[]
—
A exchange efetivamente lida, p. ex. ["binance"]
alpha × close não é o open interest em USD em um contrato com multiplicador. Nesse caso, close é o preço por unidade de contrato (por 1000 moedas no caso de 1000PEPE), enquanto alpha está em moedas unitárias — divida close pelo multiplicador primeiro. Para contratos sem multiplicador, como BTC, alpha × close ≈ open interest em USD.
Gate.io: envie sempre start_date ≥ 2026-03-28 — a janela padrão (end_date − 365 dias) começa antes do histórico da Gate e resulta em 400.
Não é o mesmo número de /oi_imbalance/get_table / get_coin (cinco exchanges somadas, em USD) nem o indicador OI 失衡 (/oi_imbalance/get_overview_data).
Erros
Status
Corpo
Quando
400
{"error": "symbol is required"} / {"error": "period is required"}
Ausente (aqui um 400, não o 403 dos endpoints de indicadores)
400
{"error": "period must be at least 5min, in min / h / d units"}
period abaixo de 5min (incluindo 1m, lido como 1min) ou em uma unidade que não seja min / h / d (1w)
400
{"error": "invalid date format, expected YYYY-MM-DD"}
start_date / end_date malformados
400
{"error": "start_date must not be after end_date"}
start_date > end_date
400
{"error": "oi_exchange must be one of binance, bybit, gate"}
oi_exchange fora da lista
400
{"error": "no <exchange> open interest for <TOKEN> at start_date; this exchange's history may start later — try a later start_date"}
A janela começa antes do histórico dessa exchange (veja Dados desde). Sem start_date, oi_exchange=gate sempre cai neste erro até que o seu histórico passe de 365 dias (≈ 2027-03) — para a Gate, envie sempre start_date ≥ 2026-03-28
404
{"error": "<TOKEN> is not a collected symbol on <exchange>"}
Essa exchange não lista a moeda, a moeda não tem perpétuo na Binance, ou foi deslistada — uma resposta, não uma falha transitória
503
{"error": "<exchange> open interest data unavailable for <TOKEN>"}
Os dados não puderam ser lidos agora — tente novamente
Observações
Cobre o open interest de Binance, Bybit e Gate.io; close é o preço do perpétuo USDT-M da Binance.
200 com arrays vazios significa que não há bucket nessa janela (p. ex. a moeda foi listada depois dela) — não guarde isso em cache como um "sem dados" permanente.
O último bucket continua mudando até o seu período fechar quando end_date é hoje.
Para históricos além de 365 dias, envie uma requisição por ano e concatene.
A resolução é de 5 minutos. A série de cada exchange começa na data de Dados desde, ou na data de listagem da moeda nessa exchange, se posterior. Apenas contratos listados atualmente.
Volume financeiro de compra e venda taker (ordens a mercado) por moeda, em USD, em três exchanges: Binance, a partir do volume de cotação de compra taker do kline de 5 minutos (venda = o total da barra menos ele); OKX, a partir do seu volume taker em USD; Gate.io, a partir dos contratos taker × o multiplicador e o preço de marcação da mesma linha. Apenas perpétuos — sem spot — e agregado a partir de barras de 5 minutos, não de negócio a negócio. É usado o volume financeiro reportado por cada exchange; o volume nunca é multiplicado por um preço emprestado de outra exchange.
Parâmetros
Nenhum.
Exemplo
Python
data = requests.get(f"{BASE_URL}/taker_intensity/get_cvd_table", headers=headers, timeout=30).json()["data"]buying = sorted((c for c in data["coins"] if c["net_24h"] is notNone), key=lambda c: -c["net_24h"])[:10]print(data["total"]["net_24h"], [(c["token"], c["net_24h"]) for c in buying])#Live capture 2026-09-22 (abridged with ...; anonymous studio twin, same inner shape):#{"coins": [{"token": "BTC", "token_id": 1, "buy_24h": 24607245298.03, "sell_24h": 23128502231.73,#"net_1h": -212647361.27, "net_4h": -207128163.51, "net_24h": 1478743066.31,#"by_exchange": {"binance": {"buy_24h": 12663681424.94, "sell_24h": 12135756153.44,#"net_1h": -191133129.94, "net_4h": -217337267.5, "net_24h": 527925271.5},#"gate": {...}, "okx": {...}}}, ...],#"exchanges": [{"key": "binance", "buy_24h": 34978603608.55, "sell_24h": 35112588381.38,#"net_24h": -133984772.74, "last_at": "2026-09-22T05:25:00+00:00", "stale": false}, ... 3 rows],#"total": {"buy_24h": 63543431942.93, "sell_24h": 62491177680.21, "net_24h": 1052254262.8},#"tokens_shown": 30, "tokens_total": 591, "full": false, "updated_at": "2026-09-22T05:25:00+00:00"}
Início da coleta (primeiro bucket armazenado, medido no BTC em 2026-09-22)
Exchange
Campo de origem
Coletando desde
binance
kline de 5 minutos (volume financeiro de compra taker)
2020-01-01
gate
contract_stats
2026-08-12
okx
taker_volume_usd
2026-09-21
A OKX tem ainda o limite de a exchange manter apenas 5 dias, então fica full_7d: false até uma semana depois dessa data. Esta tabela não traz since / full_7d (ela não tem janela de 7 dias) — leia-os por moeda no exchanges[] de /taker_intensity/get_cvd_coin, não a partir destas datas.
Volume financeiro de compra / venda taker nas 24 h móveis, somado entre as exchanges não desatualizadas da moeda; null quando todas estão desatualizadas
coins[].net_1h / .net_4h / .net_24h
float / null
USD
buy − sell em cada janela móvel (mesma regra de null)
coins[].by_exchange
object
—
{exchange: {buy_24h, sell_24h, net_1h, net_4h, net_24h}}, uma chave por exchange; null quando a moeda não é listada lá ou quando os dados dessa exchange para ela estão desatualizados
exchanges[]
object[]
—
binance, okx, gate — buy_24h, sell_24h, net_24h do mercado inteiro, last_at, stale
exchanges[].stale
bool
—
A última barra desse feed tem mais de uma hora: suas janelas voltam null e ele fica fora dos totais, em vez de contribuir com uma soma que, silenciosamente, cobre menos do que a janela
total
object
USD
buy_24h, sell_24h, net_24h do mercado inteiro, sobre as exchanges com dados recentes
tokens_shown / tokens_total / full / updated_at
—
—
Como nas outras tabelas de dados brutos
Erros
Status
Corpo
Quando
503
{"error": "cvd data unavailable"}
O job não tem resultado recente — nunca zeros
Observações
Não é o mesmo que o alpha taker_intensity (/taker_intensity/get_alpha), que é um sinal normalizado, do tipo z-score, com anos de histórico. Este é o volume financeiro bruto em USD, agora.
As janelas são móveis e terminam na última barra fechada de 5 minutos, então net_24h não é um dia civil.
Reconstruído por um job agendado a cada 15 minutos, aproximadamente, a partir de buckets de origem de 5 minutos; os buckets da Gate.io e da OKX chegam com cerca de 10 minutos de atraso.
Compra / venda / líquido taker de uma moeda por exchange (mesma base da tabela), mais um líquido horário de 7 dias e o seu acumulado corrente — a própria linha do CVD.
Parâmetros
symbol, exatamente como em /long_short_ratio/get_coin.
{buy, sell, net} somados sobre as exchanges com dados recentes
exchanges[]
object[]
—
A lista completa: key, listed, windows (as mesmas quatro, por exchange), since, full_7d, last_at, stale
exchanges[].full_7d
bool
—
false = menos de 7 dias de histórico para esta moeda lá: sua janela de 7 d é null e ela é excluída do total de 7 d e da série. A OKX mantém apenas 5 dias, então fica false até uma semana depois do início do feed
series.timestamp
int[]
epoch s
168 slots horários, do mais antigo → para o mais recente
series.net
float[]
USD
Fluxo taker líquido por hora cheia, somado sobre series.exchanges; null para uma hora sem dados. Quando series.exchanges está vazio, todo slot é null e cvd fica parado em 0 — nesse caso, a linha não traz informação
series.cvd
float[]
USD
Total acumulado de net; cvd[0] = 0 — a linha é uma forma, não um nível absoluto
400 / 404 / 503 exatamente como em /long_short_ratio/get_coin, com {"error": "cvd data unavailable"} no 503.
Observações
Cobre o fluxo taker de Binance, OKX e Gate.io.
series.exchanges ser mais curto do que exchanges[] é a regra de full_7d — compare a série com ela mesma, não com windows["24h"], que conta mais exchanges.
cvd[0] = 0 por construção: apenas a inclinação e os pontos de virada trazem informação.
Os buckets da Gate.io e da OKX chegam com cerca de 10 minutos de atraso.
Semanal, sexta-feira às 15:30 do horário do Leste dos EUA
A linha semanal mais recente da CFTC para cada um dos quatro futuros de cripto da CME, mais a soma de standard + micro em moedas por ativo. Mesma estrutura de uma linha de /cme_cot/get_history, sem price.
Um por contrato: key (btc, micro_btc, eth, micro_eth), name, cftc_code, coin, coin_per_contract (5 / 0.1 / 50 / 0.1), latest (uma linha, veja get_history; null se o contrato não tem linhas)
combined[]
btc_combined, eth_combined: name, coin, components, units, micro_since, note, latest (uma linha combinada, em moedas)
report
futures_only
units
Unidade das posições em contracts[].latest: contratos (× coin_per_contract para obter moedas)
source
Linha de atribuição à CFTC — exiba-a com qualquer número que você publicar
source_updated
Quando a CFTC atualizou o dataset pela última vez
fetched_at
Quando a Blave o buscou (UTC)
stale
true = a CFTC estava inacessível e a última cópia armazenada é servida
Erros
Status
Corpo
Quando
503
{"error": "CFTC data unavailable. Please retry shortly."}
CFTC inacessível e sem cópia armazenada
Observações
Para histórico, use /cme_cot/get_history.
As posições são referentes à terça-feira (segunda-feira quando a terça é feriado nos EUA) e são publicadas pela CFTC na sexta-feira da mesma semana, às 15:30 do horário do Leste dos EUA; um feriado federal entre quarta e sexta-feira adia a divulgação para o dia útil seguinte, e uma paralisação do governo a atrasa em semanas.
Semanal, sexta-feira às 15:30 do horário do Leste dos EUA
O posicionamento semanal de um contrato por categoria de trader. As linhas são datadas pela data do relatório — o dia a que as posições se referem, normalmente uma terça-feira (uma segunda-feira quando a terça é feriado nos EUA). Os dados se tornaram públicos depois: normalmente na sexta-feira da mesma semana, às 15:30 ET; um feriado federal entre quarta e sexta-feira adia a divulgação para o dia útil seguinte, e uma paralisação do governo a atrasa em semanas (os relatórios de 2018-12-24 … 2019-02-26 saíram em 2019-02-01 … 03-05; os relatórios de 2025-09-30 … 2026-01-20, em 2025-11-19 … 2026-01-23 — CFTC Releases 7864-19 e 9138-25). Um backtest não deve agir sobre uma linha antes da sua divulgação.
Parâmetros
Nome
Descrição
Valores permitidos
Padrão
contract
string · query
Contratos individuais são em contratos; *_combined = standard + micro somados em moedas
btc, micro_btc, eth, micro_eth, btc_combined, eth_combined (sem diferenciar maiúsculas de minúsculas)
btc
start_date
string · query
Primeira data de relatório, inclusive. Omitido = apenas o último ano — passe uma data antiga (p. ex. 2018-01-01) para obter o histórico completo
{"data": {"contract": {...}, "rows": [...], "price_source", "report", "units", "source", "source_updated", "fetched_at", "stale"}}, linhas da mais antiga → para a mais recente.
contract: key, name, coin, e cftc_code + coin_per_contract (contrato individual) ou components + micro_since + note (combinado).
Cada linha:
Campo
Tipo
Descrição
date
string
Data do relatório — normalmente uma terça-feira; uma segunda-feira quando a terça é feriado nos EUA
open_interest / open_interest_change
number
Open interest total e a sua variação semanal
tff
object
Grupos dealer, asset_manager, leveraged_funds, other_reportables, nonreportable
legacy
object | null
Grupos non_commercial, commercial, nonreportable; null se a CFTC não tem linha Legacy para aquela semana
price
float | null
Fechamento diário UTC do spot BTCUSDT / ETHUSDT da Binance na data do relatório; null quando indisponível
included
string[]
Apenas contratos combinados: quais contratos esta linha soma (["btc"] antes de micro_since)
Cada grupo: long, short, spread (não existe para nonreportable / commercial), net (= long − short), e long_change, short_change, spread_change, net_change. Unidades: contratos para um contrato individual, moedas para um combinado. Os campos *_change são os números de variação semanal da própria CFTC, não diferenças entre linhas — a CFTC pula semanas (p. ex. paralisações do governo), então nunca calcule você mesmo a diferença entre linhas.
Erros
Status
Corpo
Quando
400
{"error": "contract must be one of btc, micro_btc, eth, micro_eth, btc_combined, eth_combined"}
Contrato desconhecido
400
{"error": "Invalid start_date, expected YYYY-MM-DD"} (ou end_date) / {"error": "start_date must not be after end_date"}
Data inválida / intervalo invertido
503
{"error": "CFTC data unavailable. Please retry shortly."}
CFTC inacessível e sem cópia armazenada
Observações
*_combined tem uma quebra em micro_since: na semana em que o micro entra, os totais dão um salto e o *_change daquela semana inclui toda a primeira posição do micro. Comece um backtest combinado depois de micro_since, ou use o contrato individual btc / eth.
O histórico completo do BTC tem ~440 linhas semanais (~0.5 MB) — uma requisição, sem paginação.
Licença: os dados da CFTC são de domínio público, mas a CFTC pede que seja citada — mantenha source junto a qualquer número que você exibir. Não é endossado pela CFTC.
Data de início por contrato: btc 2018-04-10, micro_btc 2021-05-04, eth 2021-04-06, micro_eth 2021-12-14. Os futuros de BTC da própria CME entram no COT em 2018-04-10, não no lançamento, em 2017-12.
Cache do servidor: 1 hora.
price é o fechamento diário UTC do spot da Binance.
Deixe sua IA fazer quant no seu próprio computador
O Blave Desktop é grátis, de código aberto e não exige cadastro. Conecte o Claude Code ou o Codex: ele escreve a estratégia, roda o backtest e opera ao vivo.
Baixando.Arraste para Aplicativos,abra e escolha sua IA.A primeira abertura prepara o ambientee leva alguns minutos.Se gostar, dê uma estrela no GitHub.
Baixando. Ao abrir o instalador, o Windows mostra primeiro um aviso de segurança:
Clique no link abaixo do texto.
Um botão novo aparece embaixo: clique nele. O Blave se instala e abre sozinho.
A primeira abertura prepara o ambiente de execução e leva alguns minutos.
O Windows avisa porque o instalador ainda não tem assinatura de código (já solicitamos o certificado), então não consegue identificar o editor. O código-fonte é público no GitHub. Ver o passo a passo completo
