Referência da API
API de Cotação de Moedas
Cotação de qualquer par de moedas e criptomoedas, escolhido por você a cada consulta, com compra, venda, máxima, mínima e variação.
https://dev-api.primux.cloud AuthBearer SUA_CHAVE FormatoJSON · UTF-8https://dev-api.primux.cloud/v1/cotacoesVisão geral
Você informa os pares (por exemplo USD-BRL,EUR-BRL,BTC-USD) e recebe a cotação de cada um. Serve para lojas, calculadoras, sites de notícias e sistemas financeiros.
- Até 10 pares por consulta, em qualquer combinação que a fonte cote (moedas comuns e criptomoedas).
- Cada cotação traz compra, venda, máxima e mínima do dia, variação e o horário da cotação.
- /v1/cotacoes/pares lista todos os pares disponíveis, com o nome de cada um.
{
"cotacoes": [
{
"par": "EUR-BRL",
"origem": "EUR",
"destino": "BRL",
"nome": "Euro/Real Brasileiro",
"compra": 6.4983,
"venda": 6.5003,
"maxima": 6.5309,
"minima": 6.4449,
"variacao": 0.0444,
"variacao_pct": 0.687958,
"cotado_em": "2026-11-19 18:16:46"
}
],
"atualizado_em": "2026-11-19T21:32:20Z",
"desatualizado": false
}Início rápido
- Contrate a API no console (menu APIs), escolha o plano e pague a fatura.
- Abra a sessão contratada e gere a chave de API. Ela aparece uma única vez: guarde-a em uma variável de ambiente do seu servidor.
- Faça a consulta enviando a chave no cabeçalho Authorization (Bearer) e use o JSON da resposta.
O exemplo consulta dólar, euro e bitcoin, confere o status e mostra compra e venda de cada par.
curl -i "https://dev-api.primux.cloud/v1/cotacoes?pares=USD-BRL,EUR-BRL,BTC-USD" \
-H "Authorization: Bearer SUA_CHAVE"<?php
$ch = curl_init('https://dev-api.primux.cloud/v1/cotacoes?pares=USD-BRL,EUR-BRL,BTC-USD');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('PRIMUX_COTACOES_CHAVE')],
]);
$corpo = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
$dados = json_decode($corpo, true);
if ($status !== 200) {
// erro, mensagem: veja a seção Erros
exit('Erro ' . $status . ': ' . ($dados['mensagem'] ?? 'sem resposta') . PHP_EOL);
}
if ($dados['desatualizado']) {
// a fonte estava fora do ar: este é o último dado salvo (veja atualizado_em)
}
foreach ($dados['cotacoes'] as $c) {
echo $c['par'] . ': ' . $c['compra'] . ' / ' . $c['venda'] . PHP_EOL;
}const resposta = await fetch('https://dev-api.primux.cloud/v1/cotacoes?pares=USD-BRL,EUR-BRL,BTC-USD', {
headers: { Authorization: `Bearer ${process.env.PRIMUX_COTACOES_CHAVE}` },
});
const dados = await resposta.json();
if (!resposta.ok) {
// dados.erro e dados.mensagem: veja a seção Erros
throw new Error(`Erro ${resposta.status}: ${dados.mensagem}`);
}
if (dados.desatualizado) {
// a fonte estava fora do ar: este é o último dado salvo (veja atualizado_em)
}
for (const c of dados.cotacoes) console.log(c.par, c.compra, c.venda);import os, sys, requests
resposta = requests.get(
"https://dev-api.primux.cloud/v1/cotacoes?pares=USD-BRL,EUR-BRL,BTC-USD",
headers={"Authorization": f"Bearer {os.environ['PRIMUX_COTACOES_CHAVE']}"},
timeout=15,
)
dados = resposta.json()
if resposta.status_code != 200:
# dados["erro"] e dados["mensagem"]: veja a seção Erros
sys.exit(f"Erro {resposta.status_code}: {dados.get('mensagem')}")
if dados["desatualizado"]:
pass # a fonte estava fora do ar: este é o último dado salvo (veja atualizado_em)
for c in dados["cotacoes"]:
print(c["par"], c["compra"], c["venda"])Chave de API
Cada sessão contratada tem a sua própria chave. A chave identifica o plano, conta as consultas e vale só para esta API.
- A chave aparece uma única vez, na hora de gerar. Se perder, gere outra: a anterior deixa de funcionar na hora.
- Use a chave só no seu servidor (back-end). Nunca a coloque em aplicativo, página ou código que o público consiga ler.
- Uma chave não abre outra API: a chave do clima não consulta cotações nem loterias (erro chave_de_outra_api).
Abrir o console e gerar a chave
export PRIMUX_COTACOES_CHAVE="COLE_AQUI_A_SUA_CHAVE"Autenticação
Envie a chave em todas as requisições, no cabeçalho Authorization, no formato Bearer. Não há parâmetro de URL para a chave.
Authorization: Bearer 0123456789abcdefghijklmnopqrstuvwxyz0123456789Referência da API
Cotações
GET/v1/cotacoes
Devolve a cotação atual de um ou mais pares de moedas (até 10 por consulta). Você escolhe os pares: moedas comuns (USD-BRL, EUR-BRL) e criptomoedas (BTC-USD). A lista é devolvida em ordem alfabética de par.
Parâmetros da URL
parestexto obrigatório- Pares no formato ORIGEM-DESTINO separados por vírgula, de 1 a 10. Aceita também a barra (USD/BRL). Exemplo: USD-BRL,EUR-BRL,BTC-USD.
curl "https://dev-api.primux.cloud/v1/cotacoes?pares=USD-BRL,EUR-BRL,BTC-USD" \
-H "Authorization: Bearer SUA_CHAVE"<?php
$ch = curl_init('https://dev-api.primux.cloud/v1/cotacoes?pares=USD-BRL,EUR-BRL,BTC-USD');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('PRIMUX_COTACOES_CHAVE')],
]);
$dados = json_decode(curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);const resposta = await fetch('https://dev-api.primux.cloud/v1/cotacoes?pares=USD-BRL,EUR-BRL,BTC-USD', {
headers: { Authorization: `Bearer ${process.env.PRIMUX_COTACOES_CHAVE}` },
});
const dados = await resposta.json();import os, requests
resposta = requests.get(
"https://dev-api.primux.cloud/v1/cotacoes?pares=USD-BRL,EUR-BRL,BTC-USD",
headers={"Authorization": f"Bearer {os.environ['PRIMUX_COTACOES_CHAVE']}"},
timeout=15,
)
dados = resposta.json(){
"cotacoes": [
{
"par": "EUR-BRL",
"origem": "EUR",
"destino": "BRL",
"nome": "Euro/Real Brasileiro",
"compra": 6.4983,
"venda": 6.5003,
"maxima": 6.5309,
"minima": 6.4449,
"variacao": 0.0444,
"variacao_pct": 0.687958,
"cotado_em": "2026-11-19 18:16:46"
}
],
"atualizado_em": "2026-11-19T21:32:20Z",
"desatualizado": false
}Referência da API
Pares disponíveis
GET/v1/cotacoes/pares
Lista todos os pares de moedas que a fonte cota, com o nome de cada um. Use para montar telas de escolha ou conferir um par antes de consultar. A lista é renovada uma vez por dia.
curl "https://dev-api.primux.cloud/v1/cotacoes/pares" \
-H "Authorization: Bearer SUA_CHAVE"<?php
$ch = curl_init('https://dev-api.primux.cloud/v1/cotacoes/pares');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('PRIMUX_COTACOES_CHAVE')],
]);
$dados = json_decode(curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);const resposta = await fetch('https://dev-api.primux.cloud/v1/cotacoes/pares', {
headers: { Authorization: `Bearer ${process.env.PRIMUX_COTACOES_CHAVE}` },
});
const dados = await resposta.json();import os, requests
resposta = requests.get(
"https://dev-api.primux.cloud/v1/cotacoes/pares",
headers={"Authorization": f"Bearer {os.environ['PRIMUX_COTACOES_CHAVE']}"},
timeout=15,
)
dados = resposta.json(){
"pares": [
{ "par": "BTC-BRL", "nome": "Bitcoin/Real Brasileiro" },
{ "par": "EUR-BRL", "nome": "Euro/Real Brasileiro" },
{ "par": "USD-BRL", "nome": "Dólar Americano/Real Brasileiro" }
],
"atualizado_em": "2026-11-19T00:05:11Z",
"desatualizado": false
}Referência da API
Sessão e plano
GET/v1/cotacoes/sessao
Mostra o nome da sessão, o plano, o estado, a validade e os limites do plano. Não conta como consulta nos limites de uso do plano, mas passa pela mesma autenticação.
curl "https://dev-api.primux.cloud/v1/cotacoes/sessao" \
-H "Authorization: Bearer SUA_CHAVE"<?php
$ch = curl_init('https://dev-api.primux.cloud/v1/cotacoes/sessao');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('PRIMUX_COTACOES_CHAVE')],
]);
$dados = json_decode(curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);const resposta = await fetch('https://dev-api.primux.cloud/v1/cotacoes/sessao', {
headers: { Authorization: `Bearer ${process.env.PRIMUX_COTACOES_CHAVE}` },
});
const dados = await resposta.json();import os, requests
resposta = requests.get(
"https://dev-api.primux.cloud/v1/cotacoes/sessao",
headers={"Authorization": f"Bearer {os.environ['PRIMUX_COTACOES_CHAVE']}"},
timeout=15,
)
dados = resposta.json(){
"nome": "Meu site",
"plano": "Cotações 5.000",
"estado": "criada",
"valido_ate": "2026-12-19T14:30:00Z",
"limite_diario": 5000,
"limite_por_minuto": 60
}Referência da API
Uso
GET/v1/cotacoes/uso
Mostra quantas consultas a sessão fez hoje e no mês e, se o plano tem limite diário, quantas ainda restam hoje. O contador do dia zera à meia-noite.
curl "https://dev-api.primux.cloud/v1/cotacoes/uso" \
-H "Authorization: Bearer SUA_CHAVE"<?php
$ch = curl_init('https://dev-api.primux.cloud/v1/cotacoes/uso');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('PRIMUX_COTACOES_CHAVE')],
]);
$dados = json_decode(curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);const resposta = await fetch('https://dev-api.primux.cloud/v1/cotacoes/uso', {
headers: { Authorization: `Bearer ${process.env.PRIMUX_COTACOES_CHAVE}` },
});
const dados = await resposta.json();import os, requests
resposta = requests.get(
"https://dev-api.primux.cloud/v1/cotacoes/uso",
headers={"Authorization": f"Bearer {os.environ['PRIMUX_COTACOES_CHAVE']}"},
timeout=15,
)
dados = resposta.json(){
"data": "2026-11-19",
"consultas_hoje": 128,
"consultas_no_mes": 2410,
"limite_diario": 5000,
"restante_hoje": 4872
}Campos da resposta
Todos os campos da resposta de sucesso. Campos marcados como "pode faltar" aparecem só quando a fonte informa o valor.
cotacoes[].partexto- Par consultado, no formato ORIGEM-DESTINO.
cotacoes[].origemtexto- Moeda de origem (a que está sendo cotada).
cotacoes[].destinotexto- Moeda de destino (a que expressa o valor).
cotacoes[].nometexto- Nome do par em português.
cotacoes[].compranúmero- Valor de compra: quanto o mercado paga pela moeda de origem, em unidades da moeda de destino.
cotacoes[].vendanúmero- Valor de venda: quanto o mercado cobra pela moeda de origem, em unidades da moeda de destino.
cotacoes[].maximanúmero- Maior valor do dia.
cotacoes[].minimanúmero- Menor valor do dia.
cotacoes[].variacaonúmero- Variação do valor de compra em relação ao fechamento anterior.
cotacoes[].variacao_pctnúmero- Variação em porcentagem.
cotacoes[].cotado_emtexto- Data e hora da cotação na fonte.
atualizado_emtexto- Quando o dado foi obtido da fonte (UTC).
desatualizadobooleano- true quando a fonte falhou na renovação e este é o último dado salvo.
Atualização dos dados
O painel não consulta a fonte a cada chamada sua. Cada item (cidade, conjunto de pares ou concurso mais recente) é renovado no máximo a cada 30 minutos e guardado; as chamadas seguintes recebem o dado salvo.
- atualizado_em diz quando o dado foi obtido da fonte (horário UTC).
- Se a fonte estiver fora do ar na hora de renovar, você recebe o último dado salvo e desatualizado vem como true.
- Se a fonte estiver fora e nunca houve dado salvo para o item, a resposta é 503 fonte_indisponivel.
{
…
"atualizado_em": "2026-11-19T21:02:11Z",
"desatualizado": true
}Erros
Todo erro devolve um JSON com erro (código estável, para você testar no código) e mensagem (texto em português). Teste o código, não o texto.
| Status | Código | Quando acontece |
|---|---|---|
| 400 | par_invalido | Algum par não segue o formato ORIGEM-DESTINO (por exemplo USD-BRL). |
| 400 | par_ausente | Nenhum par informado no parâmetro pares. |
| 400 | pares_demais | Mais de 10 pares em uma consulta. |
| 404 | par_inexistente | A fonte não cota algum dos pares. Veja a lista em /v1/cotacoes/pares. |
| 401 | chave_invalida | Chave ausente, errada ou de formato inválido. |
| 403 | chave_de_outra_api | A chave é de outra API (por exemplo, a do clima usada nas cotações). |
| 403 | sessao_suspensa | A sessão está suspensa por falta de pagamento. Renove para voltar a usar. |
| 403 | sessao_cancelada | A sessão foi cancelada. |
| 404 | rota_inexistente | A rota não existe. Confira o caminho nesta documentação. |
| 429 | limite_por_minuto | O limite de consultas por minuto do plano foi atingido. Espere alguns segundos. |
| 429 | limite_diario | O limite de consultas do dia foi atingido. O contador zera à meia-noite. |
| 429 | muitas_requisicoes | Muitas requisições do mesmo endereço IP em pouco tempo. |
| 429 | muitas_tentativas | Muitas tentativas com chave inválida deste endereço. Espere um minuto. |
| 503 | servico_indisponivel | O serviço não respondeu agora. Tente de novo em instantes. |
| 503 | fonte_indisponivel | A fonte dos dados está fora do ar e ainda não há dado salvo para este item. |
{
"erro": "limite_diario",
"mensagem": "Limite diário de envios do plano atingido. O contador zera à meia-noite."
}Limites e boas práticas
- Cada consulta bem-sucedida conta uma unidade no limite do plano (por minuto e por dia). Consultas recusadas por chave inválida não contam.
- O limite por minuto usa uma janela deslizante; o limite diário zera à meia-noite (horário de Brasília).
- Passou do limite: a resposta é 429 com limite_por_minuto ou limite_diario. Nada é cobrado a mais.
- Veja o uso do dia e do mês em /uso e os limites do seu plano em /sessao.
Boas práticas
- Guarde o resultado no seu sistema pelo mesmo tempo que a API guarda (até 30 minutos): você gasta menos consultas e responde mais rápido.
- Defina um tempo máximo (timeout) de 10 a 15 segundos nas chamadas.
- Trate 429 e 503 esperando e tentando de novo, sem repetir em laço apertado.
- Confira desatualizado: se for true, mostre o dado mesmo assim e, se for importante, avise o usuário da hora em atualizado_em.
Tentar de novo com segurança
Para 429 e 503, espere e tente de novo com intervalo crescente (1, 2, 4, 8 segundos) e desista depois de poucas tentativas.
import os, time, requests
def consultar(url, tentativas=4):
for n in range(tentativas):
r = requests.get(url, headers={"Authorization": f"Bearer {os.environ['PRIMUX_COTACOES_CHAVE']}"}, timeout=15)
if r.status_code not in (429, 503):
return r
time.sleep(2 ** n) # 1 s, 2 s, 4 s, 8 s
return r
resposta = consultar("https://dev-api.primux.cloud/v1/cotacoes?pares=USD-BRL,EUR-BRL,BTC-USD")Perguntas frequentes
Quais moedas posso consultar?
As que a fonte cota: consulte /v1/cotacoes/pares para ver a lista completa de pares, incluindo criptomoedas como BTC-USD.
Qual é a diferença entre compra e venda?
Compra é o valor que o mercado paga pela moeda de origem; venda é o valor que ele cobra. Para mostrar um preço ao público, a venda costuma ser a referência.
Posso pedir o par ao contrário (BRL-USD)?
Só se a fonte cotar esse par. Se não existir, a resposta é 404 par_inexistente; nesse caso, calcule 1 dividido pelo valor do par USD-BRL.
Com que frequência a cotação muda?
O painel renova cada conjunto de pares no máximo a cada 30 minutos. O horário da cotação na fonte está em cotado_em.