> ## Documentation Index
> Fetch the complete documentation index at: https://docs.useotto.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Tokenized stock data API

> Choose token addresses and route-price samples on Robinhood Chain, or compare underlying stock movers across Robinhood Chain and Base B20.

Use `/tokenized-equities` to discover Robinhood Chain stock-token identities and sampled buy prices. Use `/tokenized-stock-movers` to compare the underlying US stocks' session moves across Robinhood Chain and Base B20; those moves are not token execution prices.

## Choose a registry or a movers snapshot

| Your task                                                    | Endpoint and current price                                                                         | Inputs and coverage                                                                                                                         |
| ------------------------------------------------------------ | -------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| Find stock-token addresses, decimals and sampled routability | [Tokenized equities](https://x402.ottoai.services/service-detail?path=/tokenized-equities)         | `GET /tokenized-equities`; Robinhood Chain, chain ID `4663`. Optional `thesis` narrows the registry by a theme or phrase.                   |
| Compare gainers and losers by underlying stock performance   | [Tokenized stock movers](https://x402.ottoai.services/service-detail?path=/tokenized-stock-movers) | `GET /tokenized-stock-movers`; no required parameters. Separate `rails.robinhood` and `rails.base_b20` sections, with Base chain ID `8453`. |
| Research the issuer behind a token                           | [SEC filings and fundamentals guide](/intelligence-guides/sec-filings-api)                         | Use the verified underlying US ticker, not a token symbol that merely looks similar.                                                        |

Coverage is the universe in the returned snapshot, not every tokenized stock in existence. Check `universeSize` and each rail's coverage/exclusions instead of relying on a fixed advertised count. The market-data chain is separate from the network used to pay for this API request.

## Prepare a request

Inspect the [current OpenAPI](https://x402.ottoai.services/openapi.json), then request a free challenge for your chosen task:

```bash theme={null}
curl -i --get 'https://x402.ottoai.services/tokenized-equities' \
  --data-urlencode 'thesis=semiconductors'

curl -i 'https://x402.ottoai.services/tokenized-stock-movers'
```

These unpaid calls return payment requirements, not stock data. Use the [HTTP payment client](/acp-swarm/x402#make-a-paid-request) with the route's current price and a spending cap. The route-specific [declared output schema and example](/acp-swarm/x402-examples#inspect-the-payment-and-declared-output) are available in discovery; save the actual paid body and receipt to inspect delivered values.

## Read registry prices correctly

The registry's result is in `data`. Its identity and route facts come from LI.FI data checked against Otto's verified token-address registry.

| Field                                           | Meaning                                                                                                                                     |
| ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `equities[].tokenAddress`, `symbol`, `decimals` | Verified identity for that Robinhood Chain token; rows that fail identity checks are withheld and counted in `pin.refused`                  |
| `listedOnRail`                                  | Whether LI.FI's token catalog lists the token; this alone does not establish a usable trade route                                           |
| `refExecution`                                  | A successful route sample at `refTradeUsd` from `refStableSymbol`, or `null` when no sample is available                                    |
| `executableBuyPriceUsd`                         | Sampled cost per token, calculated from the reference trade size and the route's minimum token output                                       |
| `referencePriceUsd`                             | LI.FI's catalog valuation of the token, which can differ from the sampled buy price                                                         |
| `referenceDeviationPct`                         | Catalog reference minus sampled buy price, divided by sampled buy price, as a percentage; it is not a trading spread or expected profit     |
| `quoteConclusive`, `quotesInconclusive`         | Whether a row's quote outcome is known, and how many universe rows remain inconclusive; an unanswered quote is not evidence of no liquidity |
| `referenceAsOf`, `generatedAt`, `pin.asOf`      | Catalog-read time, completed snapshot time and identity-registry date respectively; the registry date is not a price timestamp              |

`executableBuyPriceUsd` describes the route sampled during that refresh at that size. It is not a reserved quote for your wallet or a promise that a later trade will receive that price. Obtain a fresh execution quote for the actual amount and account before trading.

With `thesis`, check `matched` and `fellBackToUniverse` first: a no-match request can return the full registry for browsing. `matchedCount` counts matches across the universe; `shortlistCap` can limit returned rows. `matchReason` explains inclusion, while `matchedTradableSampled` and `matchedQuotesInconclusive` describe only the returned shortlist. Universe-level counts keep their original scope.

## Read stock movers correctly

Movers use Finnhub quotes for the **underlying US stock**, comparing its current session price with the prior session close. A token can trade at a premium or discount to that underlying. Base B20 rows use token addresses as identity because token metadata can change; read each row's `underlying` and the section's named `excluded` records.

The two sections have their own time and coverage fields. Read Robinhood's `currentSnapshotAt`, `changeState` and `staleFeedCount`; read Base B20's `currentAt`, `staleCount` and `coveredCount`. If `rails.base_b20` is `null`, the top-level `degraded` flag marks that missing rail. Do not turn an absent section into an empty or flat market.

The registry targets hourly refreshes and movers target 15-minute refreshes. Underlying quotes can lag the exchange, and outside US market hours values remain at the last session. Response-generation time does not make an old session current. Preserve the response's `meta`, timestamps and caveats when displaying a board.

For a person buying through the app, continue with [Discover and buy stocks](/using-otto-ai/stocks). Paying for either data API does not submit a trade or grant wallet authority.