# Daily on-chain metrics for tokenized stocks with the Data API

> Original page: https://docs.blockvectra.com/en/guides/stocks/

<Callout type="info">
  Data is derived from public on-chain records and is for informational purposes only. It does not constitute investment advice.
</Callout>

## What is the tokenized stocks dataset [#what-is-the-tokenized-stocks-dataset]

The BlockVectra Data API provides daily on-chain metrics and metadata for tokenized stocks. This dataset aggregates daily transfers, mints, burns, net supply changes, holder distributions, and decentralized exchange (DEX) trading metrics, enabling developers to track public activity for tokenized stocks.

For chains that offer this dataset, see the [Supported Chains](/en/chains/) page.

* **Base URL**: `https://dev-api.blockvectra.network/v1/data` — except for `GET /chains`, all Data API routes are prefixed with a chain identifier (e.g. `https://dev-api.blockvectra.network/v1/data/{chain}/…`)
* **Example chain**: `robinhood_mainnet` (used as an example path parameter; check [Supported Chains](/en/chains/) for all chains offering this dataset)
* **Authentication**: Provide your API key in the `x-api-key: <your_api_key>` request header
* **Billing and coverage**: Metered transparently in Compute Units (CU); only 2xx successful responses are billed. If a chain lacks stock coverage, the endpoint returns HTTP `422 no_coverage` (not billed)

## Daily leaderboard (`GET /{chain}/stocks`) [#daily-leaderboard-get-chainstocks]

The `GET /{chain}/stocks` endpoint returns a daily activity leaderboard of tokenized stocks for a specified UTC date, including display metadata (symbol, name, etc.), ordered by transfer activity descending (most active tokens first).

### Request parameters [#request-parameters]

* `{chain}` (path parameter, required): Chain identifier (for example, `robinhood_mainnet`).
* `day` (query parameter, optional): UTC calendar date in `YYYY-MM-DD` format. When omitted, defaults to the latest recorded day (if no activity is recorded, returns `200` with `data: []`). If provided but not a valid `YYYY-MM-DD` calendar date, returns HTTP `400` (`error.code = "bad_request"`).
* `limit` (query parameter, optional): Caps the number of records returned. Defaults to 50; values above 500 are clamped to 500; passing `0` or a non-integer returns HTTP `400` (`error.code = "bad_request"`).

### Pagination behavior [#pagination-behavior]

This endpoint is **not paginated**. The `limit` parameter caps the maximum number of records returned. In the enclosing `StockDailyListEnvelope` (`data` and `meta`), stock endpoints do not return `next_cursor` (the key is absent entirely, never `null`).

### Code examples [#code-examples]

<Tabs groupId="code-lang" items="['cURL', 'TypeScript', 'Python']">
  <Tab value="cURL">
    ```bash
    curl -s "https://dev-api.blockvectra.network/v1/data/robinhood_mainnet/stocks?day=2026-09-29&limit=10" \
      -H "x-api-key: $BLOCKVECTRA_API_KEY"
    ```
  </Tab>

  <Tab value="TypeScript">
    ```ts
    const res = await fetch(
      "https://dev-api.blockvectra.network/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);
    ```
  </Tab>

  <Tab value="Python">
    ```python
    import os
    import requests

    res = requests.get(
        "https://dev-api.blockvectra.network/v1/data/robinhood_mainnet/stocks?day=2026-09-29&limit=10",
        headers={"x-api-key": os.environ["BLOCKVECTRA_API_KEY"]},
    )
    print(res.json())
    ```
  </Tab>
</Tabs>

### Response structure [#response-structure]

The response envelope is `StockDailyListEnvelope`, containing `data` and `meta`:

* `data` (array): A list of daily leaderboard records (`StockDaily`), ordered by transfer activity descending (most active tokens first). Each item includes token identifiers (`token`, `symbol`, `name`), transfer activity (`transfers`, `unique_senders`, `unique_receivers`), supply metrics (`mint_raw_amount`, `burn_raw_amount`, `net_supply_change`), distribution metrics (`holder_count`, `top10_holder_share_bps`), DEX trading metrics (`dex_swap_count`, `dex_raw_volume`), and refresh timestamp (`refreshed_at`).
* `meta` (object): Chain metadata (`chain`, `chain_slug`, `chain_external_id`, `as_of_block`, `finalized_block`, `coverage`, `refreshed_at`). Stock endpoints do not return `next_cursor`.

## Get one tokenized stock (`GET /{chain}/stocks/{token}`) [#get-one-tokenized-stock-get-chainstockstoken]

The `GET /{chain}/stocks/{token}` endpoint fetches metadata and up to 30 days of recent daily metrics for a specific tokenized stock by its token address.

### Request parameters [#request-parameters-1]

* `{chain}` (path parameter, required): Chain identifier (for example, `robinhood_mainnet`).
* `{token}` (path parameter, required): 20-byte token contract address; `0x` prefix is optional and either case is accepted (returned addresses are normalized to `0x` followed by 40 lowercase hex digits). An invalid address format returns HTTP `400` (`error.code = "bad_request"`).
* If `{token}` is not a known tokenized stock, returns HTTP `404` (`error.code = "not_found"`). If `{chain}` is an unknown chain, returns HTTP `404` (`error.code = "unknown_chain"`).

### Code examples [#code-examples-1]

<Tabs groupId="code-lang" items="['cURL', 'TypeScript', 'Python']">
  <Tab value="cURL">
    ```bash
    curl -s "https://dev-api.blockvectra.network/v1/data/robinhood_mainnet/stocks/0x1111111111111111111111111111111111111111" \
      -H "x-api-key: $BLOCKVECTRA_API_KEY"
    ```
  </Tab>

  <Tab value="TypeScript">
    ```ts
    const token = "0x1111111111111111111111111111111111111111";
    const res = await fetch(
      `https://dev-api.blockvectra.network/v1/data/robinhood_mainnet/stocks/${token}`,
      {
        headers: { "x-api-key": process.env.BLOCKVECTRA_API_KEY! },
      },
    );
    const body = await res.json();
    console.log(body);
    ```
  </Tab>

  <Tab value="Python">
    ```python
    import os
    import requests

    token = "0x1111111111111111111111111111111111111111"
    res = requests.get(
        f"https://dev-api.blockvectra.network/v1/data/robinhood_mainnet/stocks/{token}",
        headers={"x-api-key": os.environ["BLOCKVECTRA_API_KEY"]},
    )
    print(res.json())
    ```
  </Tab>
</Tabs>

### Response structure [#response-structure-1]

The response envelope is `StockTokenEnvelope`, containing `data` and `meta`:

* `data` (object): A `StockToken` object containing token contract metadata (`address`, `symbol`, `name`, `decimals`, `created_block`, `created_tx_hash`, `factory`, `creator`, `mint_address`, `burn_address`, `refreshed_at`) and recent daily metrics array `daily`.
  * `daily` (array): An array of recent daily metrics (`StockDailyMetric`), up to 30 days, ordered by date descending (newest first). Each daily item shares the same metrics schema as the leaderboard above (without the redundant `token`, `symbol`, and `name` fields).
* `meta` (object): Chain metadata object consistent with the leaderboard response; stock endpoints do not return `next_cursor`.

## Key return fields explained [#key-return-fields-explained]

### Daily metric fields (StockDaily and StockDailyMetric) [#daily-metric-fields-stockdaily-and-stockdailymetric]

Both the leaderboard and single-token historical daily items include the following core fields:

| Field                    | Type                 | Description                                                                                                      |
| ------------------------ | -------------------- | ---------------------------------------------------------------------------------------------------------------- |
| `day`                    | `string` (date)      | UTC aggregation date formatted as `YYYY-MM-DD`.                                                                  |
| `token`                  | `string` (address)   | Token contract address (present only in leaderboard `StockDaily`), 40 lowercase hex characters with `0x` prefix. |
| `symbol`                 | `string`             | Token symbol (for example, `"EXMPL"`).                                                                           |
| `name`                   | `string`             | Token display name; empty string `""` when matching name metadata is unavailable.                                |
| `transfers`              | `integer` (int64)    | Total number of on-chain transfers on this UTC day.                                                              |
| `unique_senders`         | `integer` (int64)    | Number of unique sender addresses that initiated transfers on this day.                                          |
| `unique_receivers`       | `integer` (int64)    | Number of unique recipient addresses that received transfers on this day.                                        |
| `mint_raw_amount`        | `string` (decimal)   | Total raw token amount minted on this day.                                                                       |
| `burn_raw_amount`        | `string` (decimal)   | Total raw token amount burned on this day.                                                                       |
| `net_supply_change`      | `string` (decimal)   | Net supply change on this day (signed decimal string, may be negative).                                          |
| `holder_count`           | `integer` (int64)    | Total holder address count.                                                                                      |
| `top10_holder_share_bps` | `integer`            | Share of the top 10 holders in basis points (0–10000, 1 bps = 0.01%).                                            |
| `dex_swap_count`         | `integer` (int64)    | Number of DEX swaps involving this token on this day.                                                            |
| `dex_raw_volume`         | `string` (decimal)   | Total DEX raw trading volume on this day.                                                                        |
| `refreshed_at`           | `string` (timestamp) | ISO-8601 UTC timestamp of when this daily record was last refreshed.                                             |

### Token metadata fields (StockToken) [#token-metadata-fields-stocktoken]

When querying a single token, the outer `data` object contains contract metadata and recent daily metrics:

| Field             | Type                         | Description                                                                                                   |
| ----------------- | ---------------------------- | ------------------------------------------------------------------------------------------------------------- |
| `address`         | `string` (address)           | Token contract address.                                                                                       |
| `symbol`          | `string`                     | Token symbol.                                                                                                 |
| `name`            | `string`                     | Full token name.                                                                                              |
| `decimals`        | `integer` or `null`          | Token decimals (0–255), or `null` if unavailable.                                                             |
| `created_block`   | `integer` (int64)            | Block number in which the token contract was created.                                                         |
| `created_tx_hash` | `string` (hash)              | Contract creation transaction hash, 64 lowercase hex characters with `0x` prefix.                             |
| `factory`         | `string` (address)           | Factory contract address.                                                                                     |
| `creator`         | `string` (address) or `null` | Creator address, or `null` if unavailable.                                                                    |
| `mint_address`    | `string` (address) or `null` | Mint address, or `null` if unavailable.                                                                       |
| `burn_address`    | `string` (address) or `null` | Burn address, or `null` if unavailable.                                                                       |
| `daily`           | `array`                      | Array of recent daily metrics (`StockDailyMetric`), up to 30 days, ordered by date descending (newest first). |
| `refreshed_at`    | `string` (timestamp)         | ISO-8601 UTC timestamp of when token metadata was last refreshed.                                             |

### Encoding conventions [#encoding-conventions]

The API adheres to strict encoding rules across all endpoints to preserve numerical precision and consistency:

* **Money-safety**: Any value that can exceed `2^53` (256-bit integers such as `mint_raw_amount`, `burn_raw_amount`, `net_supply_change`, and `dex_raw_volume`) is serialized as a **decimal string**, never a JSON number and never scientific or hex notation. This prevents precision loss in runtimes like JavaScript. In JavaScript/TypeScript, parse with `BigInt(str)` (e.g. `const net = BigInt(body.data.daily[0].net_supply_change)`); in Python, parse with `int(str)`. Counters staying well below `2^53` (`transfers`, `unique_senders`, `unique_receivers`, `holder_count`, `top10_holder_share_bps`, `dex_swap_count`, `created_block`) are plain JSON numbers.
* **Binary and hex values**: Addresses are `0x` followed by 40 lowercase hexadecimal characters; hashes are `0x` followed by 64 lowercase hexadecimal characters. All returned hex values are strictly lowercase.
* **Timestamps and dates**: Timestamps such as `refreshed_at` use `YYYY-MM-DDTHH:MM:SSZ` (ISO-8601 UTC with second precision). Daily aggregates (`day`) use plain calendar dates (`YYYY-MM-DD`).

## Pagination notes [#pagination-notes]

Stock endpoints do not return `next_cursor` (these endpoints are not paginated; other Data API endpoints that support pagination pass `next_cursor` back via the `cursor` parameter). `GET /{chain}/stocks` uses the `limit` parameter to cap the maximum number of records returned (up to 500); `GET /{chain}/stocks/{token}` returns up to 30 days of recent daily metrics in the `daily` array, ordered by date descending (newest first).

## Usage estimate (refreshing 50 tokens daily) [#usage-estimate-refreshing-50-tokens-daily]

Data API queries consume Compute Units (CU) based on platform method weights. The estimate below evaluates a scenario where 50 tokens each call `GET /{chain}/stocks/{token}` once daily, evaluated dynamically at build time against active method weights without hardcoded figures in prose:

<StocksUsageEstimate lang="en" />

## Getting started and upgrading [#getting-started-and-upgrading]

The free quota is ideal for development, testing, and lightweight workloads. When your traffic expands and requires higher concurrency or more compute units, make a paid top-up in the [Console](https://console.blockvectra.com/en/login/) to upgrade to a paid account. After topping up, you are no longer constrained by the Free Plan's per-second call limit; each key remains subject to CU rate and burst limits, as described in the [JSON-RPC documentation](/en/api/json-rpc/#method-policy). Any unused Free Credits stay in your Credits and can still be used. For current rates and billing units, please see the [Pricing page](https://blockvectra.com/en/pricing/).

## Next steps [#next-steps]

* [Browse the datasets directory](https://blockvectra.com/en/data/) to see every dataset BlockVectra indexes.
* [See the free plan and pricing](https://blockvectra.com/en/pricing/#free) to check what your account includes.
* [Log in to the console](https://console.blockvectra.com/en/login/?next=%2Fen%2Fkeys%2F) to create an API key.