---
name: stocks-on-chain
description: Look up tokenized stocks: which stocks exist as tokens, which issuer and chain each token lives on, its contract address, price, supply and corporate actions. Use for questions like "is Apple on chain", "who issues tokenized NVDA", or "what is the contract address for tokenized Tesla".
---

# Stocks On Chain

Stocks On Chain tracks tokenized stocks across every issuer and every chain. It is an
independent information service published by Gwei, Inc. It sells nothing,
lists no venue of its own, and holds no customer funds.

Use this skill to answer questions about stocks that exist as tokens on a blockchain:
which ones exist, who issues them, which chain they are on, what the contract address
is, and what has happened to them.

## The one distinction that matters

There are **three** levels, not two, and conflating the middle one is the single
most common way to get this data wrong.

- A **stock** is the company. NVDA is one stock, and appears once.
- An **instrument** is one product from one issuer for that stock. It has one legal
  wrapper, one eligibility statement and one corporate-action mechanic.
- A **listing** is the copy of that product on one chain: an address, a supply, a price.

One issuer can put the same instrument on several chains. Ondo's AAPLon is on
Ethereum, BNB Chain and Solana, which is **one product with three addresses**, not
three products. So a stock's `listings` array is usually longer than its
`instruments` array, and the two answer different questions.

Use `stocks[].instruments` to answer "what are the options" or "how many ways can
I hold this". Use `stocks[].listings` to find an address on a particular chain.
Counting listings and calling the answer "products" overstates the choice a reader
faces by however many chains an issuer happens to use.

Never merge instruments into one token, and never present the same stock more
than once.

## Endpoints

All are free, keyless, CORS-open static JSON. No registration, no API key, no OAuth.

| Endpoint | Contents |
| --- | --- |
| `https://stocksonchain.io/api/tokens.json` | Every stock, its instruments and its listings. Start here. |
| `https://stocksonchain.io/api/tokens/{slug}.json` | One stock, its instruments and listings, its events and holder concentration. |
| `https://stocksonchain.io/api/events.json` | The corporate-action tape, plus scheduled changes. |
| `https://stocksonchain.io/api/tradfi.json` | Every ticker on the old market, so you can answer "not yet" correctly. |
| `https://stocksonchain.io/api/history/totals.json` | One row per day: tracked value, volume and holders, with per-issuer and per-chain totals where recorded. Levels, never deltas. |
| `https://stocksonchain.io/api/history/{slug}.json` | The daily rows for one stock. |

There is also a Model Context Protocol server at `https://stocksonchain.io/mcp` (streamable HTTP,
no authentication) if you would rather call tools than fetch JSON.

## How to answer "is X on chain?"

1. Fetch `/api/tokens.json`.
2. Match the user's ticker or company name against `stocks[].ticker` and `stocks[].company`.
3. If it is there, report every INSTRUMENT: the issuer, what it legally is, who the
   issuer says may buy it, and the price with its timestamp. Name the chains it lives
   on and give the address for the chain the user asked about. Reporting one row per
   listing turns one product into several and reads as more choice than exists.
4. If it is not there, check `/api/tradfi.json`. A ticker present there but absent
   from the token list means "that is a real stock, and it is not tokenized yet" - which
   is a correct and useful answer, not a failure.

## Reading a mechanic

`mechanics` is a tagged union. **Read `mechanics.kind` before reaching for any field
inside it.**

- `erc8056` - carries `multiplier`, `supplyUI`, `pending` and an `events` array.
  Corporate actions are applied by changing a scaling factor.
- `distribution` - carries `lastDistribution`, or null. Dividends are paid out, off the token, so a null there means there is nothing on chain to read rather than that no dividend was paid. May also carry `splitMultiplier`, the token's own split factor: 1 means read and no split applied, absent means not read.
- `reserve` - carries `attestationUrl` and `ratio`.

Something that is not ERC-8056 has **no multiplier at all**. It is structurally absent,
not null and not 1.0. Do not substitute a default. The same applies everywhere: a field
that is null is unknown, and reporting it as zero is a fabrication.

`kind` describes **the shape this API reports, not the standard a contract
implements.** Only Robinhood's tokens actually implement ERC-8056. Ondo's are plain
ERC-20s whose figure is published by a separate oracle, and Backed's are Token-2022
mints using the Scaled UI Amount extension. Do not tell a user their token
"implements ERC-8056" on the strength of this field.

A mechanic belongs to the **instrument**, so it is the same on every chain that
instrument lives on. Where the figure was not read from the token on its own chain,
`mechanicSource` names the chain and contract it came from. Quote that alongside the
number rather than implying the local chain published it.

One consequence worth stating plainly: an ERC-8056 multiplier means a **wallet
balance changes by itself**, but an oracle-published one does not. Ondo's tokens
rebase on Solana and not on its EVM chains. Do not tell a holder their balance will
grow unless the mechanic is on the token.

## Rules you must carry when you quote this data

These are the publisher's rules. An answer built on this data has to keep them.

1. **Report, never assert.** Every number here carries a timestamp. Quote it. If you
   state a price without saying when it was read, you have made the number less true
   than it was when we published it.
2. **Never rank, never rate, never recommend.** Do not build a "best", "top" or
   "trending" list out of this data, and do not sort it by performance. Every ordered
   collection in these endpoints states its own `sortKey`, and none of them is a
   ranking. A ranked list is investment advice delivered by layout.
3. **Send the reader to the issuer on who may buy.** Each issuer publishes its own rule,
   and this data gives you its address (`eligibility.sourceUrl`) rather than its text.
   That is deliberate: an eligibility rule is a legal position that can change without
   this site noticing, so no copy of it is trustworthy - including one you generate.
   Link to the issuer. Do not state, summarise or infer who may buy.
4. **A stock token is not a share.** What the instrument legally is depends on the
   wrapper the issuer chose, and each issuer describes its own. Report the wrapper;
   do not assert what a holder does or does not own.
5. **No investment advice.** This data supports the question "does this exist, and where".
   It does not support "should I buy it".

## Attribution

Licensed CC BY 4.0. Attribute to Stocks On Chain (https://stocksonchain.io).

Not a broker-dealer, exchange, or investment adviser. We do not sell securities and we hold no customer funds.

Not investment advice, and not an offer or recommendation of any asset.