From 95ae3570b46e185df01186898fc69e35f00d31cd Mon Sep 17 00:00:00 2001 From: roethke Date: Mon, 31 Aug 2026 13:08:59 -0700 Subject: [PATCH 1/2] add tokenized stocks integration guide --- docs/AGENTS.md | 6 +- .../integrate-tokenized-stocks.mdx | 107 ++++++++++++++++++ docs/docs.json | 1 + docs/llms-full.txt | 11 +- docs/llms.txt | 11 +- 5 files changed, 123 insertions(+), 13 deletions(-) create mode 100644 docs/build-on-base/integrate-defi/integrate-tokenized-stocks.mdx diff --git a/docs/AGENTS.md b/docs/AGENTS.md index 19b6c4b8e..b77e5b700 100644 --- a/docs/AGENTS.md +++ b/docs/AGENTS.md @@ -9,7 +9,7 @@ description: Look up Base documentation with a compact directory-grouped index b > High-signal index of section guides. Jump to a section's llms.txt for concise intros, curated links, and fast navigation. - [Agents](./agents/llms.txt) — Give your AI assistant a wallet. Base MCP connects any AI to your Base Account. Check balances, send funds, swap tokens, sign messages, and pay with x402. -- [Base Chain](./base-chain/llms.txt) — Base protocol specifications, core primitives, and network systems. +- [Base Chain](./base-chain/llms.txt) — Base protocol specifications — tokens, bridging, transactions, consensus, execution, and proofs. - [Build On Base](./build-on-base/llms.txt) — Build financial products on Base by outcome: integrate DeFi, tokenize assets, issue stablecoins, or accept payments. - [Fonts](./fonts/llms.txt) - [Get Started](./get-started/llms.txt) @@ -89,11 +89,11 @@ npx skills add base/base-skills |base-chain/specs/upgrades/jovian:derivation,exec-engine,l1-attributes,overview,system-config |build-on-base:assign-user-attributes,overview,test-on-vibenet |build-on-base/accept-payments:authorize-a-payment,batch-high-frequency-payments,call-a-paid-service,capture-a-partial-amount,capture-an-authorization,charge-for-an-api,charge-on-a-schedule,reconcile-payments,refund-a-payment,request-a-payment,send-a-payout,settle-usage-based-payments,split-a-payment,verify-a-payment,void-an-authorization,watch-for-payments -|build-on-base/integrate-defi:integrate-borrowing,integrate-earn-product,integrate-lending,integrate-trading +|build-on-base/integrate-defi:integrate-borrowing,integrate-earn-product,integrate-lending,integrate-tokenized-stocks,integrate-trading |build-on-base/issue-rwa:announce-a-distribution,apply-a-multiplier,cancel-blocked-units,create-an-asset-token,issue-units,pause-transfers,restrict-eligible-holders |build-on-base/issue-stablecoins:block-an-account,burn-supply,issue-your-stablecoin,mint-supply,pause-activity,reconcile-with-memos,recover-funds,restrict-who-can-hold |get-started:accept-payments,base-batches,base-chain,base-ecosystem-fund,base-services-hub,base,connect-to-base,docs-llms,docs-mcp,get-funds,integrate-defi,issue-rwa,issue-stablecoins,make-a-transaction,resources-for-ai-agents,sdks-and-apis -|root:changes,cookie-policy,ia-guidelines,privacy-policy,terms-of-service +|root:changes,content-guidelines,contribution-guidelines,cookie-policy,ia-guidelines,mintlify-reference,privacy-policy,terms-of-service |sdks:base-anvil,overview |sdks/base-account:overview |sdks/base-account/basenames:basename-transfer,basenames-faq diff --git a/docs/build-on-base/integrate-defi/integrate-tokenized-stocks.mdx b/docs/build-on-base/integrate-defi/integrate-tokenized-stocks.mdx new file mode 100644 index 000000000..121860689 --- /dev/null +++ b/docs/build-on-base/integrate-defi/integrate-tokenized-stocks.mdx @@ -0,0 +1,107 @@ +--- +title: "Integrate Tokenized Stocks" +description: "Step-by-step guide to integrating Coinbase tokenized stocks (B20) into any app: discover the official token list, read balances and prices, and handle corporate actions." +--- + +This guide covers the common integration path for building on Coinbase tokenized stocks, using a trading app as the worked example. Most app types (trading, wallet, portfolio tracker, analytics, DeFi) start from the same core steps; the [trading app example](#trading-app-example) below walks one through end to end. + +For the underlying token standard and full technical reference, see [Tokenized Stocks on Base](/base-chain/specs/reference/b20/tokenized-stocks-on-base) and the [B20 specification](/base-chain/specs/reference/b20/index). + + +**Source of truth for the token list.** Until the Coinbase Developer Platform (CDP) API is available, the authoritative list of live Coinbase tokenized stocks is the [Contract addresses](/base-chain/specs/reference/b20/tokenized-stocks-on-base#contract-addresses) table. This page is updated as each new wave of tokens lands. When the CDP API ships, migrate discovery to it. + + +## Before You Start + +- **Know the standard.** Tokenized stocks are [B20](/base-chain/network-information/b20-token-standard) tokens, an extension of ERC-20. Standard ERC-20 methods and events work natively, so most of your existing token tooling applies. +- **Identify tokens by address, not ticker.** Name, symbol, and metadata are mutable onchain and should be indexed by contract address. +- **Have an RPC endpoint.** Use a [node provider](/get-started/base-services-hub) or your own [Base node](/base-chain/node-operators/run-a-base-node). + +## The Core Integration Path + + + +Start every integration by resolving which tokens are official Coinbase stocks. The motivating use case ("show me all Coinbase stocks available") resolves to the [Contract addresses](/base-chain/specs/reference/b20/tokenized-stocks-on-base#contract-addresses) table, which is the interim source of truth. + + +Do not treat every token from the B20 factory or [`B20Created`](/base-chain/specs/reference/b20/interfaces/IB20Factory) event as an official Coinbase stock. The factory also carries test deployments and tokens in pre-launch phases that do not yet have full legal protections. If you enumerate onchain, always reconcile the result against the published list before surfacing a token to users. + + + + +For each address, read the display metadata: + +- **Onchain:** [`name`](/base-chain/specs/reference/b20/interfaces/IB20/name), [`symbol`](/base-chain/specs/reference/b20/interfaces/IB20/symbol), [`decimals`](/base-chain/specs/reference/b20/interfaces/IB20/decimals), and [`contractURI`](/base-chain/specs/reference/b20/interfaces/IB20/contractURI) ([ERC-7572](https://eips.ethereum.org/EIPS/eip-7572) metadata). +- **Offchain:** logos and market data are available from the canonical token list and market-data aggregators. + +Name and symbol are updatable onchain, so re-index them rather than caching once. See [Token information and listings](/base-chain/specs/reference/b20/tokenized-stocks-on-base#token-information-and-listings). + + + +A B20 balance is denominated in raw token units, not shares. Corporate actions (dividends, splits) change the redemption ratio through the token's [multiplier](/base-chain/specs/reference/b20/tokenized-stocks-on-base#multipliers). + + +One B20 token does not permanently equal one share. Always apply the current multiplier when converting between token units and underlying shares. + + +Use the built-in helpers rather than computing by hand: + +| Function | Description | +|----------|-------------| +| [`scaledBalanceOf(account)`](/base-chain/specs/reference/b20/interfaces/IB20Asset/scaledBalanceOf) | Raw balance × multiplier (shares redeemable) | +| [`toScaledBalance(raw)`](/base-chain/specs/reference/b20/interfaces/IB20Asset/toScaledBalance) | Convert raw amount to shares | +| [`toRawBalance(scaled)`](/base-chain/specs/reference/b20/interfaces/IB20Asset/toRawBalance) | Convert shares to raw amount | + + + +A tokenized stock's price is the underlying equity price scaled by the token's multiplier. Pick the source that fits your app: + +- **Onchain (Chainlink):** each equity has a total-return feed read via `latestRoundData()`. Feeds run 24/5, hold last close off-hours, and freeze during corporate actions. Always read `updatedAt` and apply staleness bounds; never settle or liquidate against a frozen feed. +- **Offchain (aggregators):** providers such as CoinGecko, CoinMarketCap, or RWA track the token's live DEX price 24/7. + +See [Price feeds](/base-chain/specs/reference/b20/tokenized-stocks-on-base#price-feeds) for feed addresses, decimals, and staleness handling. + + + +- **Multiplier updates:** watch [`MultiplierUpdated`](/base-chain/specs/reference/b20/interfaces/IB20Asset) so balances and prices stay correct across splits and dividends. +- **Announcements:** index [`Announcement` / `EndAnnouncement`](/base-chain/specs/reference/b20/tokenized-stocks-on-base#announcements) events to catch corporate actions as they execute. +- **Pauses:** specific functions can be [paused](/base-chain/specs/reference/b20/tokenized-stocks-on-base#pauses); monitor so you know whether transfers are currently possible. + + + +Holding and secondary-market trading are permissionless, but transfers can be gated by [policies](/base-chain/specs/reference/b20/tokenized-stocks-on-base#policies) (eg, blocking sanctioned addresses). + +- Check [`isAuthorized(policyID, account)`](/base-chain/specs/reference/b20/interfaces/IPolicyRegistry/isAuthorized) before presenting a transfer as available; a blocked transfer reverts. +- [`approve()`](/base-chain/specs/reference/b20/interfaces/IB20/approve) is not policy gated, so an existing approval does not guarantee the transfer will succeed. + + + +## Trading App Example + +All app types run the core path above; this is one worked example end to end. + +1. **Populate the tradable universe** from the [published token list](/base-chain/specs/reference/b20/tokenized-stocks-on-base#contract-addresses); reconcile any onchain discovery against it. +2. **Render each market** using onchain metadata (address-keyed) and a price source. +3. **Quote and value positions** with `scaledBalanceOf` and the current multiplier, never raw units. +4. **Gate the trade path** on `isAuthorized` and current pause state before submitting a transfer. +5. **Guard settlement** by rejecting stale or frozen feeds so you never fill against a corporate-action price. + +## Keep Your Integration Current + +- **Token list:** re-check the [Contract addresses](/base-chain/specs/reference/b20/tokenized-stocks-on-base#contract-addresses) table as new waves land, and migrate to the CDP API once it is available. +- **Corporate actions:** subscribe to `MultiplierUpdated` and announcement events rather than polling balances. +- **Prices:** enforce staleness bounds on every read; treat a non-advancing `updatedAt` as off-hours or paused, not as a live price. + +## Additional Resources + +- [Tokenized Stocks on Base](/base-chain/specs/reference/b20/tokenized-stocks-on-base) (technical reference) +- [B20 Standard](/base-chain/specs/reference/b20/index) +- [Base Standard Library](https://github.com/base/base-std/tree/main) + +## Disclaimer + +

Coinbase tokenized stocks are only available to persons in eligible jurisdictions outside of the U.S.

+ +

Inclusion of any third-party protocol or venue is for developer reference only and is not an endorsement, partnership, or warranty. Confirm addresses, feeds, and the token list against official sources before integrating.

+ +

Base is open-source, permissionless blockchain infrastructure. Each B20 token is deployed and configured by its issuer, who sets and controls all token parameters and administrative permissions; Base does not configure, administer, or control tokens deployed on the protocol.

diff --git a/docs/docs.json b/docs/docs.json index a37c1c3f7..3baf838f5 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -96,6 +96,7 @@ "group": "Integrate DeFi", "pages": [ "build-on-base/integrate-defi/integrate-trading", + "build-on-base/integrate-defi/integrate-tokenized-stocks", "build-on-base/integrate-defi/integrate-lending", "build-on-base/integrate-defi/integrate-borrowing", "build-on-base/integrate-defi/integrate-earn-product" diff --git a/docs/llms-full.txt b/docs/llms-full.txt index ef528684a..7810b20ef 100644 --- a/docs/llms-full.txt +++ b/docs/llms-full.txt @@ -87,7 +87,7 @@ const client = createPublicClient({ chain: base, transport: http() }) - [SDKs & APIs](https://docs.base.org/get-started/sdks-and-apis): Choose the Base SDK, API, CLI, or MCP integration that matches what you are building. ## Base Chain -- [Overview](https://docs.base.org/base-chain/overview): Base protocol specifications, core primitives, and network systems. +- [Overview](https://docs.base.org/base-chain/overview): Base protocol specifications — tokens, bridging, transactions, consensus, execution, and proofs. - [Overview](https://docs.base.org/base-chain/specs/overview): Technical specification of the Base Chain protocol, covering block derivation, execution, transaction propagation, and state verification. - [Specification](https://docs.base.org/base-chain/specs/protocol/consensus/index): Specification of the Base rollup node, describing its components and role in L2 block derivation and consensus. - [L2 Execution Engine](https://docs.base.org/base-chain/specs/protocol/execution/index): Specification of the L2 execution engine, detailing EIP-1559 parameters, fee vaults, Engine API usage, and execution layer behavior. @@ -168,10 +168,10 @@ const client = createPublicClient({ chain: base, transport: http() }) - [Security Council for Base](https://docs.base.org/base-chain/security/security-council): This page outlines the purpose, goals, structure, and responsibilities of the Security Council for Base. - [Native Account Abstraction](https://docs.base.org/base-chain/specs/native-account-abstraction): EIP-8130 reference for Base: vibenet chain details, client setup, transaction structure, account configuration, authenticators, and payers. - [Batcher](https://docs.base.org/base-chain/specs/protocol/batcher): Specification of the batcher (batch submitter), the component responsible for posting L2 sequencer data to L1 for data availability. -- [Standard Bridges](https://docs.base.org/base-chain/specs/protocol/bridging/bridges): Specification of the standard bridges enabling cross-domain ETH and ERC20 token transfers between L1 and L2 on Base. -- [Deposits](https://docs.base.org/base-chain/specs/protocol/bridging/deposits): Specification of the deposit mechanism for Base, detailing how L1 transactions are converted into L2 deposit transactions. +- [Standard Bridges](https://docs.base.org/base-chain/specs/protocol/bridging/bridges): Specification of the standard bridge contracts enabling cross-domain ETH and ERC-20 token transfers between L1 and L2 on Base. +- [Deposits](https://docs.base.org/base-chain/specs/protocol/bridging/deposits): How deposits work on Base — from user experience to the protocol-level deposit transaction type and guaranteed gas market. - [Cross Domain Messengers](https://docs.base.org/base-chain/specs/protocol/bridging/messengers): Specification of the cross-domain messenger contracts, providing a higher-level API for sending messages between L1 and L2 on Base. -- [Withdrawals](https://docs.base.org/base-chain/specs/protocol/bridging/withdrawals): Specification of the withdrawal mechanism for Base, describing how L2 state is proven on L1 and funds are released from the bridge. +- [Withdrawals](https://docs.base.org/base-chain/specs/protocol/bridging/withdrawals): How withdrawals work on Base — the standard 3-step flow, the 7-day challenge period, faster options, and the full protocol specification. - [Derivation](https://docs.base.org/base-chain/specs/protocol/consensus/derivation): Specification of the L2 chain derivation pipeline, describing how L2 blocks are deterministically derived from L1 data and sequencer batches. - [P2P](https://docs.base.org/base-chain/specs/protocol/consensus/p2p): Specification of the rollup node peer-to-peer network, covering node discovery, gossip protocol, and unsafe block propagation. - [RPC](https://docs.base.org/base-chain/specs/protocol/consensus/rpc): Specification of the rollup node RPC interface, including the optimism_outputAtBlock method for retrieving L2 output roots. @@ -314,7 +314,7 @@ const client = createPublicClient({ chain: base, transport: http() }) - [Dynamic Upgrades](https://docs.base.org/base-chain/specs/upgrades/cobalt/dynamic-upgrades): An Ethereum smart contract stores upgrade timestamps for Base nodes, allowing forks to activate at the scheduled time with no client restart. - [Native Account Abstraction](https://docs.base.org/base-chain/specs/upgrades/cobalt/eip-8130): Build with native account abstraction on Base. EIP-8130 smart accounts send ordinary transactions, with no bundlers or relays. - [Span-Batches](https://docs.base.org/base-chain/specs/upgrades/delta/span-batches): Specification of span batches introduced in Delta, a new batch format that compresses sequences of L2 blocks for more efficient L1 data posting. -- [200ms native blocks](https://docs.base.org/base-chain/specs/upgrades/denim/200ms-blocks): Specification for Denim's canonical 200ms blocks, including BaseTime, derivation, validation, and RPC behavior. +- [200ms Native Blocks](https://docs.base.org/base-chain/specs/upgrades/denim/200ms-blocks): Specification for Denim's canonical 200ms blocks, including BaseTime, derivation, validation, and RPC behavior. - [Derivation](https://docs.base.org/base-chain/specs/upgrades/ecotone/derivation): Derivation changes in the Ecotone upgrade, extending the retrieval stage to support EIP-4844 blobs as an additional data availability source. - [Ecotone L1 Attributes](https://docs.base.org/base-chain/specs/upgrades/ecotone/l1-attributes): L1 attributes transaction changes in the Ecotone upgrade, updating calldata format to support the new blob-based fee calculation model. - [Fjord L2 Chain Derivation Changes](https://docs.base.org/base-chain/specs/upgrades/fjord/derivation): Derivation changes in the Fjord upgrade, updating protocol parameters for max sequencer drift, channel bank size, and adding brotli compression support. @@ -419,6 +419,7 @@ const client = createPublicClient({ chain: base, transport: http() }) - [Integrate Borrowing](https://docs.base.org/build-on-base/integrate-defi/integrate-borrowing): Let users borrow USDC against WETH collateral with Morpho or Aave on Base. - [Integrate an Earn Product](https://docs.base.org/build-on-base/integrate-defi/integrate-earn-product): Give users a one-deposit USDC earn experience with Morpho vaults on Base. - [Integrate Lending](https://docs.base.org/build-on-base/integrate-defi/integrate-lending): Let users supply USDC directly to Morpho or Aave lending markets on Base. +- [Integrate Tokenized Stocks](https://docs.base.org/build-on-base/integrate-defi/integrate-tokenized-stocks): Step-by-step guide to integrating Coinbase tokenized stocks (B20) into any app: discover the official token list, read balances and prices, and handle corporate actions. - [Integrate Trading](https://docs.base.org/build-on-base/integrate-defi/integrate-trading): Let users swap tokens on Base with executable routes from the 0x Swap API. - [Announce a Distribution](https://docs.base.org/build-on-base/issue-rwa/announce-a-distribution): Publish a B20 Asset announcement and distribute additional units to holders in the same transaction. - [Apply a Multiplier](https://docs.base.org/build-on-base/issue-rwa/apply-a-multiplier): Apply a B20 Asset multiplier to update displayed unit balances without migrating holders. A stock split is one example. diff --git a/docs/llms.txt b/docs/llms.txt index c242f7cf1..6203f87fe 100644 --- a/docs/llms.txt +++ b/docs/llms.txt @@ -21,7 +21,7 @@ - [SDKs & APIs](https://docs.base.org/get-started/sdks-and-apis): Choose the Base SDK, API, CLI, or MCP integration that matches what you are building. ## Base Chain -- [Overview](https://docs.base.org/base-chain/overview): Base protocol specifications, core primitives, and network systems. +- [Overview](https://docs.base.org/base-chain/overview): Base protocol specifications — tokens, bridging, transactions, consensus, execution, and proofs. - [Overview](https://docs.base.org/base-chain/specs/overview): Technical specification of the Base Chain protocol, covering block derivation, execution, transaction propagation, and state verification. - [Specification](https://docs.base.org/base-chain/specs/protocol/consensus/index): Specification of the Base rollup node, describing its components and role in L2 block derivation and consensus. - [L2 Execution Engine](https://docs.base.org/base-chain/specs/protocol/execution/index): Specification of the L2 execution engine, detailing EIP-1559 parameters, fee vaults, Engine API usage, and execution layer behavior. @@ -102,10 +102,10 @@ - [Security Council for Base](https://docs.base.org/base-chain/security/security-council): This page outlines the purpose, goals, structure, and responsibilities of the Security Council for Base. - [Native Account Abstraction](https://docs.base.org/base-chain/specs/native-account-abstraction): EIP-8130 reference for Base: vibenet chain details, client setup, transaction structure, account configuration, authenticators, and payers. - [Batcher](https://docs.base.org/base-chain/specs/protocol/batcher): Specification of the batcher (batch submitter), the component responsible for posting L2 sequencer data to L1 for data availability. -- [Standard Bridges](https://docs.base.org/base-chain/specs/protocol/bridging/bridges): Specification of the standard bridges enabling cross-domain ETH and ERC20 token transfers between L1 and L2 on Base. -- [Deposits](https://docs.base.org/base-chain/specs/protocol/bridging/deposits): Specification of the deposit mechanism for Base, detailing how L1 transactions are converted into L2 deposit transactions. +- [Standard Bridges](https://docs.base.org/base-chain/specs/protocol/bridging/bridges): Specification of the standard bridge contracts enabling cross-domain ETH and ERC-20 token transfers between L1 and L2 on Base. +- [Deposits](https://docs.base.org/base-chain/specs/protocol/bridging/deposits): How deposits work on Base — from user experience to the protocol-level deposit transaction type and guaranteed gas market. - [Cross Domain Messengers](https://docs.base.org/base-chain/specs/protocol/bridging/messengers): Specification of the cross-domain messenger contracts, providing a higher-level API for sending messages between L1 and L2 on Base. -- [Withdrawals](https://docs.base.org/base-chain/specs/protocol/bridging/withdrawals): Specification of the withdrawal mechanism for Base, describing how L2 state is proven on L1 and funds are released from the bridge. +- [Withdrawals](https://docs.base.org/base-chain/specs/protocol/bridging/withdrawals): How withdrawals work on Base — the standard 3-step flow, the 7-day challenge period, faster options, and the full protocol specification. - [Derivation](https://docs.base.org/base-chain/specs/protocol/consensus/derivation): Specification of the L2 chain derivation pipeline, describing how L2 blocks are deterministically derived from L1 data and sequencer batches. - [P2P](https://docs.base.org/base-chain/specs/protocol/consensus/p2p): Specification of the rollup node peer-to-peer network, covering node discovery, gossip protocol, and unsafe block propagation. - [RPC](https://docs.base.org/base-chain/specs/protocol/consensus/rpc): Specification of the rollup node RPC interface, including the optimism_outputAtBlock method for retrieving L2 output roots. @@ -248,7 +248,7 @@ - [Dynamic Upgrades](https://docs.base.org/base-chain/specs/upgrades/cobalt/dynamic-upgrades): An Ethereum smart contract stores upgrade timestamps for Base nodes, allowing forks to activate at the scheduled time with no client restart. - [Native Account Abstraction](https://docs.base.org/base-chain/specs/upgrades/cobalt/eip-8130): Build with native account abstraction on Base. EIP-8130 smart accounts send ordinary transactions, with no bundlers or relays. - [Span-Batches](https://docs.base.org/base-chain/specs/upgrades/delta/span-batches): Specification of span batches introduced in Delta, a new batch format that compresses sequences of L2 blocks for more efficient L1 data posting. -- [200ms native blocks](https://docs.base.org/base-chain/specs/upgrades/denim/200ms-blocks): Specification for Denim's canonical 200ms blocks, including BaseTime, derivation, validation, and RPC behavior. +- [200ms Native Blocks](https://docs.base.org/base-chain/specs/upgrades/denim/200ms-blocks): Specification for Denim's canonical 200ms blocks, including BaseTime, derivation, validation, and RPC behavior. - [Derivation](https://docs.base.org/base-chain/specs/upgrades/ecotone/derivation): Derivation changes in the Ecotone upgrade, extending the retrieval stage to support EIP-4844 blobs as an additional data availability source. - [Ecotone L1 Attributes](https://docs.base.org/base-chain/specs/upgrades/ecotone/l1-attributes): L1 attributes transaction changes in the Ecotone upgrade, updating calldata format to support the new blob-based fee calculation model. - [Fjord L2 Chain Derivation Changes](https://docs.base.org/base-chain/specs/upgrades/fjord/derivation): Derivation changes in the Fjord upgrade, updating protocol parameters for max sequencer drift, channel bank size, and adding brotli compression support. @@ -353,6 +353,7 @@ - [Integrate Borrowing](https://docs.base.org/build-on-base/integrate-defi/integrate-borrowing): Let users borrow USDC against WETH collateral with Morpho or Aave on Base. - [Integrate an Earn Product](https://docs.base.org/build-on-base/integrate-defi/integrate-earn-product): Give users a one-deposit USDC earn experience with Morpho vaults on Base. - [Integrate Lending](https://docs.base.org/build-on-base/integrate-defi/integrate-lending): Let users supply USDC directly to Morpho or Aave lending markets on Base. +- [Integrate Tokenized Stocks](https://docs.base.org/build-on-base/integrate-defi/integrate-tokenized-stocks): Step-by-step guide to integrating Coinbase tokenized stocks (B20) into any app: discover the official token list, read balances and prices, and handle corporate actions. - [Integrate Trading](https://docs.base.org/build-on-base/integrate-defi/integrate-trading): Let users swap tokens on Base with executable routes from the 0x Swap API. - [Announce a Distribution](https://docs.base.org/build-on-base/issue-rwa/announce-a-distribution): Publish a B20 Asset announcement and distribute additional units to holders in the same transaction. - [Apply a Multiplier](https://docs.base.org/build-on-base/issue-rwa/apply-a-multiplier): Apply a B20 Asset multiplier to update displayed unit balances without migrating holders. A stock split is one example. From 3da3ca8750ddef095d48ff7a9d4f9b1edf801e43 Mon Sep 17 00:00:00 2001 From: roethke Date: Tue, 15 Sep 2026 14:59:52 -0700 Subject: [PATCH 2/2] docs: drop integrate-tokenized-stocks in favor of list-tokenized-stocks Master consolidated the tokenized-stocks reference into list-tokenized-stocks.mdx (the old tokenized-stocks-on-base page now redirects there). This unshipped guide overlapped heavily and had stale links, so remove it and redirect its path to list-tokenized-stocks. Co-Authored-By: Claude --- docs/AGENTS.md | 2 +- .../integrate-tokenized-stocks.mdx | 107 ------------------ docs/docs.json | 5 +- docs/llms-full.txt | 4 +- docs/llms.txt | 4 +- 5 files changed, 7 insertions(+), 115 deletions(-) delete mode 100644 docs/build-on-base/integrate-defi/integrate-tokenized-stocks.mdx diff --git a/docs/AGENTS.md b/docs/AGENTS.md index 286ff97a9..000bd734e 100644 --- a/docs/AGENTS.md +++ b/docs/AGENTS.md @@ -43,7 +43,7 @@ npx skills add base/base-skills |Get Started/Get Funding:get-started/base-batches,get-started/base-ecosystem-fund,get-started/base-services-hub |Get Started/References:get-started/base-chain,get-started/sdks-and-apis |Build on Base/Overview:build-on-base/overview,build-on-base/test-on-vibenet,build-on-base/assign-user-attributes -|Build on Base/Integrate DeFi:build-on-base/integrate-defi/integrate-trading,build-on-base/integrate-defi/integrate-tokenized-stocks,build-on-base/integrate-defi/integrate-lending,build-on-base/integrate-defi/integrate-borrowing,build-on-base/integrate-defi/integrate-earn-product,build-on-base/integrate-defi/list-tokenized-stocks +|Build on Base/Integrate DeFi:build-on-base/integrate-defi/integrate-trading,build-on-base/integrate-defi/integrate-lending,build-on-base/integrate-defi/integrate-borrowing,build-on-base/integrate-defi/integrate-earn-product,build-on-base/integrate-defi/list-tokenized-stocks |Build on Base/Tokenize Assets:build-on-base/issue-rwa/create-an-asset-token,build-on-base/issue-rwa/issue-units,build-on-base/issue-rwa/restrict-eligible-holders,build-on-base/issue-rwa/cancel-blocked-units,build-on-base/issue-rwa/announce-a-distribution,build-on-base/issue-rwa/apply-a-multiplier,build-on-base/issue-rwa/pause-transfers |Build on Base/Issue Stablecoins:build-on-base/issue-stablecoins/issue-your-stablecoin,build-on-base/issue-stablecoins/mint-supply,build-on-base/issue-stablecoins/burn-supply,build-on-base/issue-stablecoins/restrict-who-can-hold,build-on-base/issue-stablecoins/block-an-account,build-on-base/issue-stablecoins/recover-funds,build-on-base/issue-stablecoins/pause-activity,build-on-base/issue-stablecoins/reconcile-with-memos |Build on Base/Accept Payments/Take a Payment:build-on-base/accept-payments/request-a-payment,build-on-base/accept-payments/authorize-a-payment,build-on-base/accept-payments/capture-an-authorization,build-on-base/accept-payments/capture-a-partial-amount,build-on-base/accept-payments/void-an-authorization,build-on-base/accept-payments/charge-on-a-schedule diff --git a/docs/build-on-base/integrate-defi/integrate-tokenized-stocks.mdx b/docs/build-on-base/integrate-defi/integrate-tokenized-stocks.mdx deleted file mode 100644 index 121860689..000000000 --- a/docs/build-on-base/integrate-defi/integrate-tokenized-stocks.mdx +++ /dev/null @@ -1,107 +0,0 @@ ---- -title: "Integrate Tokenized Stocks" -description: "Step-by-step guide to integrating Coinbase tokenized stocks (B20) into any app: discover the official token list, read balances and prices, and handle corporate actions." ---- - -This guide covers the common integration path for building on Coinbase tokenized stocks, using a trading app as the worked example. Most app types (trading, wallet, portfolio tracker, analytics, DeFi) start from the same core steps; the [trading app example](#trading-app-example) below walks one through end to end. - -For the underlying token standard and full technical reference, see [Tokenized Stocks on Base](/base-chain/specs/reference/b20/tokenized-stocks-on-base) and the [B20 specification](/base-chain/specs/reference/b20/index). - - -**Source of truth for the token list.** Until the Coinbase Developer Platform (CDP) API is available, the authoritative list of live Coinbase tokenized stocks is the [Contract addresses](/base-chain/specs/reference/b20/tokenized-stocks-on-base#contract-addresses) table. This page is updated as each new wave of tokens lands. When the CDP API ships, migrate discovery to it. - - -## Before You Start - -- **Know the standard.** Tokenized stocks are [B20](/base-chain/network-information/b20-token-standard) tokens, an extension of ERC-20. Standard ERC-20 methods and events work natively, so most of your existing token tooling applies. -- **Identify tokens by address, not ticker.** Name, symbol, and metadata are mutable onchain and should be indexed by contract address. -- **Have an RPC endpoint.** Use a [node provider](/get-started/base-services-hub) or your own [Base node](/base-chain/node-operators/run-a-base-node). - -## The Core Integration Path - - - -Start every integration by resolving which tokens are official Coinbase stocks. The motivating use case ("show me all Coinbase stocks available") resolves to the [Contract addresses](/base-chain/specs/reference/b20/tokenized-stocks-on-base#contract-addresses) table, which is the interim source of truth. - - -Do not treat every token from the B20 factory or [`B20Created`](/base-chain/specs/reference/b20/interfaces/IB20Factory) event as an official Coinbase stock. The factory also carries test deployments and tokens in pre-launch phases that do not yet have full legal protections. If you enumerate onchain, always reconcile the result against the published list before surfacing a token to users. - - - - -For each address, read the display metadata: - -- **Onchain:** [`name`](/base-chain/specs/reference/b20/interfaces/IB20/name), [`symbol`](/base-chain/specs/reference/b20/interfaces/IB20/symbol), [`decimals`](/base-chain/specs/reference/b20/interfaces/IB20/decimals), and [`contractURI`](/base-chain/specs/reference/b20/interfaces/IB20/contractURI) ([ERC-7572](https://eips.ethereum.org/EIPS/eip-7572) metadata). -- **Offchain:** logos and market data are available from the canonical token list and market-data aggregators. - -Name and symbol are updatable onchain, so re-index them rather than caching once. See [Token information and listings](/base-chain/specs/reference/b20/tokenized-stocks-on-base#token-information-and-listings). - - - -A B20 balance is denominated in raw token units, not shares. Corporate actions (dividends, splits) change the redemption ratio through the token's [multiplier](/base-chain/specs/reference/b20/tokenized-stocks-on-base#multipliers). - - -One B20 token does not permanently equal one share. Always apply the current multiplier when converting between token units and underlying shares. - - -Use the built-in helpers rather than computing by hand: - -| Function | Description | -|----------|-------------| -| [`scaledBalanceOf(account)`](/base-chain/specs/reference/b20/interfaces/IB20Asset/scaledBalanceOf) | Raw balance × multiplier (shares redeemable) | -| [`toScaledBalance(raw)`](/base-chain/specs/reference/b20/interfaces/IB20Asset/toScaledBalance) | Convert raw amount to shares | -| [`toRawBalance(scaled)`](/base-chain/specs/reference/b20/interfaces/IB20Asset/toRawBalance) | Convert shares to raw amount | - - - -A tokenized stock's price is the underlying equity price scaled by the token's multiplier. Pick the source that fits your app: - -- **Onchain (Chainlink):** each equity has a total-return feed read via `latestRoundData()`. Feeds run 24/5, hold last close off-hours, and freeze during corporate actions. Always read `updatedAt` and apply staleness bounds; never settle or liquidate against a frozen feed. -- **Offchain (aggregators):** providers such as CoinGecko, CoinMarketCap, or RWA track the token's live DEX price 24/7. - -See [Price feeds](/base-chain/specs/reference/b20/tokenized-stocks-on-base#price-feeds) for feed addresses, decimals, and staleness handling. - - - -- **Multiplier updates:** watch [`MultiplierUpdated`](/base-chain/specs/reference/b20/interfaces/IB20Asset) so balances and prices stay correct across splits and dividends. -- **Announcements:** index [`Announcement` / `EndAnnouncement`](/base-chain/specs/reference/b20/tokenized-stocks-on-base#announcements) events to catch corporate actions as they execute. -- **Pauses:** specific functions can be [paused](/base-chain/specs/reference/b20/tokenized-stocks-on-base#pauses); monitor so you know whether transfers are currently possible. - - - -Holding and secondary-market trading are permissionless, but transfers can be gated by [policies](/base-chain/specs/reference/b20/tokenized-stocks-on-base#policies) (eg, blocking sanctioned addresses). - -- Check [`isAuthorized(policyID, account)`](/base-chain/specs/reference/b20/interfaces/IPolicyRegistry/isAuthorized) before presenting a transfer as available; a blocked transfer reverts. -- [`approve()`](/base-chain/specs/reference/b20/interfaces/IB20/approve) is not policy gated, so an existing approval does not guarantee the transfer will succeed. - - - -## Trading App Example - -All app types run the core path above; this is one worked example end to end. - -1. **Populate the tradable universe** from the [published token list](/base-chain/specs/reference/b20/tokenized-stocks-on-base#contract-addresses); reconcile any onchain discovery against it. -2. **Render each market** using onchain metadata (address-keyed) and a price source. -3. **Quote and value positions** with `scaledBalanceOf` and the current multiplier, never raw units. -4. **Gate the trade path** on `isAuthorized` and current pause state before submitting a transfer. -5. **Guard settlement** by rejecting stale or frozen feeds so you never fill against a corporate-action price. - -## Keep Your Integration Current - -- **Token list:** re-check the [Contract addresses](/base-chain/specs/reference/b20/tokenized-stocks-on-base#contract-addresses) table as new waves land, and migrate to the CDP API once it is available. -- **Corporate actions:** subscribe to `MultiplierUpdated` and announcement events rather than polling balances. -- **Prices:** enforce staleness bounds on every read; treat a non-advancing `updatedAt` as off-hours or paused, not as a live price. - -## Additional Resources - -- [Tokenized Stocks on Base](/base-chain/specs/reference/b20/tokenized-stocks-on-base) (technical reference) -- [B20 Standard](/base-chain/specs/reference/b20/index) -- [Base Standard Library](https://github.com/base/base-std/tree/main) - -## Disclaimer - -

Coinbase tokenized stocks are only available to persons in eligible jurisdictions outside of the U.S.

- -

Inclusion of any third-party protocol or venue is for developer reference only and is not an endorsement, partnership, or warranty. Confirm addresses, feeds, and the token list against official sources before integrating.

- -

Base is open-source, permissionless blockchain infrastructure. Each B20 token is deployed and configured by its issuer, who sets and controls all token parameters and administrative permissions; Base does not configure, administer, or control tokens deployed on the protocol.

diff --git a/docs/docs.json b/docs/docs.json index e2074fdbe..68bb6a07d 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -96,7 +96,6 @@ "group": "Integrate DeFi", "pages": [ "build-on-base/integrate-defi/integrate-trading", - "build-on-base/integrate-defi/integrate-tokenized-stocks", "build-on-base/integrate-defi/integrate-lending", "build-on-base/integrate-defi/integrate-borrowing", "build-on-base/integrate-defi/integrate-earn-product", @@ -2895,6 +2894,10 @@ "source": "/build-on-base/issue-rwa/list-tokenized-stocks", "destination": "/build-on-base/integrate-defi/list-tokenized-stocks" }, + { + "source": "/build-on-base/integrate-defi/integrate-tokenized-stocks", + "destination": "/build-on-base/integrate-defi/list-tokenized-stocks" + }, { "source": "/base-chain/specs/reference/b20/changelog", "destination": "/specifications/b20/changelog" diff --git a/docs/llms-full.txt b/docs/llms-full.txt index b5f0a18a6..21f4fae66 100644 --- a/docs/llms-full.txt +++ b/docs/llms-full.txt @@ -128,8 +128,6 @@ const client = createPublicClient({ chain: base, transport: http() }) - [Integrate Trading](https://docs.base.org/build-on-base/integrate-defi/integrate-trading): Let users swap tokens on Base with executable routes from the 0x Swap API. -- [Integrate Tokenized Stocks](https://docs.base.org/build-on-base/integrate-defi/integrate-tokenized-stocks): Step-by-step guide to integrating Coinbase tokenized stocks (B20) into any app: discover the official token list, read balances and prices, and handle corporate actions. - - [Integrate Lending](https://docs.base.org/build-on-base/integrate-defi/integrate-lending): Let users supply USDC directly to Morpho or Aave lending markets on Base. - [Integrate Borrowing](https://docs.base.org/build-on-base/integrate-defi/integrate-borrowing): Let users borrow USDC against WETH collateral with Morpho or Aave on Base. @@ -502,7 +500,7 @@ const client = createPublicClient({ chain: base, transport: http() }) - [PolicyRegistry: Composite Policies (UNION / INTERSECT)](https://docs.base.org/base-chain/specs/reference/b20/changelog/02-cobalt-policyregistry-composite-policy): Cobalt adds UNION and INTERSECT composite policies to PolicyRegistry so B20 integrations can combine simple authorization policies without flattening their member lists. -- [Validity Transactions](https://docs.base.org/upgrades/cobalt/validity-transactions): Validity transactions ship with the Cobalt upgrade. +- [Validity Transactions](https://docs.base.org/upgrades/cobalt/validity-transactions): Validity transactions ship with the Cobalt upgrade. Read the full specification in the Specifications tab. ### Beryl diff --git a/docs/llms.txt b/docs/llms.txt index 13f894a6b..d9a6f2e19 100644 --- a/docs/llms.txt +++ b/docs/llms.txt @@ -62,8 +62,6 @@ - [Integrate Trading](https://docs.base.org/build-on-base/integrate-defi/integrate-trading): Let users swap tokens on Base with executable routes from the 0x Swap API. -- [Integrate Tokenized Stocks](https://docs.base.org/build-on-base/integrate-defi/integrate-tokenized-stocks): Step-by-step guide to integrating Coinbase tokenized stocks (B20) into any app: discover the official token list, read balances and prices, and handle corporate actions. - - [Integrate Lending](https://docs.base.org/build-on-base/integrate-defi/integrate-lending): Let users supply USDC directly to Morpho or Aave lending markets on Base. - [Integrate Borrowing](https://docs.base.org/build-on-base/integrate-defi/integrate-borrowing): Let users borrow USDC against WETH collateral with Morpho or Aave on Base. @@ -436,7 +434,7 @@ - [PolicyRegistry: Composite Policies (UNION / INTERSECT)](https://docs.base.org/base-chain/specs/reference/b20/changelog/02-cobalt-policyregistry-composite-policy): Cobalt adds UNION and INTERSECT composite policies to PolicyRegistry so B20 integrations can combine simple authorization policies without flattening their member lists. -- [Validity Transactions](https://docs.base.org/upgrades/cobalt/validity-transactions): Validity transactions ship with the Cobalt upgrade. +- [Validity Transactions](https://docs.base.org/upgrades/cobalt/validity-transactions): Validity transactions ship with the Cobalt upgrade. Read the full specification in the Specifications tab. ### Beryl