# Щоденні ончейн-показники для токенізованих акцій за допомогою Data API

> Source: https://docs.blockvectra.com/uk/guides/stocks/

> Дані отримано з публічних ончейн-записів і надаються виключно в інформаційних цілях. Вони не є інвестиційною порадою.


Щодо розгортання контрактів та прослуховування подій у Robinhood Chain звертайтеся до [посібника з RPC та WebSocket](https://docs.blockvectra.com/en/guides/robinhood-chain/).

* **Перший крок:** [Прочитайте останній блок без API key](#1-read-the-latest-block-without-an-api-key) за допомогою команди curl нижче.
* **Критерій завершення:** автентифікований запит до stocks повертає `data` та `meta`; доступні записи містять `day`, `token`, `transfers` та `holder_count`, тоді як `data: []` означає відсутність доступних записів активності.

[Параметри основної мережі та набори даних](https://blockvectra.com/en/chains/robinhood_mainnet/).

<span id="stock-activity-task" />

## Завдання у три кроки: запит активності акцій у Robinhood Chain

Знайдіть найактивніші токенізовані акції за останній зафіксований день за UTC, а потім зчитайте кількість їхніх переказів та власників.

Використовуйте один API key для запиту активності та власників токенів акцій в основній мережі для створення панелі активності. Це показники ончейн-активності, а не біржові котирування акцій.

### 1. Прочитайте останній блок без 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":[]}'
```

Поле `result` відповіді JSON-RPC містить номер останнього блоку в шістнадцятковому форматі. Цей публічний виклик RPC не вимагає ключа; запит до Data API на кроці 3 потребує його.

### 2. Створіть ключ для тієї самої мережі

[Увійдіть до консолі та відкрийте API Keys](https://console.blockvectra.com/login/?next=%2Fkeys%2F\&ref=docs-stocks-task). Створіть ключ і збережіть secret, показаний у діалоговому вікні. Один і той самий ключ підходить для JSON-RPC і Data API на `robinhood_mainnet`.

Для AI-агента, який використовує HTTP без браузера, дотримуйтесь [посібника з програмної реєстрації](https://docs.blockvectra.com/en/guides/programmatic-signup/?ref=docs-stocks-task), щоб зареєструватися за допомогою підпису Ethereum-гаманця та створити ключ; не просіть користувача вставляти ключ у чат.

### 3. Запитайте активність акцій за допомогою вашого ключа

Замініть `replace-with-your-key` нижче на ваш збережений ключ, після чого виконайте команду на вашому сервері або в локальному терміналі. Пропуск `day` вибирає останній зафіксований день; `limit=5` повертає до п'яти акцій, відсортованих за спаданням активності переказів.

```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"
```

Зверніть увагу на такі поля у відповіді:

| Поле                  | Значення                                                                              |
| --------------------- | ------------------------------------------------------------------------------------- |
| `data[].day`          | Дата щоденних показників за UTC.                                                      |
| `data[].token`        | Адреса контракту токена акцій, повернута запитом.                                     |
| `data[].symbol`       | Символ токена.                                                                        |
| `data[].transfers`    | Кількість ончейн-переказів за цей день.                                               |
| `data[].holder_count` | Загальна кількість адрес власників.                                                   |
| `meta.as_of_block`    | Поточна проіндексована вершина ланцюга, а не висота блоку знімка щоденних показників. |
| `meta.refreshed_at`   | Час оновлення знімка; вважайте дані застарілими, якщо це значення дорівнює `null`.    |

Порожній масив `data` означає відсутність доступних записів активності. Щоб перевірити конкретну акцію з результату, використовуйте її значення `token` у запиті `GET /robinhood_mainnet/stocks/{token}`, як описано нижче.

## Що являє собою набір даних токенізованих акцій

BlockVectra Data API надає щоденні ончейн-показники та метадані для токенізованих акцій. Цей набір даних агрегує щоденні перекази, випуски (mints), спалювання (burns), чисті зміни пропозиції, розподіл власників та показники торгівлі на децентралізованих біржах (DEX), дозволяючи розробникам відстежувати публічну активність токенізованих акцій.

Список мереж, які пропонують цей набір даних, наведено на сторінці [Підтримувані мережі](https://docs.blockvectra.com/en/chains/).

* **Базовий URL**: `https://api.blockvectra.com/v1/data` — за винятком `GET /chains`, усі маршрути Data API мають префікс ідентифікатора мережі (наприклад, `https://api.blockvectra.com/v1/data/{chain}/…`)
* **Приклад мережі**: `robinhood_mainnet` (використовується як приклад параметра шляху; перевірте [Підтримувані мережі](https://docs.blockvectra.com/en/chains/) для всіх мереж, що надають цей набір даних)
* **Автентифікація**: передавайте ваш API key у заголовку запиту `x-api-key: $BLOCKVECTRA_API_KEY`
* **Білінг та покриття**: тарифікується в Compute Units (CU); тарифікуються лише успішні відповіді 2xx. Якщо в мережі відсутнє покриття акцій, ендпоінт повертає HTTP `422 no_coverage` (не тарифікується)

## Щоденна таблиця лідерів (`GET /{chain}/stocks`)

Ендпоінт `GET /{chain}/stocks` повертає щоденну таблицю лідерів активності токенізованих акцій за вказану дату UTC, включно з метаданими для відображення (символ, назва тощо), відсортовану за спаданням активності переказів (найактивніші токени першими).

### Параметри запиту

* `{chain}` (параметр шляху, обов'язковий): ідентифікатор мережі (наприклад, `robinhood_mainnet`).
* `day` (параметр запиту, необов'язковий): календарна дата за UTC у форматі `YYYY-MM-DD`. Якщо пропущено, за замовчуванням вибирається останній зафіксований день (якщо активність не зафіксована, повертає `200` із `data: []`). Якщо передано недійсну календарну дату `YYYY-MM-DD`, повертає HTTP `400` (`error.code = "bad_request"`).
* `limit` (параметр запиту, необов'язковий): обмежує кількість повернених записів. За замовчуванням — 50; значення понад 500 обмежуються до 500; передача `0` або нецілого числа повертає HTTP `400` (`error.code = "bad_request"`).

### Поведінка пагінації

Цей ендпоінт **не підтримує пагінацію**. Параметр `limit` обмежує максимальну кількість повернених записів. В охоплюючому об'єкті `StockDailyListEnvelope` (`data` та `meta`) ендпоінти акцій не повертають `next_cursor` (ключ взагалі відсутній, а не `null`).

### Приклади коду

Повний стартовий шаблон для 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())
```


### Структура відповіді

Обгорткою відповіді є `StockDailyListEnvelope`, що містить `data` та `meta`:

* `data` (масив): список записів щоденної таблиці лідерів (`StockDaily`), відсортований за спаданням активності переказів (найактивніші токени першими). Кожен елемент містить ідентифікатори токена (`token`, `symbol`, `name`), показники активності переказів (`transfers`, `unique_senders`, `unique_receivers`), показники пропозиції (`mint_raw_amount`, `burn_raw_amount`, `net_supply_change`), показники розподілу (`holder_count`, `top10_holder_share_bps`), показники торгівлі на DEX (`dex_swap_count`, `dex_raw_volume`) та часову мітку оновлення (`refreshed_at`).
* `meta` (об'єкт): метадані мережі (`chain`, `chain_slug`, `chain_external_id`, `as_of_block`, `safe_block`, `finalized_block`, `coverage`, `refreshed_at`). Поле `meta.refreshed_at` може бути `null`: `null` означає, що час оновлення цих даних невідомий і їх слід вважати застарілими; ендпоінти на основі блоків завжди повертають значення.

## Отримання однієї токенізованої акції (`GET /{chain}/stocks/{token}`)

Ендпоінт `GET /{chain}/stocks/{token}` повертає метадані та до 30 днів останніх щоденних показників для конкретної токенізованої акції за адресою її токена.

### Параметри запиту

* `{chain}` (параметр шляху, обов'язковий): ідентифікатор мережі (наприклад, `robinhood_mainnet`).
* `{token}` (параметр шляху, обов'язковий): 20-байтна адреса контракту токена; префікс `0x` необов'язковий, підтримується будь-який регістр (повернені адреси нормалізуються до `0x`, за яким слідують 40 малих шістнадцяткових цифр). Недійсний формат адреси повертає HTTP `400` (`error.code = "bad_request"`).
* Якщо `{token}` не є відомою токенізованою акцією, повертає HTTP `404` (`error.code = "not_found"`). Якщо `{chain}` є невідомою мережею, повертає HTTP `404` (`error.code = "unknown_chain"`).

### Приклади коду

**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())
```


### Структура відповіді

Обгорткою відповіді є `StockTokenEnvelope`, що містить `data` та `meta`:

* `data` (об'єкт): об'єкт `StockToken`, що містить метадані контракту токена (`address`, `symbol`, `name`, `decimals`, `created_block`, `created_tx_hash`, `factory`, `creator`, `mint_address`, `burn_address`, `refreshed_at`) та масив нещодавніх щоденних показників `daily`.
  * `daily` (масив): масив нещодавніх щоденних показників (`StockDailyMetric`), до 30 днів, відсортований за датою у спадному порядку (найновіші першими). Кожен щоденний елемент має ту саму схему показників, що й наведена вище таблиця лідерів (без надлишкових полів `token`, `symbol` та `name`).
* `meta` (об'єкт): об'єкт метаданих мережі, узгоджений із відповіддю таблиці лідерів.

## Опис ключових повернених полів

### Поля щоденних показників (StockDaily та StockDailyMetric)

Як елементи таблиці лідерів, так і щоденні історичні записи окремого токена містять такі основні поля:

| Поле                     | Тип                     | Опис                                                                                                                         |
| ------------------------ | ----------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `day`                    | `string` (дата)         | Дата агрегації за UTC у форматі `YYYY-MM-DD`.                                                                                |
| `token`                  | `string` (адреса)       | Адреса контракту токена (присутня лише в `StockDaily` таблиці лідерів), 40 малих шістнадцяткових символів із префіксом `0x`. |
| `symbol`                 | `string`                | Символ токена (наприклад, `"EXMPL"`).                                                                                        |
| `name`                   | `string`                | Відображувана назва токена; порожній рядок `""`, якщо відповідні метадані назви недоступні.                                  |
| `transfers`              | `integer` (int64)       | Загальна кількість ончейн-переказів за цей день UTC.                                                                         |
| `unique_senders`         | `integer` (int64)       | Кількість унікальних адрес відправників, які ініціювали перекази цього дня.                                                  |
| `unique_receivers`       | `integer` (int64)       | Кількість унікальних адрес одержувачів, які отримали перекази цього дня.                                                     |
| `mint_raw_amount`        | `string` (десятковий)   | Загальна необроблена кількість токенів, випущених цього дня.                                                                 |
| `burn_raw_amount`        | `string` (десятковий)   | Загальна необроблена кількість токенів, спалених цього дня.                                                                  |
| `net_supply_change`      | `string` (десятковий)   | Чиста зміна пропозиції за цей день (десятковий рядок зі знаком, може бути від'ємним).                                        |
| `holder_count`           | `integer` (int64)       | Загальна кількість адрес власників.                                                                                          |
| `top10_holder_share_bps` | `integer`               | Частка 10 найбільших власників у базисних пунктах (0–10000, 1 bps = 0.01%).                                                  |
| `dex_swap_count`         | `integer` (int64)       | Кількість обмінів на DEX за участю цього токена цього дня.                                                                   |
| `dex_raw_volume`         | `string` (десятковий)   | Загальний необроблений обсяг торгів на DEX за цей день.                                                                      |
| `refreshed_at`           | `string` (часова мітка) | Часова мітка ISO-8601 UTC останнього оновлення цього щоденного запису.                                                       |

### Поля метаданих токена (StockToken)

Під час запиту окремого токена зовнішній об'єкт `data` містить метадані контракту та нещодавні щоденні показники:

| Поле              | Тип                          | Опис                                                                                                                                  |
| ----------------- | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| `address`         | `string` (адреса)            | Адреса контракту токена.                                                                                                              |
| `symbol`          | `string`                     | Символ токена.                                                                                                                        |
| `name`            | `string`                     | Повна назва токена.                                                                                                                   |
| `decimals`        | `integer` або `null`         | Кількість десяткових знаків токена (0–255), або `null`, якщо недоступно.                                                              |
| `created_block`   | `integer` (int64)            | Номер блоку, в якому було створено контракт токена.                                                                                   |
| `created_tx_hash` | `string` (хеш)               | Хеш транзакції створення контракту, 64 малі шістнадцяткові символи з префіксом `0x`.                                                  |
| `factory`         | `string` (адреса)            | Адреса фабричного контракту.                                                                                                          |
| `creator`         | `string` (адреса) або `null` | Адреса творця, або `null`, якщо недоступно.                                                                                           |
| `mint_address`    | `string` (адреса) або `null` | Адреса емісії (mint), або `null`, якщо недоступно.                                                                                    |
| `burn_address`    | `string` (адреса) або `null` | Адреса спалювання (burn), або `null`, якщо недоступно.                                                                                |
| `daily`           | `array`                      | Масив нещодавніх щоденних показників (`StockDailyMetric`), до 30 днів, відсортований за датою у спадному порядку (найновіші першими). |
| `refreshed_at`    | `string` (часова мітка)      | Часова мітка ISO-8601 UTC останнього оновлення метаданих токена.                                                                      |

### Конвенції кодування

API дотримується суворих правил кодування для всіх ендпоінтів заради збереження числової точності та узгодженості:

* **Безпека грошових сум**: будь-яке значення, яке може перевищувати `2^53` (256-бітні цілі числа, такі як `mint_raw_amount`, `burn_raw_amount`, `net_supply_change` та `dex_raw_volume`), серіалізується як **десятковий рядок**, ніколи не як число JSON і ніколи в науковій чи шістнадцятковій нотації. Це запобігає втраті точності в таких середовищах, як JavaScript. У JavaScript/TypeScript парсіть за допомогою `BigInt(str)` (наприклад, `const net = BigInt(body.data.daily[0].net_supply_change)`); у Python парсіть за допомогою `int(str)`. Лічильники, що залишаються значно нижче `2^53` (`transfers`, `unique_senders`, `unique_receivers`, `holder_count`, `top10_holder_share_bps`, `dex_swap_count`, `created_block`), є звичайними числами JSON.
* **Двійкові та шістнадцяткові значення**: адреси мають вигляд `0x`, за яким слідують 40 малих шістнадцяткових символів; хеші мають вигляд `0x`, за яким слідують 64 малі шістнадцяткові символи. Усі повернені шістнадцяткові значення подаються виключно в нижньому регістрі.
* **Часові мітки та дати**: такі мітки, як `refreshed_at`, використовують формат `YYYY-MM-DDTHH:MM:SSZ` (ISO-8601 UTC із точністю до секунд). Щоденні агрегати (`day`) використовують прості календарні дати (`YYYY-MM-DD`).

## Оцінка використання (щоденне оновлення 50 токенів)

Запити до Data API споживають Compute Units (CU) на основі ваг методів платформи. Наведена нижче оцінка розглядає сценарій, у якому для 50 токенів виконується виклик `GET /{chain}/stocks/{token}` один раз на день за активними вагами методів:

- **Вага методу на виклик:** Кожен виклик `data.stock` споживає 15 CU (ціна за прейскурантом $1.50 за 1M викликів).
- **Щоденне оновлення 50 токенів** (один виклик `GET /{chain}/stocks/{token}` на токен, 50 викликів/день): щоденне споживання становить 750 CU; за 30-денний цикл це загалом становить 1,500 викликів із використанням 22,500 CU, близько <0.1% від безкоштовної квоти (30,000,000 CU). У разі перевищення безкоштовного ліміту або на платному плані загальна вартість використання за прейскурантом становить близько <$0.01/місяць.

## Початок роботи та оновлення тарифу

Безкоштовна квота ідеально підходить для розробки, тестування та помірних робочих навантажень. Коли ваш трафік зростає та вимагає вищого рівня паралелізму або більшої кількості compute units, поповніть баланс ончейн на сторінці [Білінг](https://console.blockvectra.com/billing/) у консолі; після підтвердження ончейн та зарахування коштів ліміт викликів на секунду для всього акаунта знімається. Кожен ключ залишається обмеженим лімітами швидкості CU та сплесків, як описано в [документації JSON-RPC](https://docs.blockvectra.com/en/api/json-rpc/#method-policy). Усі невикористані безкоштовні кредити залишаються у ваших Credits і все ще можуть використовуватися. Актуальні тарифи та одиниці білінгу дивіться на [сторінці Ціни](https://blockvectra.com/en/pricing/).

## Наступні кроки

* [Перегляньте каталог наборів даних](https://blockvectra.com/en/data/), щоб ознайомитися з усіма наборами даних, які індексує BlockVectra.
* [Перегляньте безкоштовний план і ціни](https://blockvectra.com/en/pricing/#free), щоб дізнатися, що включено у ваш акаунт.
* [Увійдіть до консолі](https://console.blockvectra.com/login/?next=%2Fkeys%2F), щоб створити API key.