# Métricas on-chain diárias para ações tokenizadas com a Data API > Source: https://docs.blockvectra.com/pt-br/guides/stocks/ > Os dados são derivados de registros públicos on-chain e destinam-se apenas a fins informativos. Não constituem aconselhamento de investimento. Para deploy de contratos e escuta de eventos na Robinhood Chain, siga o [guia de RPC e WebSocket](https://docs.blockvectra.com/en/guides/robinhood-chain/). ## Tarefa em três passos: consultar a atividade de ações na Robinhood Chain Encontre as ações tokenizadas mais ativas no dia UTC registrado mais recente e, em seguida, leia a quantidade de transferências e o número de detentores. Use uma API key para consultar a atividade de tokens de ações e detentores na mainnet para um painel de atividade. Trata-se de métricas de atividade on-chain, não cotações de ações. ### 1. Ler o bloco mais recente sem uma API key ```bash curl -sS "https://api.blockvectra.com/v1/robinhood_mainnet/public" \ -H 'Content-Type: application/json' \ -d '{"jsonrpc":"2.0","id":1,"method":"eth_blockNumber","params":[]}' ``` O `result` do JSON-RPC é o número do bloco mais recente em hexadecimal. Esta chamada de RPC público não exige chave; a consulta à Data API no passo 3 exige uma chave. ### 2. Criar uma chave para a mesma rede [Entre no console e abra API Keys](https://console.blockvectra.com/login/?next=%2Fkeys%2F\&ref=docs-stocks-task). Crie uma chave e salve o segredo exibido na caixa de diálogo. A mesma chave funciona para JSON-RPC e Data API em `robinhood_mainnet`. Para um agente de IA usando HTTP sem navegador, siga o [guia de cadastro programático](https://docs.blockvectra.com/en/guides/programmatic-signup/?ref=docs-stocks-task) para se cadastrar com uma assinatura de carteira Ethereum e criar uma chave; não peça ao usuário para colar a chave no chat. ### 3. Consultar a atividade de ações com sua chave Substitua `replace-with-your-key` abaixo pela sua chave salva e execute o comando no seu servidor ou em um terminal local. Omitir `day` seleciona o dia registrado mais recente; `limit=5` retorna até cinco ações ordenadas pela atividade de transferências em ordem decrescente. ```bash export BLOCKVECTRA_API_KEY='replace-with-your-key' curl -sS "https://api.blockvectra.com/v1/data/robinhood_mainnet/stocks?limit=5" \ -H "x-api-key: $BLOCKVECTRA_API_KEY" ``` Leia estes campos na resposta: | Campo | Significado | | --------------------- | ---------------------------------------------------------------------------------------- | | `data[].day` | Data UTC das métricas diárias. | | `data[].token` | Endereço do contrato do token de ação retornado pela consulta. | | `data[].symbol` | Símbolo do token. | | `data[].transfers` | Número de transferências on-chain naquele dia. | | `data[].holder_count` | Quantidade total de endereços detentores. | | `meta.as_of_block` | Bloco indexado atual, e não a altura do bloco do snapshot de métricas diárias. | | `meta.refreshed_at` | Horário de atualização do snapshot; considere os dados desatualizados quando for `null`. | Um array `data` vazio significa que não há registros de atividade disponíveis. Para inspecionar uma ação do resultado, use o valor de `token` com `GET /robinhood_mainnet/stocks/{token}` conforme descrito abaixo. ## O que é o conjunto de dados de ações tokenizadas A BlockVectra Data API fornece métricas diárias on-chain e metadados para ações tokenizadas. Esse conjunto de dados consolida transferências diárias, emissões (mints), queimas (burns), variações líquidas de fornecimento, distribuições de detentores e métricas de negociação em exchanges descentralizadas (DEX), permitindo que desenvolvedores acompanhem a atividade pública de ações tokenizadas. Para consultar as redes que oferecem esse conjunto de dados, consulte a página [Redes suportadas](https://docs.blockvectra.com/en/chains/). * **URL base**: `https://api.blockvectra.com/v1/data` — exceto por `GET /chains`, todas as rotas da Data API são prefixadas com um identificador de rede (por exemplo, `https://api.blockvectra.com/v1/data/{chain}/…`) * **Rede de exemplo**: `robinhood_mainnet` (usada como exemplo de parâmetro de caminho; verifique [Redes suportadas](https://docs.blockvectra.com/en/chains/) para ver todas as redes que oferecem esse conjunto de dados) * **Autenticação**: Forneça sua API key no cabeçalho de requisição `x-api-key: $BLOCKVECTRA_API_KEY` * **Cobrança e cobertura**: Tarifado em Unidades de Computação (CU); apenas respostas 2xx bem-sucedidas são cobradas. Se uma rede não tiver cobertura de ações, o endpoint retorna HTTP `422 no_coverage` (não tarifado) ## Classificação diária (`GET /{chain}/stocks`) O endpoint `GET /{chain}/stocks` retorna uma classificação diária de atividade de ações tokenizadas para uma data UTC especificada, incluindo metadados de exibição (símbolo, nome, etc.), ordenada pela atividade de transferências em ordem decrescente (tokens mais ativos primeiro). ### Parâmetros de requisição * `{chain}` (parâmetro de caminho, obrigatório): Identificador da rede (por exemplo, `robinhood_mainnet`). * `day` (parâmetro de consulta, opcional): Data do calendário UTC no formato `YYYY-MM-DD`. Quando omitido, adota por padrão o dia registrado mais recente (se nenhuma atividade for registrada, retorna `200` com `data: []`). Se fornecido, mas não for uma data de calendário válida em `YYYY-MM-DD`, retorna HTTP `400` (`error.code = "bad_request"`). * `limit` (parâmetro de consulta, opcional): Limita a quantidade de registros retornados. O padrão é 50; valores acima de 500 são limitados a 500; passar `0` ou um valor não inteiro retorna HTTP `400` (`error.code = "bad_request"`). ### Comportamento de paginação Este endpoint **não é paginado**. O parâmetro `limit` define o número máximo de registros retornados. No envelope delimitador `StockDailyListEnvelope` (`data` e `meta`), os endpoints de ações não retornam `next_cursor` (a chave fica completamente ausente, nunca `null`). ### Exemplos de código Modelo inicial completo na Robinhood Chain: [blockvectra/robinhood-stock-tokens](https://github.com/blockvectra/robinhood-stock-tokens) **cURL** ```bash curl -s "https://api.blockvectra.com/v1/data/robinhood_mainnet/stocks?day=2026-09-29&limit=10" \ -H "x-api-key: $BLOCKVECTRA_API_KEY" ``` **TypeScript** ```ts const res = await fetch( "https://api.blockvectra.com/v1/data/robinhood_mainnet/stocks?day=2026-09-29&limit=10", { headers: { "x-api-key": process.env.BLOCKVECTRA_API_KEY! }, }, ); const body = await res.json(); console.log(body); ``` **Python** ```python import os import requests res = requests.get( "https://api.blockvectra.com/v1/data/robinhood_mainnet/stocks?day=2026-09-29&limit=10", headers={"x-api-key": os.environ["BLOCKVECTRA_API_KEY"]}, ) print(res.json()) ``` ### Estrutura de resposta O envelope de resposta é `StockDailyListEnvelope`, contendo `data` e `meta`: * `data` (array): Uma lista de registros de classificação diária (`StockDaily`), ordenada pela atividade de transferências em ordem decrescente (tokens mais ativos primeiro). Cada item inclui identificadores do token (`token`, `symbol`, `name`), atividade de transferências (`transfers`, `unique_senders`, `unique_receivers`), métricas de fornecimento (`mint_raw_amount`, `burn_raw_amount`, `net_supply_change`), métricas de distribuição (`holder_count`, `top10_holder_share_bps`), métricas de negociação em DEX (`dex_swap_count`, `dex_raw_volume`) e timestamp de atualização (`refreshed_at`). * `meta` (objeto): Metadados da rede (`chain`, `chain_slug`, `chain_external_id`, `as_of_block`, `safe_block`, `finalized_block`, `coverage`, `refreshed_at`). `meta.refreshed_at` pode ser `null`: `null` indica que o horário de atualização desses dados é desconhecido e eles devem ser tratados como desatualizados; endpoints baseados em blocos sempre retornam um valor. ## Consultar uma ação tokenizada (`GET /{chain}/stocks/{token}`) O endpoint `GET /{chain}/stocks/{token}` obtém metadados e até 30 dias de métricas diárias recentes para uma ação tokenizada específica a partir de seu endereço de token. ### Parâmetros de requisição * `{chain}` (parâmetro de caminho, obrigatório): Identificador da rede (por exemplo, `robinhood_mainnet`). * `{token}` (parâmetro de caminho, obrigatório): Endereço de contrato de token de 20 bytes; o prefixo `0x` é opcional e qualquer capitalização é aceita (os endereços retornados são normalizados para `0x` seguido por 40 dígitos hexadecimais em minúsculas). Um formato de endereço inválido retorna HTTP `400` (`error.code = "bad_request"`). * Se `{token}` não for uma ação tokenizada conhecida, retorna HTTP `404` (`error.code = "not_found"`). Se `{chain}` for uma rede desconhecida, retorna HTTP `404` (`error.code = "unknown_chain"`). ### Exemplos de código **cURL** ```bash curl -s "https://api.blockvectra.com/v1/data/robinhood_mainnet/stocks/0x1111111111111111111111111111111111111111" \ -H "x-api-key: $BLOCKVECTRA_API_KEY" ``` **TypeScript** ```ts const token = "0x1111111111111111111111111111111111111111"; const res = await fetch( `https://api.blockvectra.com/v1/data/robinhood_mainnet/stocks/${token}`, { headers: { "x-api-key": process.env.BLOCKVECTRA_API_KEY! }, }, ); const body = await res.json(); console.log(body); ``` **Python** ```python import os import requests token = "0x1111111111111111111111111111111111111111" res = requests.get( f"https://api.blockvectra.com/v1/data/robinhood_mainnet/stocks/{token}", headers={"x-api-key": os.environ["BLOCKVECTRA_API_KEY"]}, ) print(res.json()) ``` ### Estrutura de resposta O envelope de resposta é `StockTokenEnvelope`, contendo `data` e `meta`: * `data` (objeto): Um objeto `StockToken` contendo metadados do contrato do token (`address`, `symbol`, `name`, `decimals`, `created_block`, `created_tx_hash`, `factory`, `creator`, `mint_address`, `burn_address`, `refreshed_at`) e o array de métricas diárias recentes `daily`. * `daily` (array): Um array de métricas diárias recentes (`StockDailyMetric`), de até 30 dias, ordenado por data em ordem decrescente (mais recente primeiro). Cada item diário compartilha o mesmo esquema de métricas da classificação acima (sem os campos redundantes `token`, `symbol` e `name`). * `meta` (objeto): Objeto de metadados da rede consistente com a resposta da classificação. ## Principais campos de retorno explicados ### Campos de métricas diárias (StockDaily e StockDailyMetric) Tanto a classificação quanto os itens diários históricos de um único token incluem os seguintes campos principais: | Campo | Tipo | Descrição | | ------------------------ | -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | | `day` | `string` (date) | Data de agregação UTC formatada como `YYYY-MM-DD`. | | `token` | `string` (address) | Endereço do contrato do token (presente apenas em `StockDaily` da classificação), 40 caracteres hexadecimais em minúsculas com prefixo `0x`. | | `symbol` | `string` | Símbolo do token (por exemplo, `"EXMPL"`). | | `name` | `string` | Nome de exibição do token; string vazia `""` quando os metadados correspondentes de nome não estiverem disponíveis. | | `transfers` | `integer` (int64) | Número total de transferências on-chain neste dia UTC. | | `unique_senders` | `integer` (int64) | Quantidade de endereços remetentes únicos que iniciaram transferências neste dia. | | `unique_receivers` | `integer` (int64) | Quantidade de endereços destinatários únicos que receberam transferências neste dia. | | `mint_raw_amount` | `string` (decimal) | Quantidade bruta total do token emitida neste dia. | | `burn_raw_amount` | `string` (decimal) | Quantidade bruta total do token queimada neste dia. | | `net_supply_change` | `string` (decimal) | Variação líquida de fornecimento neste dia (string decimal com sinal, pode ser negativa). | | `holder_count` | `integer` (int64) | Quantidade total de endereços detentores. | | `top10_holder_share_bps` | `integer` | Participação dos 10 maiores detentores em pontos-base (0–10000, 1 bps = 0,01%). | | `dex_swap_count` | `integer` (int64) | Número de swaps em DEX envolvendo este token neste dia. | | `dex_raw_volume` | `string` (decimal) | Volume bruto total de negociação em DEX neste dia. | | `refreshed_at` | `string` (timestamp) | Timestamp UTC ISO-8601 de quando este registro diário foi atualizado pela última vez. | ### Campos de metadados de token (StockToken) Ao consultar um único token, o objeto externo `data` contém os metadados do contrato e as métricas diárias recentes: | Campo | Tipo | Descrição | | ----------------- | ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | | `address` | `string` (address) | Endereço do contrato do token. | | `symbol` | `string` | Símbolo do token. | | `name` | `string` | Nome completo do token. | | `decimals` | `integer` or `null` | Decimais do token (0–255), ou `null` se indisponível. | | `created_block` | `integer` (int64) | Número do bloco no qual o contrato do token foi criado. | | `created_tx_hash` | `string` (hash) | Hash da transação de criação do contrato, 64 caracteres hexadecimais em minúsculas com prefixo `0x`. | | `factory` | `string` (address) | Endereço do contrato factory. | | `creator` | `string` (address) or `null` | Endereço do criador, ou `null` se indisponível. | | `mint_address` | `string` (address) or `null` | Endereço de emissão (mint), ou `null` se indisponível. | | `burn_address` | `string` (address) or `null` | Endereço de queima (burn), ou `null` se indisponível. | | `daily` | `array` | Array de métricas diárias recentes (`StockDailyMetric`), de até 30 dias, ordenado por data em ordem decrescente (mais recente primeiro). | | `refreshed_at` | `string` (timestamp) | Timestamp UTC ISO-8601 de quando os metadados do token foram atualizados pela última vez. | ### Convenções de codificação A API adere a regras estritas de codificação em todos os endpoints para preservar a precisão numérica e a consistência: * **Money-safety**: Qualquer valor que possa exceder `2^53` (inteiros de 256 bits como `mint_raw_amount`, `burn_raw_amount`, `net_supply_change` e `dex_raw_volume`) é serializado como uma **string decimal**, nunca como um número JSON e nunca em notação científica ou hexadecimal. Isso evita a perda de precisão em ambientes de execução como o JavaScript. Em JavaScript/TypeScript, faça o parse com `BigInt(str)` (por exemplo, `const net = BigInt(body.data.daily[0].net_supply_change)`); em Python, faça o parse com `int(str)`. Contadores que se mantêm bem abaixo de `2^53` (`transfers`, `unique_senders`, `unique_receivers`, `holder_count`, `top10_holder_share_bps`, `dex_swap_count`, `created_block`) são números JSON convencionais. * **Valores binários e hexadecimais**: Endereços são representados por `0x` seguido de 40 caracteres hexadecimais em minúsculas; hashes são representados por `0x` seguido de 64 caracteres hexadecimais em minúsculas. Todos os valores hexadecimais retornados são estritamente em letras minúsculas. * **Timestamps e datas**: Timestamps como `refreshed_at` usam `YYYY-MM-DDTHH:MM:SSZ` (ISO-8601 UTC com precisão de segundos). Agregações diárias (`day`) usam datas de calendário simples (`YYYY-MM-DD`). ## Estimativa de uso (atualizando 50 tokens diariamente) As consultas à Data API consomem Unidades de Computação (CU) com base nos pesos dos métodos da plataforma. A estimativa abaixo avalia um cenário em que 50 tokens chamam `GET /{chain}/stocks/{token}` uma vez ao dia cada um, calculado com base nos pesos dos métodos ativos: - **Peso do método por chamada:** Cada chamada a `data.stock` consome 15 CU (preço de tabela $1.50 por 1M de chamadas). - **Atualização diária de 50 tokens** (uma chamada `GET /{chain}/stocks/{token}` por token, 50 chamadas/dia): o consumo diário é de 750 CU; ao longo de um ciclo de 30 dias, isso totaliza 1,500 chamadas consumindo 22,500 CU, cerca de <0.1% da cota gratuita (30,000,000 CU). Se exceder a franquia gratuita ou em um plano pago, o uso total a preço de tabela é de cerca de <$0.01/mês. ## Primeiros passos e upgrade A cota gratuita é ideal para desenvolvimento, testes e cargas de trabalho leves. Quando seu tráfego aumentar e exigir maior simultaneidade ou mais unidades de computação, recarregue on-chain na [página Billing do console](https://console.blockvectra.com/billing/); assim que a transação for confirmada on-chain e creditada, o limite de chamadas por segundo de toda a conta será removido. Cada chave continua sujeita aos limites de taxa e pico de CU, conforme descrito na [documentação de JSON-RPC](https://docs.blockvectra.com/en/api/json-rpc/#method-policy). Os Créditos Gratuitos não utilizados permanecem no seu saldo de Créditos e ainda podem ser usados. Para as tarifas e unidades de cobrança atuais, consulte a [página de preços](https://blockvectra.com/en/pricing/). ## Próximos passos * [Navegue pelo diretório de conjuntos de dados](https://blockvectra.com/en/data/) para ver todos os conjuntos de dados indexados pela BlockVectra. * [Veja o plano gratuito e os preços](https://blockvectra.com/en/pricing/#free) para verificar o que sua conta inclui. * [Entre no console](https://console.blockvectra.com/login/?next=%2Fkeys%2F) para criar uma API key.