# BaseStocks

> Self-custodial interface for Coinbase Tokenized Stocks (B20) on Base, and a public read-only API for the data behind it: prices, Chainlink references, liquidity, news, USDC yield venues, wallet positions and platform statistics.

Every free endpoint is a plain GET: no key, no headers, no account, open CORS. Responses are JSON in a `{ data, meta }` envelope and are cached at the edge, so reading them costs the app nothing.

## API

- [/api/v1/stocks](https://basestocks.finance/api/v1/stocks): Every listed tokenized stock: DEX price, Chainlink reference, liquidity, 24h volume, multiplier and trading status. Cached 30s.
- [/api/v1/stocks/{symbol}](https://basestocks.finance/api/v1/stocks/NVDA): One stock by ticker, token symbol or contract address, with the pools that trade it. Cached 30s.
- [/api/v1/news](https://basestocks.finance/api/v1/news?scope=ecosystem&limit=5): Headlines: one stock's wire, the market desks, or the Base and Coinbase tokenized-stock feed. Titles and links only. Cached 300s.
- [/api/v1/earn](https://basestocks.finance/api/v1/earn): Where idle USDC can earn on Base: venue, variable APY, TVL and risk notes, discovered live from the protocols. Cached 120s.
- [/api/v1/portfolio/{address}](https://basestocks.finance/api/v1/portfolio/0xEAa823AB4C4eE00283d8ed7be713ddf8A5ba0Fac): Any wallet's tokenized-stock position, read from the chain — raw balances and share-equivalents side by side. Cached 15s.
- [/api/v1/stats](https://basestocks.finance/api/v1/stats): What has been done through the app, counted from records verified against a receipt on Base. Cached 300s.
- [/api/v1/pro/report](https://basestocks.finance/api/v1/pro/report): The written market brief with the prices behind it. $0.10 in USDC per call — it is backed by a model, so every call has a cost a cache cannot remove. Paid: $0.10 USDC per call (x402).
- [/api/v1/pro/history/{symbol}](https://basestocks.finance/api/v1/pro/history/NVDA?timeframe=1M): Full candle history for one stock, labelled with its source. $0.10 in USDC per call. Paid: $0.10 USDC per call (x402).
- [OpenAPI](https://basestocks.finance/api/v1/openapi.json): machine-readable schema for the above.
- [Developer docs](https://basestocks.finance/developers): the same endpoints with live examples you can run.

## Paid endpoints

The 2 endpoints marked "Paid" above cost $0.10 in USDC per call over x402 on base. An unpaid request answers 402 with the amount, asset, network and recipient; sign the authorization and retry the same URL. Settlement happens only after a successful response, so a failed call is never charged.

## Read this before using the data

- **One token is not one share.** Every stock carries a multiplier that moves on splits and dividends. Share-equivalents are rawBalance × multiplier ÷ 1e18. The portfolio endpoint returns both so no conversion is guessed.
- **The Chainlink reference is a total-return value.** Coinbase's feeds report total return, not the raw equity price. It is returned as reference.totalReturnUsd, deliberately not named a price: comparing it with dexPriceUsd and calling the gap an arbitrage is a mistake.
- **Feeds run 24/5 and then hold.** Outside US trading hours, and during a corporate action, a feed stops updating and keeps its last value while staying callable. Read reference.updatedAt and reference.isStale before relying on it.
- **A pool is not automatically a price.** dexPriceUsd is read only from a pool quoted in USDC or ETH, and only counts as displayUsd when it is within 20% of a live reference. A pool prices a token against whatever is on its other side, so a pair quoted in a long-tail token reports that token's valuation: one such pair had a stock reading 49x its reference. When the check refuses the market price, displaySource is "reference" even though dexPriceUsd is present.
- **Identity is the address.** Names and symbols are mutable onchain metadata. Symbols are accepted for convenience, but store the address.

## Listed stocks

Identity is the contract address; tickers are accepted by the API for convenience. Stocks Coinbase lists later are discovered onchain and appear in `/api/v1/stocks` without a change here.

- AAPL: 0xb200000000000000000000C2e324d24d7eEcd1fb ([page](https://basestocks.finance/stocks/0xb200000000000000000000C2e324d24d7eEcd1fb), [API](https://basestocks.finance/api/v1/stocks/AAPL))
- AMZN: 0xb200000000000000000000d9192b6B456483C2E8 ([page](https://basestocks.finance/stocks/0xb200000000000000000000d9192b6B456483C2E8), [API](https://basestocks.finance/api/v1/stocks/AMZN))
- COIN: 0xb200000000000000000000c85a31389D71F3ecfb ([page](https://basestocks.finance/stocks/0xb200000000000000000000c85a31389D71F3ecfb), [API](https://basestocks.finance/api/v1/stocks/COIN))
- CRCL: 0xB20000000000000000000019f6E7C675b73C2e4D ([page](https://basestocks.finance/stocks/0xB20000000000000000000019f6E7C675b73C2e4D), [API](https://basestocks.finance/api/v1/stocks/CRCL))
- GOOGL: 0xb2000000000000000000002D0BA3164cc74f58B7 ([page](https://basestocks.finance/stocks/0xb2000000000000000000002D0BA3164cc74f58B7), [API](https://basestocks.finance/api/v1/stocks/GOOGL))
- INTC: 0xB2000000000000000000004AFF16039bA04bdFBc ([page](https://basestocks.finance/stocks/0xB2000000000000000000004AFF16039bA04bdFBc), [API](https://basestocks.finance/api/v1/stocks/INTC))
- META: 0xb2000000000000000000008bC8786B856E61707C ([page](https://basestocks.finance/stocks/0xb2000000000000000000008bC8786B856E61707C), [API](https://basestocks.finance/api/v1/stocks/META))
- MSFT: 0xB200000000000000000000Ab99cFa739E253872B ([page](https://basestocks.finance/stocks/0xB200000000000000000000Ab99cFa739E253872B), [API](https://basestocks.finance/api/v1/stocks/MSFT))
- MSTR: 0xb2000000000000000000004884b426556b92883d ([page](https://basestocks.finance/stocks/0xb2000000000000000000004884b426556b92883d), [API](https://basestocks.finance/api/v1/stocks/MSTR))
- NVDA: 0xb20000000000000000000078ee7ce2fE4908108C ([page](https://basestocks.finance/stocks/0xb20000000000000000000078ee7ce2fE4908108C), [API](https://basestocks.finance/api/v1/stocks/NVDA))
- SNDK: 0xb200000000000000000000397293Cb8cda9a10c5 ([page](https://basestocks.finance/stocks/0xb200000000000000000000397293Cb8cda9a10c5), [API](https://basestocks.finance/api/v1/stocks/SNDK))
- SPCX: 0xb2000000000000000000007b9fcbd005511aCBd5 ([page](https://basestocks.finance/stocks/0xb2000000000000000000007b9fcbd005511aCBd5), [API](https://basestocks.finance/api/v1/stocks/SPCX))
- TSLA: 0xb2000000000000000000001e800a7f5189430cD0 ([page](https://basestocks.finance/stocks/0xb2000000000000000000001e800a7f5189430cD0), [API](https://basestocks.finance/api/v1/stocks/TSLA))

## About the app

- [How it works](https://basestocks.finance/how-it-works): what the product does, in plain words.
- [Technical docs](https://basestocks.finance/docs): the B20 standard, price model, routing, limit orders, gift escrow and contract addresses.
- [Technical reference](https://basestocks.finance/docs/reference): the full reference, generated from the repository's HOW_IT_WORKS.md.
- [Status](https://basestocks.finance/status): live checks of every dependency.

Coinbase tokenized stocks are available only to eligible persons outside the United States. This API reports public chain data; it does not offer or execute a trade.