API de preço da prata: cotações XAG ao vivo e históricas em JSON

O que uma API de preço da prata oferece

Uma API de preço da prata retorna o preço atual e o histórico da prata como dados estruturados, geralmente JSON via HTTPS, para que uma loja, um app ou um relatório possa usá-los sem copiar números de um site. Na MetalAPI, a prata tem o símbolo XAG, o código ISO 4217 para uma onça troy de prata. O seu valor ao vivo é o preço à vista (spot): o ponto médio entre as cotações de compra (bid) e de venda (ask) do mercado de atacado.

A prata divide a API com o ouro, mas tem hábitos próprios. Ela é cotada por onça troy, mas comprada e vendida em gramas e quilos, o seu preço por grama é pequeno o suficiente para que o arredondamento faça diferença, e quem compra prataria e sucata pensa em teor de pureza, não em quilates. Este guia cobre as requisições e os detalhes específicos da prata:

• O preço da prata ao vivo em uma requisição, e como lê-lo.
• Preços da prata por onça, grama e quilo.
• A prata em outras moedas, ainda com uma única requisição.
• Preços históricos da prata desde 2000.
• Casos de uso: lojas de metais preciosos, compradores de prataria e sucata, e apps de investimento.

Como obter o preço da prata ao vivo via API

Crie uma conta grátis e adicione uma chave de API no painel. As chaves começam com mk_live_. Guarde a sua em uma variável de ambiente e envie-a em um cabeçalho; depois, solicite /latest com XAG:

export METALAPI_KEY="mk_live_your_key_here"

curl "https://metalapi.com/api/v1/latest?base=USD&currencies=XAG" \
  -H "X-API-Key: $METALAPI_KEY"

A resposta tem esta aparência. Os números são os valores de exemplo usados em toda a documentação da MetalAPI, não preços ao vivo:

{
  "success": true,
  "timestamp": 1792713600,
  "date": "2026-10-23",
  "base": "USD",
  "rates": {
    "XAG": 0.01853911754,
    "USDXAG": 53.94
  }
}

USDXAG é o preço de uma onça troy de prata na moeda base, 53,94 dólares americanos neste exemplo. XAG é o inverso, onças troy de prata por dólar, mantido por compatibilidade com APIs no estilo forex. Leia sempre a chave com prefixo: tratar rates.XAG como o preço exibiria 0,0185 em vez de 53,94.

timestamp é o horário dos dados, e não da sua requisição. A prata à vista é negociada 24 horas por dia nos dias úteis e pausa de sexta-feira às 17:00 até domingo às 17:00, horário de Nova York, então no fim de semana a API continua retornando o preço de fechamento de sexta-feira. Exiba o timestamp ao lado do preço, principalmente aos sábados e domingos.

Se você também precisa de ouro, platina ou paládio, adicione-os à mesma requisição: currencies=XAU,XAG,XPT,XPD. Uma requisição conta uma vez só, não importa quantos símbolos ela retorne.

Preço da prata por onça, grama e quilo

Os preços da prata são por onça troy, 31,1034768 gramas, a menos que você passe unit. Os valores aceitos são troy_oz (o padrão), gram, kilogram, ounce, pound, metric_ton e short_ton, e a resposta acrescenta um campo unit de nível superior sempre que a unidade não for a padrão:

curl "https://metalapi.com/api/v1/latest?currencies=XAG&unit=kilogram" \
  -H "X-API-Key: $METALAPI_KEY"

Ao preço de exemplo de 53,94 dólares por onça troy, a prata custa:

Vale a pena adotar dois hábitos com a prata. Primeiro, exiba mais casas decimais por grama: a 1,7342 dólar, duas casas escondem a maior parte da oscilação diária, por isso quatro são comuns. Segundo, se você exibe várias unidades, solicite onças troy uma vez e converta localmente, em vez de fazer uma requisição por unidade. Os fatores são exatos:

const GRAMS_PER_TROY_OZ = 31.1034768;

const res = await fetch("https://metalapi.com/api/v1/latest?currencies=XAG", {
  headers: { "X-API-Key": process.env.METALAPI_KEY },
  signal: AbortSignal.timeout(10_000),
});
const data = await res.json();
if (!data.success) throw new Error(`MetalAPI ${data.error.code} (${data.error.type}): ${data.error.info}`);

const perOz = data.rates[`${data.base}XAG`]; // 53.94 no exemplo da documentação
const perGram = perOz / GRAMS_PER_TROY_OZ; // 1.7342...
const perKg = perGram * 1000; // 1734.21...

console.log({ perOz, perGram: perGram.toFixed(4), perKg: perKg.toFixed(2) });

Onças troy, gramas e quilogramas lista todos os fatores, incluindo o pennyweight, e as regras de arredondamento para faturas.

Preços da prata em outras moedas

Defina base para precificar a prata em outra moeda: base=EUR retorna EURXAG, base=INR retorna INRXAG. Combinada com unit, esta requisição retorna euros por grama:

curl "https://metalapi.com/api/v1/latest?base=EUR&currencies=XAG&unit=gram" \
  -H "X-API-Key: $METALAPI_KEY"

{
  "success": true,
  "timestamp": 1792765800,
  "date": "2026-10-23",
  "base": "EUR",
  "unit": "gram",
  "rates": {
    "XAG": 0.6713138244,
    "EURXAG": 1.489616277
  }
}

Para exibir a prata em várias moedas, uma requisição continua bastando. Peça a prata e as moedas com base USD e depois divida: a prata em euros é USDXAG ÷ USDEUR, porque USDEUR é o preço de um euro em dólares. Todos os valores vêm do mesmo snapshot, então o resultado bate com o que base=EUR retorna. Com a taxa de exemplo da documentação, de 1,1642 dólar por euro, 53,94 ÷ 1,1642 dá 46,33 euros por onça troy, ou 1,4896 euro por grama, o mesmo valor acima:

import os

import requests

GRAMS_PER_TROY_OZ = 31.1034768
CURRENCIES = ["EUR", "GBP", "INR", "TRY"]

resp = requests.get(
    "https://metalapi.com/api/v1/latest",
    params={"base": "USD", "currencies": ",".join(["XAG", *CURRENCIES])},
    headers={"X-API-Key": os.environ["METALAPI_KEY"]},
    timeout=10,
)
data = resp.json()
if not data["success"]:
    err = data["error"]
    raise RuntimeError(f"MetalAPI {err['code']} ({err['type']}): {err['info']}")

rates = data["rates"]
silver_usd = rates["USDXAG"]
for cur in ["USD", *CURRENCIES]:
    per_oz = silver_usd if cur == "USD" else silver_usd / rates["USD" + cur]
    print(f"{cur}: {per_oz:,.2f} per troy oz, {per_oz / GRAMS_PER_TROY_OZ:,.4f} per gram")

Qualquer uma das 57 moedas aceitas funciona assim, assim como ouro, platina e paládio, então uma única chamada pode alimentar um painel de preços inteiro. Na Índia, onde a prata costuma ser cotada por quilo, base=INR&unit=kilogram dá diretamente o número familiar.

Preços históricos da prata via API

O histórico da prata começa em 2000 e usa os mesmos parâmetros e o mesmo formato de resposta do preço ao vivo. Os valores de cada dia são os preços de fechamento daquele dia, com datas em UTC. Quatro endpoints cobrem a maioria das necessidades:

• /YYYY-MM-DD, /historical?date= ou /yesterday: o fechamento de um dia. Para um fim de semana ou feriado, é retornado o fechamento do dia de negociação mais recente.
• /timeframe: fechamentos diários entre start_date e end_date, até 30 dias por requisição no Free e 365 dias nos planos pagos.
• /change: preço inicial, preço final e variação absoluta e percentual entre duas datas.
• /ohlc: abertura, máxima, mínima e fechamento de um dia.

# Prata no fechamento de 15 de janeiro de 2024 (USDXAG 23.162 no exemplo da documentação)
curl "https://metalapi.com/api/v1/2024-01-15?currencies=XAG" \
  -H "X-API-Key: $METALAPI_KEY"

# Fechamentos diários da prata em euros por grama em setembro de 2026
curl "https://metalapi.com/api/v1/timeframe?start_date=2026-09-01&end_date=2026-09-30&base=EUR&currencies=XAG&unit=gram" \
  -H "X-API-Key: $METALAPI_KEY"

# Quanto valiam 500 gramas de prata em euros no fechamento de 1º de outubro de 2026
curl "https://metalapi.com/api/v1/convert?from=XAG&to=EUR&amount=500&unit=gram&date=2026-10-01" \
  -H "X-API-Key: $METALAPI_KEY"

Os preços de fechamento de dias passados nunca mudam, então armazene-os em vez de solicitá-los de novo. Com o limite de 365 dias de um plano pago, um backfill completo desde 2000 custa uma requisição a /timeframe por ano. Lembre-se de que os preços dos metais anteriores a outubro de 2026 são derivados de contratos futuros de primeiro vencimento, então podem diferir ligeiramente do preço spot do mesmo dia.

Preços históricos de ouro e prata via API traz um script de backfill completo, dicas de armazenamento e validação, e um gráfico do ouro junto com a relação ouro/prata.

Casos de uso de uma API de preço da prata

Lojas de metais preciosos e revendedores de moedas. Os revendedores vendem acima do spot e recompram abaixo dele. Um preço de venda típico é o preço spot por onça troy vezes o conteúdo de prata fina, mais um prêmio do produto, mais uma taxa fixa por item. Guarde o prêmio por produto, atualize o spot no intervalo de atualização do seu plano e mostre aos clientes quando o preço foi atualizado pela última vez. A partir do plano Standard, adicione XAG-BID e XAG-ASK a currencies para cotar os dois lados com o próprio spread do mercado. Spot, bid e ask explicados mostra como os revendedores transformam esses números em cotações de compra e venda.

Compradores de prataria, joias e sucata. Objetos de prata são precificados pelo peso e pelo teor, a proporção de prata pura em milésimos. Os teores comuns são 999 (prata fina), 958 (Britannia), 925 (prata de lei, ou sterling) e 800, encontrado em prataria antiga da Europa continental. O valor de fundição é o peso em gramas × o teor × o preço por grama. Ao preço de exemplo de 1,7342 dólar por grama, uma bandeja de prata 925 de 500 gramas contém 462,5 gramas de prata, que valem cerca de 802,07 dólares. Compradores de sucata pagam uma porcentagem do valor de fundição, então faça dessa porcentagem uma configuração, e não uma constante.

O endpoint de quilates da MetalAPI, /carat, cobre apenas o ouro, então o teor da prata é um cálculo do seu lado:

const GRAMS_PER_TROY_OZ = 31.1034768;

/** Valor de fundição de um item de prata: peso em gramas × teor (ex.: 0.925) × preço por grama. */
export function meltValue(grams, fineness, pricePerTroyOz) {
  return grams * fineness * (pricePerTroyOz / GRAMS_PER_TROY_OZ);
}

meltValue(500, 0.925, 53.94); // 802.07…  bandeja de prata 925 ao preço de exemplo
meltValue(1000, 0.999, 53.94); // 1732.48… barra de um quilo de prata 999

Apps de investimento e de carteira. Os usuários têm moedas, medalhas e barras de um quilo e querem saber quanto valem na sua própria moeda. Armazene as posições internamente em onças troy, converta a unidade de entrada uma vez e avalie a carteira com a moeda do usuário como base. /change retorna a variação percentual entre duas datas para linhas como “prata neste mês”, e os fechamentos diários armazenados a partir de /timeframe alimentam os gráficos.

Alertas de preço. Se você só precisa reagir quando a prata cruzar um nível, os alertas de preço podem monitorar XAG em qualquer moeda e avisar você por e-mail a partir do plano Lite, ou por webhook assinado a partir do plano Advanced, sem polling do seu lado.

Atualização, cotas e planos

Quão recente é o preço da prata depende do plano. Fazer polling mais rápido que o intervalo de atualização do seu plano só retorna os mesmos números de novo:

• Faça cache por, no mínimo, o seu intervalo de atualização. No Free, uma requisição por dia basta para os preços atuais.
• Peça todos os metais em uma só chamada. currencies=XAU,XAG,XPT,XPD custa uma requisição; quatro chamadas separadas custam quatro.
• Mantenha a chave no servidor. Sirva preços em cache para as suas páginas em vez de chamar a API a partir do navegador de cada visitante.
• Consulte o uso de graça. /usage e /symbols nunca contam para a cota, e toda resposta traz um bloco rate_limit.

Pronto para começar? Crie uma conta grátis para obter uma chave de API em um minuto, sem precisar de cartão de crédito. Compare intervalos de atualização e cotas na página de preços e use a documentação da API como referência para todos os endpoints e parâmetros.

Perguntas frequentes

Qual é o símbolo da prata em uma API de preços?

XAG, o código ISO 4217 para uma onça troy de prata. Na MetalAPI, o preço da prata na sua moeda base é a chave que une os dois códigos, como USDXAG para dólares por onça ou EURXAG para euros por onça.

Existe uma API de preço da prata gratuita?

Sim. O plano Free da MetalAPI inclui a prata, todos os outros símbolos e o histórico completo, com 100 requisições por mês e atualização diária dos preços, e não exige cartão de crédito. Os planos pagos começam em US$ 4,99 por mês, com atualização a cada 30 minutos e 1.000 requisições.

Como obtenho o preço da prata por grama?

Passe unit=gram ou divida o preço por onça troy por 31,1034768. Não divida por 28,35: essa é a onça avoirdupois, e ela superestima o preço por grama em cerca de 9,7%.

Até quando vão os preços históricos da prata?

Os preços diários da prata estão disponíveis desde 2000 em todos os planos. Uma única requisição de período cobre até 30 dias no Free e até 365 dias nos planos pagos.

Por que o preço da prata de um revendedor é diferente do preço da API?

A API retorna o preço médio à vista do mercado de atacado. Os revendedores acrescentam prêmios de cunhagem, distribuição e sua margem ao vender, e pagam menos que o spot ao recomprar, por isso os preços de varejo de moedas e barras ficam acima do spot e os de recompra, abaixo dele.