# Create a document signing submission for the authenticated partner and user
Source: https://docs.passage.coinlist.co/api-reference/documentsubmissions/create-a-document-signing-submission-for-the-authenticated-partner-and-user

/api-reference/openapi.json post /v1/documents/{document_type}/submission
Creates a signing submission for the given document type (e.g. a W-8BEN tax certification) for the current entity. The signing link is emailed to the user. Re-posting acts as a resend/re-sign where the document state allows it. The submitted PII pre-fills the form and is forwarded to Passport, never persisted by Frontline.



# Generate a Sumsub KYC access token
Source: https://docs.passage.coinlist.co/api-reference/kyc/generate-a-sumsub-kyc-access-token

/api-reference/openapi.json post /v1/kyc-token
Generates a short-lived Sumsub WebSDK access token for the current user so an identity verification flow can be started. Requires a user-scoped access token (authorization code grant); partner-only tokens (client credentials grant) are rejected.



# Introspect token
Source: https://docs.passage.coinlist.co/api-reference/oauth/introspect-token

/api-reference/openapi.json post /oauth/introspect
Returns metadata about an access token, including whether it is active.



# Issue OAuth access token
Source: https://docs.passage.coinlist.co/api-reference/oauth/issue-oauth-access-token

/api-reference/openapi.json post /oauth/token
Issues access tokens for `authorization_code`, `client_credentials`, and `refresh_token` grants using an `application/x-www-form-urlencoded` request body. For the `authorization_code` grant, the partner exchanges the code obtained from `GET /oauth/authorize` along with a PKCE `code_verifier`.



# Revoke token
Source: https://docs.passage.coinlist.co/api-reference/oauth/revoke-token

/api-reference/openapi.json post /oauth/revoke
Revokes an access or refresh token.



# Allow a wallet address for an offer
Source: https://docs.passage.coinlist.co/api-reference/offers/allow-a-wallet-address-for-an-offer

/api-reference/openapi.json post /v1/offers/{offer_id}/allow-wallet



# Connect a proven external wallet to an offer option
Source: https://docs.passage.coinlist.co/api-reference/offers/connect-a-proven-external-wallet-to-an-offer-option

/api-reference/openapi.json post /v1/offers/{offer_id}/addresses
For options without a whitelisted-wallet requirement, submitting when a wallet is already connected updates the existing binding in place, keeping its id. Options with a whitelisted-wallet requirement accumulate wallets up to the requirement's max_wallets and then reject with `max_wallets_reached`.



# Get an offer for the authenticated partner
Source: https://docs.passage.coinlist.co/api-reference/offers/get-an-offer-for-the-authenticated-partner

/api-reference/openapi.json get /v1/offers/{id}



# List offers for the authenticated partner
Source: https://docs.passage.coinlist.co/api-reference/offers/list-offers-for-the-authenticated-partner

/api-reference/openapi.json get /v1/offers



# List the user's connected wallets for an offer option
Source: https://docs.passage.coinlist.co/api-reference/offers/list-the-users-connected-wallets-for-an-offer-option

/api-reference/openapi.json get /v1/offers/{offer_id}/addresses



# Remove a connected external wallet from an offer option
Source: https://docs.passage.coinlist.co/api-reference/offers/remove-a-connected-external-wallet-from-an-offer-option

/api-reference/openapi.json delete /v1/offers/{offer_id}/addresses/{id}
Returns the removed binding. Rejected with `offer_ended` once the offer has ended; bindings on an offer that has not yet started remain deletable.



# Encode an Ondo swap for broadcast
Source: https://docs.passage.coinlist.co/api-reference/ondo/encode-an-ondo-swap-for-broadcast

/api-reference/openapi.json post /v1/ondo/swap/transaction
Encodes the buy the user just confirmed and returns calldata their wallet can sign and broadcast, plus the amounts it commits to. This is the commit step: it consumes an attestation and the calldata expires, so call it once per confirmation and never poll it. Approve the swap contract for the full amount first; an allowance short of it is rejected here rather than reverting on-chain. The addresses are resolved from the offer, so the request names the asset, not the tokens.



# Get whether an Ondo asset is currently tradable
Source: https://docs.passage.coinlist.co/api-reference/ondo/get-whether-an-ondo-asset-is-currently-tradable

/api-reference/openapi.json get /v1/ondo/swap/trading-status
Reports whether an Ondo asset can be traded right now on the given side, and the gross caps if so. Ondo reports its trading limits per side, so a buy and a sell of the same asset can differ. Free to poll and consumes no attestation.



# Quote an Ondo asset
Source: https://docs.passage.coinlist.co/api-reference/ondo/quote-an-ondo-asset

/api-reference/openapi.json get /v1/ondo/swap/quote
Prices a buy or sell of an Ondo asset and returns the quantity, the per-token USD price and the decimals the quantity is denominated in. Free to poll while the user edits an order; it consumes no attestation. Takes no chain parameter, since Ondo runs no testnet and every environment prices against Ethereum mainnet.



# Create a participation for the authenticated partner and user
Source: https://docs.passage.coinlist.co/api-reference/participations/create-a-participation-for-the-authenticated-partner-and-user

/api-reference/openapi.json post /v1/participations



# Get a participation for the authenticated partner and user
Source: https://docs.passage.coinlist.co/api-reference/participations/get-a-participation-for-the-authenticated-partner-and-user

/api-reference/openapi.json get /v1/participations/{id}



# List participations for the authenticated partner and user
Source: https://docs.passage.coinlist.co/api-reference/participations/list-participations-for-the-authenticated-partner-and-user

/api-reference/openapi.json get /v1/participations

## Filtering

`filters` takes Flop filter parameters serialized as `filters[0][field]`, `filters[0][op]`, and `filters[0][value]`, with one index per filter. The playground cannot build that shape, so use the code samples.

Filterable fields: `offer_id`, `offer_option_id`, `user_id`, `status`, `user_email`.


# Get PII for the authenticated partner and user
Source: https://docs.passage.coinlist.co/api-reference/pii/get-pii-for-the-authenticated-partner-and-user

/api-reference/openapi.json get /v1/pii
Returns the user's PII (full legal name, country of citizenship, tax ID, permanent address) to pre-fill tax forms such as the W-8BEN. Fields that are unavailable are null.



# List requirement statuses for all options of an offer
Source: https://docs.passage.coinlist.co/api-reference/requirements/list-requirement-statuses-for-all-options-of-an-offer

/api-reference/openapi.json get /v1/offers/{offer_id}/requirements/statuses



# List requirements for all options of an offer
Source: https://docs.passage.coinlist.co/api-reference/requirements/list-requirements-for-all-options-of-an-offer

/api-reference/openapi.json get /v1/offers/{offer_id}/requirements



# Get the swap contract's output token metadata
Source: https://docs.passage.coinlist.co/api-reference/swap/get-the-swap-contracts-output-token-metadata

/api-reference/openapi.json get /v1/swap/output-token
Resolves outputToken() on the Superstate swap contract and returns the ERC-20 name, symbol and decimals of that token.



# Get the swap contract's status
Source: https://docs.passage.coinlist.co/api-reference/swap/get-the-swap-contracts-status

/api-reference/openapi.json get /v1/swap/status
Reads stopped() and SWAP_LEVEL() on the Superstate swap contract so clients can determine whether swaps are currently allowed.



# Preview a swap
Source: https://docs.passage.coinlist.co/api-reference/swap/preview-a-swap

/api-reference/openapi.json get /v1/swap/preview
Reads preview(inputToken, amount) on the Superstate swap contract and returns the quote: the input amount to pay, the fee charged on it and the output amount to receive.



# Get the on-chain ERC-20 allowance for a token, owner and spender
Source: https://docs.passage.coinlist.co/api-reference/token/get-the-on-chain-erc-20-allowance-for-a-token-owner-and-spender

/api-reference/openapi.json get /v1/token/allowance
Reads allowance(owner, spender) on the ERC-20 token contract. Can be used to determine whether an approval transaction is needed before a swap or token sale.



# Get the on-chain ERC-20 balance of an address
Source: https://docs.passage.coinlist.co/api-reference/token/get-the-on-chain-erc-20-balance-of-an-address

/api-reference/openapi.json get /v1/token/balance
Reads balanceOf(owner) on the ERC-20 token contract. Used to display the balance of the connected wallet the user will pay with.



# Request a wallet ownership challenge
Source: https://docs.passage.coinlist.co/api-reference/wallet-ownership/request-a-wallet-ownership-challenge

/api-reference/openapi.json post /v1/wallet-ownership



# Check whether a wallet is authorized on a swap contract
Source: https://docs.passage.coinlist.co/api-reference/wallet/check-whether-a-wallet-is-authorized-on-a-swap-contract

/api-reference/openapi.json get /v1/wallet/authorized
Reads authorized(address) on the Superstate swap contract to determine whether the given wallet is allowed to swap.



# Asset catalog
Source: https://docs.passage.coinlist.co/assets/catalog

What is in the Passage catalog today, and a plain-language primer on each asset class.

## The catalog at a glance

| Category | Examples | Issuing partners |
| - | - | - |
| [Equities](/assets/equities) | Tokenized US stocks, equity index and sector funds | Superstate (Opening Bell), Ondo |
| [Fixed income (yield)](/assets/fixed-income) | US Treasury funds, corporate credit, CLOs | Ondo, WisdomTree (coming soon), Centrifuge (coming soon) |
| [Commodities](/assets/commodities) | Gold, silver, oil, natural gas | Ondo |
| [Token sales](/use-cases/token-sales) | New token offerings | CoinList |

Ondo alone contributes 442 assets across the three asset classes, and the catalog grows every time Passage connects to another tokenization platform.

> **[Equities](/assets/equities)**
>
> 391 assets

> **[Fixed income](/assets/fixed-income)**
>
> 30 assets

> **[Commodities](/assets/commodities)**
>
> 21 assets

See [Asset issuers](/assets/partners) for what each partner issues and what ownership of their tokens actually means.

## Trading windows

Ondo assets trade in sessions that follow the US stock market, and each asset has its own set of sessions. The **Trading window** column on [Equities](/assets/equities), [Fixed income](/assets/fixed-income), and [Commodities](/assets/commodities) shows which set applies.

| Trading window | When users can buy and sell (US Eastern time) |
| - | - |
| 24/7 | Every weekday session, plus weekends and US market holidays |
| 24/5 | Sunday 8:05 PM to Friday 7:59 PM, across all four weekday sessions |
| Extended hours | Weekdays, 4:01 AM to 7:59 PM |
| Market hours | Weekdays, 9:31 AM to 3:59 PM |

Some assets trade in a mix of sessions that does not fit these windows. For those, the column names the sessions instead, such as "Pre-market and regular hours."

### Sessions

| Session | Hours (US Eastern time) |
| - | - |
| Pre-market | 4:01 AM to 9:29 AM |
| Regular hours | 9:31 AM to 3:59 PM |
| Post-market | 4:01 PM to 7:59 PM |
| Overnight | 8:05 PM to 3:55 AM |
| Off-Hours | Friday evening to Sunday evening, and US market holidays |

Weekday sessions run only on US market days, so on a US market holiday only 24/7 assets trade. Trading pauses for a few minutes between sessions, during corporate actions on a ticker, and if risk limits trip. Outside regular hours, and especially in Off-Hours, liquidity is lower, spreads can be wider, and order limits are smaller.

> [!NOTE]
>
> Trading windows reflect Ondo's schedule as of October 22, 2026, and Ondo adds assets to
> Off-Hours over time. Live status for each asset is at
> [status.ondo.finance/market](https://status.ondo.finance/market).

## Understanding the asset classes

These primers are written for readers without a finance background.

### What is a stock?

A stock is an ownership share in a company. If you own a share of Apple, you own a piece of Apple. Your share entitles you to the economic upside of the company, dividends, and other rights like voting. When the company becomes more valuable, your share generally does too, and some companies pay owners a portion of profits as dividends. Stocks can trade on public exchanges, where prices move constantly based on what buyers and sellers think the company is worth. There are also private shares that don't trade on major exchanges, but are purchased directly from the company or existing investors.

### What is a tokenized stock?

A tokenized stock is a blockchain token that represents a share. Instead of holding shares in a brokerage account, your users hold a token in their own wallet. The token's value tracks the underlying stock, and it moves and settles like any other digital asset, including outside US market hours and without a registered brokerage relationship.

One thing worth knowing is that not all tokenized stocks are created equally. Some represent direct, real ownership of the underlying share. Others are wrapped exposure, which tracks the price but carries different rights. See [Asset issuers](/assets/partners) for how this works issuer by issuer.

### What is a fund?

A fund represents a basket of assets managed by an asset manager, for example WisdomTree. Funds can be managed actively, meaning the asset manager makes discretionary decisions on how to manage the portfolio, or passively, meaning the fund follows an existing asset allocation strategy or index. Some funds may be publicly traded like ETFs, while others may be private and not actively traded. There are many types of funds that represent exposure across all asset classes.

A large share of the funds in the catalog are index funds, which track a basket of assets rather than a single one. The S\&P 500 tracks 500 of the largest US companies, so one S\&P 500 fund gives a user diversified exposure to the broad US stock market rather than a bet on any one company. Index funds sit in the asset class they track, so an S\&P 500 fund is listed under [Equities](/assets/equities) and a Treasury bond fund under [Fixed income](/assets/fixed-income).

### What is a yield product?

A yield product covers a broad category of different types of financial assets. A yield product typically pays a return over time. The most common example is a US Treasury, which is a loan to the US government that pays interest and returns the principal at maturity. Because the US government backs them, US Treasuries are widely treated as one of the lowest-risk investments in the world, and their interest rate is often used as the baseline "risk-free" rate. Tokenized Treasury products let users hold that exposure as a token that accrues yield.

Corporate debt works the same way, except the borrowers are companies rather than the government. That usually means a higher yield in exchange for more risk.

### What is a commodity?

A commodity is a physical good that trades on a market, like gold, silver, oil, or natural gas. Prices move with global supply and demand rather than with the performance of any one company, which is why commodities are often held as a hedge against inflation or as diversification away from stocks.

Users rarely take delivery of the physical good. Instead they hold a fund that owns it on their behalf, such as a gold trust that stores bullion in a vault, or a fund that tracks the commodity through futures contracts. Tokenized commodity products deliver that exposure as a single token. Passage also groups commodity-linked equity funds here, such as copper and uranium miner funds, because users buy them for exposure to the underlying commodity.

> **[Next: Equities](/assets/equities)**
>
> Every tokenized stock and equity fund in the catalog, with ticker and issuer.


# Commodities
Source: https://docs.passage.coinlist.co/assets/commodities

Every tokenized metals, energy, and commodity product in the Passage catalog, with ticker and issuer.

Commodities are physical goods such as gold, silver, oil, and natural gas. The tokens below
give exposure to those goods, either through funds holding the physical commodity or through
futures and commodity-linked equities. See [Asset catalog](/assets/catalog) for a primer on
the asset class, and [Asset issuers](/assets/partners) for what ownership of an Ondo token
actually means.

> [!NOTE]
>
> The catalog below reflects Ondo's published assets as of July 22, 2026. For current
> availability, retrieve the [latest catalog](https://github.com/ondoprotocol/ondo-global-markets-token-list)
> at runtime.
>
> The **Trading window** column shows when users can buy and sell each asset, as of
> October 22, 2026. See [Trading windows](/assets/catalog#trading-windows) for what each one
> means, and [status.ondo.finance/market](https://status.ondo.finance/market) for live status.

## Assets

21 tokenized commodity assets.

The type column describes the instrument itself: **Company** for shares in a single company, **ETF**, **Fund**, or **Trust** for pooled vehicles that hold a basket on your behalf, and **Preferred** for preferred shares.

| Asset | Ticker | Type | Issued by | Trading window |
| - | - | - | - | - |
| abrdn Physical Palladium Shares ETF | `PALLon` | ETF | Ondo | 24/5 |
| abrdn Physical Platinum Shares ETF | `PPLTon` | ETF | Ondo | 24/5 |
| abrdn Physical Precious Metals Basket Shares ETF | `GLTRon` | ETF | Ondo | Extended hours |
| Breakwave Tanker Shipping ETF | `BWETon` | ETF | Ondo | Market hours |
| First Trust Global Tactical Commodity Strategy Fund | `FTGCon` | Fund | Ondo | Market hours |
| Franklin Responsibly Sourced Gold ETF | `FGDLon` | ETF | Ondo | Pre-market and regular hours |
| Global X Copper Miners ETF | `COPXon` | ETF | Ondo | Extended hours |
| Global X Silver Miners ETF | `SILon` | ETF | Ondo | 24/5 |
| Global X Uranium ETF | `URAon` | ETF | Ondo | 24/5 |
| Invesco DB Commodity Index Tracking Fund | `DBCon` | Fund | Ondo | Market hours |
| Invesco Optimum Yld Dvsfd Cmd Str No K-1 ETF | `PDBCon` | ETF | Ondo | Market hours |
| iShares Gold Trust | `IAUon` | Trust | Ondo | 24/5 |
| iShares Silver Trust | `SLVon` | Trust | Ondo | 24/7 |
| SPDR Gold Shares | `GLDon` | ETF | Ondo | 24/7 |
| Sprott Nickel Miners ETF | `NIKLon` | ETF | Ondo | Market hours |
| Sprott Uranium Miners ETF | `URNMon` | ETF | Ondo | 24/5 |
| United States Oil Fund | `USOon` | Fund | Ondo | 24/5 |
| US Brent Oil Fund | `BNOon` | Fund | Ondo | Extended hours |
| US Copper Index Fund | `CPERon` | Fund | Ondo | 24/5 |
| US Natural Gas Fund | `UNGon` | Fund | Ondo | 24/5 |
| VanEck Rare Earth and Strategic Metals ETF | `REMXon` | ETF | Ondo | Market hours |

> **[Next: Asset issuers](/assets/partners)**
>
> Ownership models and asset lifecycles, issuer by issuer.


# Equities
Source: https://docs.passage.coinlist.co/assets/equities

Every tokenized stock and equity fund in the Passage catalog, with ticker and issuer.

Equities are ownership shares in a company. Each token below tracks a listed share or an
equity fund, and settles onchain like any other digital asset. See
[Asset catalog](/assets/catalog) for a primer on the asset class, and
[Asset issuers](/assets/partners) for what ownership of an Ondo token actually means.

> [!NOTE]
>
> The catalog below reflects Ondo's published assets as of July 22, 2026. For current
> availability, retrieve the [latest catalog](https://github.com/ondoprotocol/ondo-global-markets-token-list)
> at runtime.
>
> The **Trading window** column shows when users can buy and sell each asset, as of
> October 22, 2026. See [Trading windows](/assets/catalog#trading-windows) for what each one
> means, and [status.ondo.finance/market](https://status.ondo.finance/market) for live status.

## Assets

391 tokenized equity assets: 326 single-company shares and
65 funds tracking equity indexes, sectors, regions, and themes.

The type column describes the instrument itself: **Company** for shares in a single company, **ETF**, **Fund**, or **Trust** for pooled vehicles that hold a basket on your behalf, and **Preferred** for preferred shares.

| Asset | Ticker | Type | Issued by | Trading window |
| - | - | - | - | - |
| AAON | `AAONon` | Company | Ondo | Pre-market and regular hours |
| Abbott | `ABTon` | Company | Ondo | 24/5 |
| AbbVie | `ABBVon` | Company | Ondo | 24/5 |
| Accenture | `ACNon` | Company | Ondo | 24/5 |
| ACM Research | `ACMRon` | Company | Ondo | Pre-market and regular hours |
| Adobe | `ADBEon` | Company | Ondo | 24/5 |
| Aehr Test Systems | `AEHRon` | Company | Ondo | 24/5 |
| Airbnb | `ABNBon` | Company | Ondo | 24/5 |
| Albemarle | `ALBon` | Company | Ondo | 24/5 |
| Alibaba | `BABAon` | Company | Ondo | 24/5 |
| Alpha and Omega Semiconductor | `AOSLon` | Company | Ondo | Market hours |
| Alphabet Class A | `GOOGLon` | Company | Ondo | 24/7 |
| Amazon | `AMZNon` | Company | Ondo | 24/7 |
| AMC Entertainment | `AMCon` | Company | Ondo | Market hours |
| AMD | `AMDon` | Company | Ondo | 24/7 |
| American Airlines Group | `AALon` | Company | Ondo | 24/5 |
| American Express | `AXPon` | Company | Ondo | 24/5 |
| AMETEK | `AMEon` | Company | Ondo | Extended hours |
| Amgen | `AMGNon` | Company | Ondo | 24/5 |
| Amkor Technology | `AMKRon` | Company | Ondo | 24/5 |
| Amphenol | `APHon` | Company | Ondo | 24/5 |
| Analog Devices | `ADIon` | Company | Ondo | Extended hours |
| Apollo Global Management | `APOon` | Company | Ondo | 24/5 |
| Apple | `AAPLon` | Company | Ondo | 24/7 |
| Applied Digital | `APLDon` | Company | Ondo | 24/5 |
| Applied Materials | `AMATon` | Company | Ondo | 24/5 |
| Applied Optoelectronics | `AAOIon` | Company | Ondo | 24/5 |
| AppLovin | `APPon` | Company | Ondo | 24/5 |
| Archer Aviation | `ACHRon` | Company | Ondo | Extended hours |
| Arista Networks | `ANETon` | Company | Ondo | 24/5 |
| Arm Holdings plc | `ARMon` | Company | Ondo | 24/7 |
| Arqit Quantum | `ARQQon` | Company | Ondo | Market hours |
| Arteris | `AIPon` | Company | Ondo | Market hours |
| ASML Holding NV | `ASMLon` | Company | Ondo | 24/5 |
| AST SpaceMobile | `ASTSon` | Company | Ondo | 24/5 |
| Astera Labs | `ALABon` | Company | Ondo | 24/5 |
| AT\&T | `Ton` | Company | Ondo | 24/5 |
| Atkore | `ATKRon` | Company | Ondo | Market hours |
| Aurora Innovation | `AURon` | Company | Ondo | Regular hours and post-market |
| Axcelis Technologies | `ACLSon` | Company | Ondo | Pre-market and regular hours |
| AXT | `AXTIon` | Company | Ondo | 24/5 |
| B2Gold | `BTGon` | Company | Ondo | Market hours |
| Baidu | `BIDUon` | Company | Ondo | 24/5 |
| Bank of America | `BACon` | Company | Ondo | 24/5 |
| BigBear.ai Holdings | `BBAIon` | Company | Ondo | Extended hours |
| Bilibili | `BILIon` | Company | Ondo | 24/5 |
| Bitdeer Technologies | `BTDRon` | Company | Ondo | Pre-market and regular hours |
| BitGo Holdings | `BTGOon` | Company | Ondo | Extended hours |
| BitMine Immersion Technologies | `BMNRon` | Company | Ondo | 24/5 |
| Blackrock, Inc. | `BLKon` | Company | Ondo | 24/5 |
| Block | `XYZon` | Company | Ondo | Regular hours and overnight |
| Bloom Energy | `BEon` | Company | Ondo | 24/5 |
| Boeing | `BAon` | Company | Ondo | 24/5 |
| Broadcom | `AVGOon` | Company | Ondo | 24/7 |
| Bullish | `BLSHon` | Company | Ondo | Market hours |
| Cameco | `CCJon` | Company | Ondo | 24/5 |
| Camtek | `CAMTon` | Company | Ondo | Pre-market and regular hours |
| Capital One | `COFon` | Company | Ondo | 24/5 |
| Capricor Therapeutics | `CAPRon` | Company | Ondo | Market hours |
| Carvana | `CVNAon` | Company | Ondo | 24/5 |
| Caterpillar | `CATon` | Company | Ondo | 24/5 |
| Celestica | `CLSon` | Company | Ondo | 24/5 |
| Cerebras Systems | `CBRSon` | Company | Ondo | 24/5 |
| CEVA | `CEVAon` | Company | Ondo | Market hours |
| Charles Schwab | `SCHWon` | Company | Ondo | Regular hours and overnight |
| Chevron | `CVXon` | Company | Ondo | 24/5 |
| Chipotle | `CMGon` | Company | Ondo | 24/5 |
| Ciena | `CIENon` | Company | Ondo | 24/5 |
| Cipher Mining | `CIFRon` | Company | Ondo | Extended hours |
| Circle Internet Group | `CRCLon` | Company | Ondo | 24/7 |
| Cisco Systems | `CSCOon` | Company | Ondo | 24/5 |
| Citigroup | `Con` | Company | Ondo | 24/5 |
| Cleveland-Cliffs | `CLFon` | Company | Ondo | Extended hours |
| Cloudflare | `NETon` | Company | Ondo | 24/5 |
| Coca-Cola | `KOon` | Company | Ondo | 24/5 |
| Coherent | `COHRon` | Company | Ondo | 24/5 |
| Cohu | `COHUon` | Company | Ondo | Market hours |
| Coinbase | `COINon` | Company | Ondo | 24/7 |
| ConocoPhillips | `COPon` | Company | Ondo | Extended hours |
| Constellation Energy | `CEGon` | Company | Ondo | 24/5 |
| Core Scientific | `CORZon` | Company | Ondo | 24/5 |
| CoreWeave | `CRWVon` | Company | Ondo | 24/5 |
| Corning | `GLWon` | Company | Ondo | 24/7 |
| Costco | `COSTon` | Company | Ondo | 24/5 |
| Coupang | `CPNGon` | Company | Ondo | Extended hours |
| Credo Technology Group Holding | `CRDOon` | Company | Ondo | 24/5 |
| CrowdStrike | `CRWDon` | Company | Ondo | 24/5 |
| D-Wave Quantum | `QBTSon` | Company | Ondo | 24/5 |
| Deere | `DEon` | Company | Ondo | Extended hours |
| Defiance Quantum ETF | `QTUMon` | ETF | Ondo | 24/5 |
| Dell Technologies | `DELLon` | Company | Ondo | 24/5 |
| Denison Mines | `DNNon` | Company | Ondo | Market hours |
| Digi Power X | `DGXXon` | Company | Ondo | Extended hours |
| Direxion Daily Semi Bear 3X ETF | `SOXSon` | ETF | Ondo | 24/5 |
| Direxion Daily Semi Bull 3X ETF | `SOXLon` | ETF | Ondo | Extended hours |
| Disney | `DISon` | Company | Ondo | 24/5 |
| DoorDash | `DASHon` | Company | Ondo | 24/5 |
| Eaton | `ETNon` | Company | Ondo | 24/5 |
| Eli Lilly | `LLYon` | Company | Ondo | 24/5 |
| Emerson Electric | `EMRon` | Company | Ondo | Market hours |
| Enbridge | `ENBon` | Company | Ondo | Extended hours |
| Energy Fuels | `UUUUon` | Company | Ondo | 24/5 |
| Enlivex Therapeutics | `ENLVon` | Company | Ondo | Market hours |
| Enphase Energy | `ENPHon` | Company | Ondo | 24/5 |
| Entegris | `ENTGon` | Company | Ondo | Pre-market and regular hours |
| EQT | `EQTon` | Company | Ondo | Extended hours |
| Equinix | `EQIXon` | Company | Ondo | 24/5 |
| Exodus Movement | `EXODon` | Company | Ondo | Market hours |
| Extreme Networks | `EXTRon` | Company | Ondo | Market hours |
| Exxon Mobil | `XOMon` | Company | Ondo | 24/5 |
| Fabrinet | `FNon` | Company | Ondo | 24/5 |
| Fidelity Solana Fund | `FSOLon` | Fund | Ondo | Extended hours |
| Figma | `FIGon` | Company | Ondo | 24/5 |
| Figure Technology Solutions | `FIGRon` | Company | Ondo | Market hours |
| First Majestic Silver | `AGon` | Company | Ondo | 24/5 |
| First Trust NASDAQ Cybersecurity ETF | `CIBRon` | ETF | Ondo | Pre-market, regular hours, and overnight |
| Flex | `FLEXon` | Company | Ondo | Extended hours |
| Fluence Energy | `FLNCon` | Company | Ondo | 24/5 |
| Ford Motor | `Fon` | Company | Ondo | 24/5 |
| Forgent Power Solutions | `FPSon` | Company | Ondo | Pre-market and regular hours |
| FormFactor | `FORMon` | Company | Ondo | 24/5 |
| Franklin Focused Growth ETF | `FFOGon` | ETF | Ondo | Market hours |
| Franklin Income Equity Focus ETF | `INCEon` | ETF | Ondo | Market hours |
| Franklin US Large Cap Multifactor Index ETF | `FLQLon` | ETF | Ondo | Market hours |
| Freeport-McMoRan | `FCXon` | Company | Ondo | 24/5 |
| FuelCell Energy | `FCELon` | Company | Ondo | 24/5 |
| Fundrise Innovation Fund | `VCXon` | Fund | Ondo | Extended hours |
| Futu Holdings | `FUTUon` | Company | Ondo | 24/5 |
| Galaxy Digital | `GLXYon` | Company | Ondo | Pre-market, regular hours, and overnight |
| GameStop | `GMEon` | Company | Ondo | 24/7 |
| GE Vernova | `GEVon` | Company | Ondo | 24/5 |
| Gemini Space Station | `GEMIon` | Company | Ondo | Market hours |
| Generac Holdings | `GNRCon` | Company | Ondo | Extended hours |
| General Dynamics | `GDon` | Company | Ondo | Regular hours and post-market |
| General Electric | `GEon` | Company | Ondo | 24/5 |
| Global X Artificial Intelligence & Technology ETF | `AIQon` | ETF | Ondo | Market hours |
| Global X Blockchain ETF | `BKCHon` | ETF | Ondo | Pre-market, regular hours, and overnight |
| Global X Data Center & Digital Infrastructure ETF | `DTCRon` | ETF | Ondo | Extended hours |
| Global X Defense Tech ETF | `SHLDon` | ETF | Ondo | 24/5 |
| Global X Lithium & Battery Tech ETF | `LITon` | ETF | Ondo | Extended hours |
| Global X MSCI Argentina ETF | `ARGTon` | ETF | Ondo | Regular hours and overnight |
| Global X NASDAQ 100 Covered Call ETF | `QYLDon` | ETF | Ondo | 24/5 |
| Global X Robotics & Artificial Intelligence ETF | `BOTZon` | ETF | Ondo | 24/5 |
| Global X S\&P 500 Covered Call ETF | `XYLDon` | ETF | Ondo | Extended hours |
| Global X Space Tech ETF | `ORBXon` | ETF | Ondo | Market hours |
| Global X US Infrastructure Development ETF | `PAVEon` | ETF | Ondo | 24/5 |
| GlobalFoundries | `GFSon` | Company | Ondo | 24/5 |
| Goldman Sachs | `GSon` | Company | Ondo | 24/5 |
| Grab Holdings | `GRABon` | Company | Ondo | Market hours |
| Grindr | `GRNDon` | Company | Ondo | Market hours |
| Halliburton | `HALon` | Company | Ondo | 24/5 |
| Harmonic | `HLITon` | Company | Ondo | Market hours |
| Hesai Group | `HSAIon` | Company | Ondo | Pre-market, regular hours, and overnight |
| Hewlett Packard Enterprise | `HPEon` | Company | Ondo | Pre-market, regular hours, and overnight |
| Himax Technologies | `HIMXon` | Company | Ondo | Market hours |
| Hims & Hers Health | `HIMSon` | Company | Ondo | 24/5 |
| HIVE Digital Technologies | `HIVEon` | Company | Ondo | Extended hours |
| Home Depot | `HDon` | Company | Ondo | Market hours |
| Hubbell | `HUBBon` | Company | Ondo | 24/5 |
| Huntington Ingalls Industries | `HIIon` | Company | Ondo | Pre-market and regular hours |
| Hut 8 | `HUTon` | Company | Ondo | 24/5 |
| Hyperliquid Strategies | `PURRon` | Company | Ondo | Market hours |
| IBM | `IBMon` | Company | Ondo | 24/5 |
| Ichor Holdings | `ICHRon` | Company | Ondo | Pre-market and regular hours |
| Innodata | `INODon` | Company | Ondo | 24/5 |
| Intel | `INTCon` | Company | Ondo | 24/7 |
| International Seaways | `INSWon` | Company | Ondo | Pre-market and regular hours |
| Intuit | `INTUon` | Company | Ondo | 24/5 |
| Intuitive Machines | `LUNRon` | Company | Ondo | Regular hours, post-market, and overnight |
| Intuitive Surgical | `ISRGon` | Company | Ondo | 24/5 |
| Invesco PHLX Semiconductor ETF | `SOXQon` | ETF | Ondo | 24/5 |
| Invesco QQQ | `QQQon` | ETF | Ondo | 24/7 |
| IonQ | `IONQon` | Company | Ondo | 24/5 |
| IREN | `IRENon` | Company | Ondo | 24/5 |
| Iridium Communications | `IRDMon` | Company | Ondo | Pre-market and regular hours |
| iShares A.I. Innovation and Tech Active ETF | `BAIon` | ETF | Ondo | Extended hours |
| iShares Bitcoin Trust | `IBITon` | Trust | Ondo | 24/7 |
| iShares China Large-Cap ETF | `FXIon` | ETF | Ondo | 24/5 |
| iShares Core MSCI EAFE ETF | `IEFAon` | ETF | Ondo | 24/5 |
| iShares Core MSCI Emerging Markets ETF | `IEMGon` | ETF | Ondo | 24/5 |
| iShares Core S\&P 500 ETF | `IVVon` | ETF | Ondo | 24/5 |
| iShares Core S\&P MidCap ETF | `IJHon` | ETF | Ondo | 24/5 |
| iShares Core S\&P Total US Stock Market ETF | `ITOTon` | ETF | Ondo | Extended hours |
| iShares Defense Industrials Active ETF | `IDEFon` | ETF | Ondo | Market hours |
| iShares Ethereum Trust ETF | `ETHAon` | ETF | Ondo | 24/7 |
| iShares Expanded Tech-Software ETF | `IGVon` | ETF | Ondo | 24/5 |
| iShares International Country Rotation Active ETF | `COROon` | ETF | Ondo | Pre-market and regular hours |
| iShares Large Cap Core Active ETF | `BLCRon` | ETF | Ondo | Pre-market and regular hours |
| iShares MSCI Brazil ETF | `EWZon` | ETF | Ondo | Extended hours |
| iShares MSCI Chile ETF | `ECHon` | ETF | Ondo | Pre-market and regular hours |
| iShares MSCI EAFE ETF | `EFAon` | ETF | Ondo | 24/5 |
| iShares MSCI EAFE Value ETF | `EFVon` | ETF | Ondo | Pre-market, regular hours, and overnight |
| iShares MSCI Emerging Markets ETF | `EEMon` | ETF | Ondo | 24/5 |
| iShares MSCI India ETF | `INDAon` | ETF | Ondo | 24/5 |
| iShares MSCI Japan ETF | `EWJon` | ETF | Ondo | 24/5 |
| iShares MSCI South Korea ETF | `EWYon` | ETF | Ondo | 24/5 |
| iShares Russell 1000 Growth ETF | `IWFon` | ETF | Ondo | 24/5 |
| iShares Russell 2000 ETF | `IWMon` | ETF | Ondo | 24/5 |
| iShares Russell 2000 Value ETF | `IWNon` | ETF | Ondo | 24/5 |
| iShares S\&P Small-Cap 600 Value ETF | `IJSon` | ETF | Ondo | 24/5 |
| iShares Semiconductor ETF | `SOXXon` | ETF | Ondo | 24/5 |
| iShares Systematic Alternatives Active ETF | `IALTon` | ETF | Ondo | Market hours |
| iShares US Aerospace and Defense ETF | `ITAon` | ETF | Ondo | 24/5 |
| iShares US Equity Factor Rotation Active ETF | `DYNFon` | ETF | Ondo | 24/5 |
| iShares US Industry Rotation Active ETF | `INROon` | ETF | Ondo | Market hours |
| iShares US Technology ETF | `IYWon` | ETF | Ondo | 24/5 |
| Jabil | `JBLon` | Company | Ondo | 24/5 |
| JD.com | `JDon` | Company | Ondo | 24/5 |
| Johnson & Johnson | `JNJon` | Company | Ondo | 24/5 |
| JPMorgan Chase | `JPMon` | Company | Ondo | 24/5 |
| Kanzhun | `BZon` | Company | Ondo | Market hours |
| Keel Infrastructure | `KEELon` | Company | Ondo | 24/5 |
| Keysight Technologies | `KEYSon` | Company | Ondo | 24/5 |
| KLA | `KLACon` | Company | Ondo | 24/5 |
| Kopin | `KOPNon` | Company | Ondo | Market hours |
| KraneShares CSI China Internet ETF | `KWEBon` | ETF | Ondo | 24/5 |
| Lam Research | `LRCXon` | Company | Ondo | Extended hours |
| Lattice Semiconductor | `LSCCon` | Company | Ondo | Pre-market and regular hours |
| Leonardo DRS | `DRSon` | Company | Ondo | Market hours |
| Li Auto | `LIon` | Company | Ondo | Regular hours and overnight |
| LightPath Technologies | `LPTHon` | Company | Ondo | Market hours |
| Lightwave Logic | `LWLGon` | Company | Ondo | Extended hours |
| Lincoln Electric | `LECOon` | Company | Ondo | Regular hours and post-market |
| Linde plc | `LINon` | Company | Ondo | 24/5 |
| Lockheed | `LMTon` | Company | Ondo | 24/5 |
| Lowe's | `LOWon` | Company | Ondo | Market hours |
| Lumentum Holdings | `LITEon` | Company | Ondo | 24/5 |
| MACOM Technology Solutions Holdings | `MTSIon` | Company | Ondo | 24/5 |
| MARA Holdings | `MARAon` | Company | Ondo | 24/5 |
| Marvell Technology | `MRVLon` | Company | Ondo | 24/7 |
| MasTec | `MTZon` | Company | Ondo | Market hours |
| Mastercard | `MAon` | Company | Ondo | 24/5 |
| MaxLinear | `MXLon` | Company | Ondo | 24/5 |
| McDonald's | `MCDon` | Company | Ondo | 24/5 |
| MercadoLibre | `MELIon` | Company | Ondo | 24/5 |
| Merck | `MRKon` | Company | Ondo | 24/5 |
| Meta Platforms | `METAon` | Company | Ondo | 24/7 |
| Methode Electronics | `MEIon` | Company | Ondo | Market hours |
| Micron Technology | `MUon` | Company | Ondo | 24/7 |
| Microsoft | `MSFTon` | Company | Ondo | 24/7 |
| MicroStrategy | `MSTRon` | Company | Ondo | 24/7 |
| MKS Inc. | `MKSIon` | Company | Ondo | Extended hours |
| Mobileye Global | `MBLYon` | Company | Ondo | Market hours |
| Moderna | `MRNAon` | Company | Ondo | Extended hours |
| MP Materials | `MPon` | Company | Ondo | 24/5 |
| MYR Group | `MYRGon` | Company | Ondo | Market hours |
| NANO Nuclear Energy | `NNEon` | Company | Ondo | Extended hours |
| Navitas Semiconductor | `NVTSon` | Company | Ondo | 24/5 |
| Nebius Group | `NBISon` | Company | Ondo | 24/5 |
| NetEase | `NTESon` | Company | Ondo | Market hours |
| Netflix | `NFLXon` | Company | Ondo | 24/5 |
| Newmont | `NEMon` | Company | Ondo | 24/5 |
| NextEra Energy | `NEEon` | Company | Ondo | Market hours |
| Nike | `NKEon` | Company | Ondo | 24/5 |
| NIO | `NIOon` | Company | Ondo | Extended hours |
| nLIGHT | `LASRon` | Company | Ondo | Extended hours |
| Nokia | `NOKon` | Company | Ondo | 24/5 |
| Nordic American Tankers | `NATon` | Company | Ondo | Market hours |
| Northrop Grumman | `NOCon` | Company | Ondo | 24/5 |
| Nova | `NVMIon` | Company | Ondo | Extended hours |
| Novo Nordisk | `NVOon` | Company | Ondo | 24/5 |
| Nucor | `NUEon` | Company | Ondo | Extended hours |
| NuScale Power | `SMRon` | Company | Ondo | 24/5 |
| nVent Electric | `NVTon` | Company | Ondo | Extended hours |
| NVIDIA | `NVDAon` | Company | Ondo | 24/7 |
| Occidental Petroleum | `OXYon` | Company | Ondo | Extended hours |
| Oceaneering International | `OIIon` | Company | Ondo | Market hours |
| Okeanis Eco Tankers | `ECOon` | Company | Ondo | Pre-market, regular hours, and overnight |
| Oklo | `OKLOon` | Company | Ondo | 24/5 |
| ON Semiconductor | `ONon` | Company | Ondo | Market hours |
| Ondas Holdings | `ONDSon` | Company | Ondo | Extended hours |
| Onto Innovation | `ONTOon` | Company | Ondo | Extended hours |
| Opendoor Technologies | `OPENon` | Company | Ondo | Market hours |
| Opera | `OPRAon` | Company | Ondo | Market hours |
| Oracle | `ORCLon` | Company | Ondo | 24/7 |
| Oscar Health | `OSCRon` | Company | Ondo | Market hours |
| Ouster | `OUSTon` | Company | Ondo | Extended hours |
| Palantir Technologies | `PLTRon` | Company | Ondo | 24/5 |
| Palo Alto Networks | `PANWon` | Company | Ondo | 24/5 |
| PayPal | `PYPLon` | Company | Ondo | 24/5 |
| PDD Holdings | `PDDon` | Company | Ondo | 24/5 |
| Penguin Solutions | `PENGon` | Company | Ondo | Market hours |
| PepsiCo | `PEPon` | Company | Ondo | 24/5 |
| Petrobras | `PBRon` | Company | Ondo | 24/5 |
| Pfizer | `PFEon` | Company | Ondo | 24/5 |
| PG\&E | `PCGon` | Company | Ondo | Market hours |
| Pinterest | `PINSon` | Company | Ondo | Extended hours |
| Planet Labs | `PLon` | Company | Ondo | 24/5 |
| Plug Power | `PLUGon` | Company | Ondo | Extended hours |
| Powell Industries | `POWLon` | Company | Ondo | Extended hours |
| Power Integrations | `POWIon` | Company | Ondo | Market hours |
| Primoris Services | `PRIMon` | Company | Ondo | Regular hours and post-market |
| Procter & Gamble | `PGon` | Company | Ondo | 24/5 |
| ProShares Short QQQ | `PSQon` | ETF | Ondo | 24/5 |
| ProShares UltraPro QQQ | `TQQQon` | ETF | Ondo | 24/7 |
| ProShares UltraPro Short QQQ | `SQQQon` | ETF | Ondo | Extended hours |
| Qualcomm | `QCOMon` | Company | Ondo | 24/5 |
| Quanta Services | `PWRon` | Company | Ondo | 24/5 |
| Quantum Computing | `QUBTon` | Company | Ondo | Regular hours and overnight |
| Rambus | `RMBSon` | Company | Ondo | 24/5 |
| REalloys | `ALOYon` | Company | Ondo | Market hours |
| Reddit | `RDDTon` | Company | Ondo | 24/5 |
| Redwire | `RDWon` | Company | Ondo | Regular hours, post-market, and overnight |
| Regeneron Pharmaceuticals | `REGNon` | Company | Ondo | 24/5 |
| Rigetti Computing | `RGTIon` | Company | Ondo | 24/5 |
| Riot Platforms | `RIOTon` | Company | Ondo | 24/5 |
| Rivian Automotive | `RIVNon` | Company | Ondo | 24/5 |
| Robinhood Markets | `HOODon` | Company | Ondo | 24/5 |
| RoboStrategy | `BOTon` | Company | Ondo | Market hours |
| Rocket Lab | `RKLBon` | Company | Ondo | 24/5 |
| Rockwell Automation | `ROKon` | Company | Ondo | Extended hours |
| Roundhill Memory ETF | `DRAMon` | ETF | Ondo | 24/7 |
| RTX | `RTXon` | Company | Ondo | Extended hours |
| S\&P Global | `SPGIon` | Company | Ondo | 24/5 |
| Salesforce | `CRMon` | Company | Ondo | 24/5 |
| SanDisk | `SNDKon` | Company | Ondo | 24/7 |
| SAP | `SAPon` | Company | Ondo | 24/5 |
| Scorpio Tankers | `STNGon` | Company | Ondo | Pre-market and regular hours |
| Seagate | `STXon` | Company | Ondo | 24/5 |
| ServiceNow | `NOWon` | Company | Ondo | 24/5 |
| SharpLink Gaming | `SBETon` | Company | Ondo | 24/5 |
| Shopify | `SHOPon` | Company | Ondo | 24/5 |
| SK Hynix | `SKHYon` | Company | Ondo | 24/7 |
| Skyworks Solutions | `SWKSon` | Company | Ondo | Extended hours |
| SLB | `SLBon` | Company | Ondo | Extended hours |
| Snap | `SNAPon` | Company | Ondo | Market hours |
| Snowflake | `SNOWon` | Company | Ondo | 24/5 |
| SoFi Technologies | `SOFIon` | Company | Ondo | 24/5 |
| SolarEdge Technologies | `SEDGon` | Company | Ondo | Market hours |
| SoundHound AI | `SOUNon` | Company | Ondo | 24/5 |
| Southern | `SOon` | Company | Ondo | Market hours |
| Southern Copper | `SCCOon` | Company | Ondo | 24/5 |
| SpaceX | `SPCXon` | Company | Ondo | 24/7 |
| SPDR S\&P 500 ETF | `SPYon` | ETF | Ondo | 24/7 |
| Spotify | `SPOTon` | Company | Ondo | 24/5 |
| Starbucks | `SBUXon` | Company | Ondo | 24/5 |
| Steel Dynamics | `STLDon` | Company | Ondo | Pre-market and regular hours |
| STMicroelectronics | `STMon` | Company | Ondo | 24/5 |
| Super Micro Computer | `SMCIon` | Company | Ondo | 24/5 |
| Symbotic | `SYMon` | Company | Ondo | 24/5 |
| T-Mobile US | `TMUSon` | Company | Ondo | Extended hours |
| Taiwan Semiconductor Manufacturing | `TSMon` | Company | Ondo | 24/7 |
| Talen Energy | `TLNon` | Company | Ondo | Market hours |
| TaskUs | `TASKon` | Company | Ondo | Market hours |
| TE Connectivity | `TELon` | Company | Ondo | Extended hours |
| Teekay Tankers | `TNKon` | Company | Ondo | Market hours |
| Teradyne | `TERon` | Company | Ondo | 24/5 |
| Terawulf | `WULFon` | Company | Ondo | Market hours |
| Tesla | `TSLAon` | Company | Ondo | 24/7 |
| Texas Instruments | `TXNon` | Company | Ondo | Extended hours |
| Thermo Fisher Scientific | `TMOon` | Company | Ondo | Extended hours |
| Tower Semiconductor | `TSEMon` | Company | Ondo | 24/5 |
| Toyota | `TMon` | Company | Ondo | 24/5 |
| Trane Technologies | `TTon` | Company | Ondo | 24/5 |
| Trip.com Group | `TCOMon` | Company | Ondo | Extended hours |
| Tsakos Energy Navigation | `TENon` | Company | Ondo | Regular hours and overnight |
| TTM Technologies | `TTMIon` | Company | Ondo | 24/5 |
| Uber | `UBERon` | Company | Ondo | 24/5 |
| Ultra Clean Holdings | `UCTTon` | Company | Ondo | Pre-market and regular hours |
| Union Pacific Corporation | `UNPon` | Company | Ondo | 24/5 |
| United Microelectronics | `UMCon` | Company | Ondo | Pre-market, regular hours, and overnight |
| United States Antimony | `UAMYon` | Company | Ondo | Extended hours |
| UnitedHealth | `UNHon` | Company | Ondo | 24/5 |
| Uranium Energy | `UECon` | Company | Ondo | Pre-market and regular hours |
| USA Rare Earth | `USARon` | Company | Ondo | 24/5 |
| VanEck Oil Services ETF | `OIHon` | ETF | Ondo | Extended hours |
| Vanguard Energy ETF | `VDEon` | ETF | Ondo | Extended hours |
| Vanguard Real Estate ETF | `VNQon` | ETF | Ondo | 24/5 |
| Vanguard Total Stock Market ETF | `VTIon` | ETF | Ondo | 24/5 |
| Vanguard Value ETF | `VTVon` | ETF | Ondo | Extended hours |
| VeriSign | `VRSNon` | Company | Ondo | Regular hours and post-market |
| Verizon | `VZon` | Company | Ondo | 24/5 |
| Vertex Pharmaceuticals | `VRTXon` | Company | Ondo | 24/5 |
| Vertiv | `VRTon` | Company | Ondo | 24/5 |
| Vicor | `VICRon` | Company | Ondo | Extended hours |
| VinFast Auto | `VFSon` | Company | Ondo | Market hours |
| Visa | `Von` | Company | Ondo | 24/5 |
| Vishay Intertechnology | `VSHon` | Company | Ondo | Pre-market and regular hours |
| Vishay Precision Group | `VPGon` | Company | Ondo | Pre-market and regular hours |
| Vistra | `VSTon` | Company | Ondo | Extended hours |
| Walmart | `WMTon` | Company | Ondo | 24/5 |
| Waste Management | `WMon` | Company | Ondo | Regular hours, post-market, and overnight |
| Wells Fargo | `WFCon` | Company | Ondo | 24/5 |
| WESCO International | `WCCon` | Company | Ondo | Regular hours and post-market |
| Western Digital | `WDCon` | Company | Ondo | 24/5 |
| Westlake | `WLKon` | Company | Ondo | Pre-market and regular hours |
| WhiteFiber | `WYFIon` | Company | Ondo | Pre-market and regular hours |
| Williams | `WMBon` | Company | Ondo | Pre-market and regular hours |
| WisdomTree US Quality Dividend Growth Fund | `DGRWon` | Fund | Ondo | Market hours |
| Wolfspeed | `WOLFon` | Company | Ondo | 24/5 |
| Worthington Steel | `WSon` | Company | Ondo | Market hours |

> **[Next: Fixed income](/assets/fixed-income)**
>
> Tokenized treasuries, credit, and other yield-bearing assets.


# Fixed income
Source: https://docs.passage.coinlist.co/assets/fixed-income

Every tokenized treasury, bond, and credit product in the Passage catalog, with ticker and issuer.

Fixed income covers assets that pay a return over time, from US Treasuries through corporate
credit and securitized products. See [Asset catalog](/assets/catalog) for a primer on the
asset class, and [Asset issuers](/assets/partners) for what ownership of an Ondo token
actually means.

> [!NOTE]
>
> The catalog below reflects Ondo's published assets as of July 22, 2026. For current
> availability, retrieve the [latest catalog](https://github.com/ondoprotocol/ondo-global-markets-token-list)
> at runtime.
>
> The **Trading window** column shows when users can buy and sell each asset, as of
> October 22, 2026. See [Trading windows](/assets/catalog#trading-windows) for what each one
> means, and [status.ondo.finance/market](https://status.ondo.finance/market) for live status.

## Assets

30 tokenized fixed income and yield-bearing assets.

The type column describes the instrument itself: **Company** for shares in a single company, **ETF**, **Fund**, or **Trust** for pooled vehicles that hold a basket on your behalf, and **Preferred** for preferred shares.

| Asset | Ticker | Type | Issued by | Trading window |
| - | - | - | - | - |
| AB Ultra Short Income ETF | `YEARon` | ETF | Ondo | Pre-market and regular hours |
| Franklin High Yield Corporate ETF | `FLHYon` | ETF | Ondo | Market hours |
| iBoxx \$ High Yield Corporate Bond ETF | `HYGon` | ETF | Ondo | 24/5 |
| iShares 0-3 Month Treasury Bond ETF | `SGOVon` | ETF | Ondo | 24/5 |
| iShares 1-3 Year Treasury Bond ETF | `SHYon` | ETF | Ondo | 24/5 |
| iShares 20+ Year Treasury Bond ETF | `TLTon` | ETF | Ondo | 24/5 |
| iShares 3-7 Year Treasury Bond ETF | `IEIon` | ETF | Ondo | 24/5 |
| iShares 7-10 Year Treasury Bond ETF | `IEFon` | ETF | Ondo | 24/5 |
| iShares Aaa - A Rated Corporate Bond ETF | `QLTAon` | ETF | Ondo | Pre-market and regular hours |
| iShares AAA CLO Active ETF | `CLOAon` | ETF | Ondo | Market hours |
| iShares Core US Aggregate Bond ETF | `AGGon` | ETF | Ondo | 24/5 |
| iShares Euro High Yield Corporate Bond USD Hedged ETF | `EUHYon` | ETF | Ondo | Pre-market and regular hours |
| iShares Flexible Income Active ETF | `BINCon` | ETF | Ondo | Extended hours |
| iShares Floating Rate Loan Active ETF | `BRLNon` | ETF | Ondo | Extended hours |
| iShares Global Government Bond USD Hedged Active ETF | `GGOVon` | ETF | Ondo | Pre-market and regular hours |
| iShares High Yield Active ETF | `BRHYon` | ETF | Ondo | Pre-market, regular hours, and overnight |
| iShares High Yield Corporate Bond BuyWrite Strategy ETF | `HYGWon` | ETF | Ondo | Market hours |
| iShares Investment Grade Systematic Bond ETF | `IGEBon` | ETF | Ondo | Pre-market and regular hours |
| iShares J.P. Morgan EM Local Currency Bond ETF | `LEMBon` | ETF | Ondo | Market hours |
| iShares Securitized Income Active ETF | `SECUon` | ETF | Ondo | Market hours |
| iShares Systematic Bond ETF | `SYSBon` | ETF | Ondo | Market hours |
| iShares TIPS Bond ETF | `TIPon` | ETF | Ondo | 24/5 |
| iShares Total Return Active ETF | `BRTRon` | ETF | Ondo | Pre-market and regular hours |
| Janus Henderson AAA CLO ETF | `JAAAon` | ETF | Ondo | Extended hours |
| PIMCO 0-5 Year High Yield Corporate Bond Index ETF | `HYSon` | ETF | Ondo | 24/5 |
| SPDR Bloomberg 1-3 Month T-Bill ETF | `BILon` | ETF | Ondo | 24/5 |
| Strategy Stretch Preferred | `STRCon` | Preferred | Ondo | 24/7 |
| Strive Preferred | `SATAon` | Preferred | Ondo | Extended hours |
| VanEck CLO ETF | `CLOIon` | ETF | Ondo | Market hours |
| WisdomTree Floating Rate Treasury Fund | `USFRon` | Fund | Ondo | 24/5 |

> **[Next: Commodities](/assets/commodities)**
>
> Tokenized metals, energy, and broad commodity exposure.


# Asset issuers
Source: https://docs.passage.coinlist.co/assets/partners

What a token represents and what your users can do with it, issuer by issuer.

What a token actually represents, and what your users can do with it after they buy, both depend on who issued it. Two tokens tracking the same stock can carry meaningfully different rights depending on which platform issued them, so each issuer has its own page covering its ownership model alongside the lifecycle of its assets.

## Issuer profiles at a glance

| Issuer | What they issue | Ownership model | Powers which use cases |
| - | - | - | - |
| [Superstate](/assets/partners/superstate) | Tokenized US equities (Opening Bell) | Direct ownership of the underlying equity | Tokenized stocks, permissioned lending/borrowing pools |
| [Ondo](/assets/partners/ondo) | 400+ assets: equities, fixed income, commodities | Wrapped economic exposure | Tokenized stocks, yield, commodities |
| [CoinList](/assets/partners/coinlist) | Token sales | Direct token allocation / ownership | Early stage crypto exposure |
| Centrifuge (coming soon) | Tokenized funds from established managers including Janus Henderson and Apollo | Wrapped economic exposure | Yield, tokenized funds, DeFi collateral |
| WisdomTree (coming soon) | US Treasury funds, index funds, and mutual funds | Direct ownership of the underlying funds | Yield, tokenized funds |

> **[Superstate](/assets/partners/superstate)**
>
> Direct ownership

> **[Ondo](/assets/partners/ondo)**
>
> Wrapped exposure

> **[CoinList](/assets/partners/coinlist)**
>
> Token sales

> **[Next: Wallet partners](/wallet-partners)**
>
> The other half of the partner story: who supplies the wallets your users sign with.


# CoinList
Source: https://docs.passage.coinlist.co/assets/partners/coinlist

Token sales run by CoinList, embedded inside your app, with direct token allocation on each sale's terms.

CoinList is the token sale partner. Where the other partners issue assets that trade continuously, CoinList offers run as discrete sales with their own window, terms, and eligibility.

## What it is

Token sales. Passage embeds sales that CoinList already runs inside your app, so your users get access to new token offerings without leaving it.

> [!NOTE]
>
> This is for surfacing sales CoinList already runs. If you are raising for your own token, see [Run your raise](/use-cases/run-your-raise).

## Ownership model

Direct token allocation on the terms of each sale. Your users receive an allocation of the token itself, not a wrapper or a claim on an underlying security. Allocation follows whatever schedule the sale defines.

## How users buy

Users contribute during the sale window, with eligibility set per sale rather than once across the catalog. A user who qualified for one offering will not necessarily qualify for the next.

The contribution settles later on Passage's own schedule rather than in the same transaction, which is the main way this differs from the instant swaps used by [Superstate](/assets/partners/superstate) and [Ondo](/assets/partners/ondo). Offers carry a `type` field, and CoinList sales arrive as `coinlist::token_sale`. [`CheckoutContainer`](/sdk/checkout) routes on that and renders the SDK's own token-sale checkout: wallet, amount paid in a stablecoin the sale accepts, and review. `ClaimContainer` lists the user's participations in the sale and where each one stands.

## What users can do with it

Receive distributions on the sale's configured schedule, including any vesting or lockups that apply. Sell the tokens through DeFi or exchanges. Stake the tokens on the network, where applicable.

CoinList powers [token sales](/use-cases/token-sales).

## Build it

> **[CoinList Token Sale](/sdk/invest-flow)**
>
> Approve funds and record a participation with `passage.tokenSale.execute`.

> **[Track participations](/sdk/invest-flow#track-participations)**
>
> Read and create participations for a sale.


# Ondo
Source: https://docs.passage.coinlist.co/assets/partners/ondo

A broad catalog of 400+ tokenized assets across equities, fixed income, and commodities. Ondo assets are only available to non-US investors.

Ondo adds assets regularly, so treat the [Ondo token list](https://github.com/ondoprotocol/ondo-global-markets-token-list) as the source of truth rather than a fixed roster.

## What it is

A broad catalog of 400+ assets, spanning [equities](/assets/equities), [fixed income](/assets/fixed-income), and [commodities](/assets/commodities). That covers single-company shares, index and sector funds, Treasuries and corporate credit, and physical metals and energy.

Assets are issued as wrapped economic exposure. The asset holder has economic exposure to the underlying asset, but does not own the asset outright. The issuing entity owns the underlying asset and issues a claim against it to the investor.

## Ownership model

Wrapped exposure. The token tracks the value of the underlying asset but confers fewer rights than direct share ownership.

Practically, that means your users get the price exposure without the shareholder rights that come with a directly owned share. Where those rights matter to your users, [Superstate](/assets/partners/superstate) is a better partner.

## How users buy

Tokens are minted directly from the issuer through an RFQ purchase flow. The user places an order and confirms the price before the purchase processes. Tokens and stablecoins settle in a single transaction.

Unlike Superstate assets, Ondo assets are not allowlist-gated, so there is no wallet registration step before the purchase.

## What users can do with it

Buy, sell, and hold it for exposure, and earn yield where the product accrues it.

Ondo powers [tokenized stocks and funds](/use-cases/tokenized-assets), yield, and commodities.

## FAQ

> **What does my user actually own?**
>
> Economic exposure, not title in the underlying asset. Ondo tokenized equities are backed 1:1 by securities at licensed US broker-dealers, issued by Ondo Global Markets (BVI) Limited through a bankruptcy-remote SPV with an independent director, overcollateralization, a third-party security agent, and daily attestations.

> **Does one token equal one share?**
>
> Not always. Ondo stocks are total-return trackers, which means dividends are reinvested net of withholding taxes. The price typically matches the price of the stock exactly on the day Ondo issues it, but over time, as dividends are reinvested, the price drifts to represent more than one share and stops tracking the stock.
>
> This matters for how you communicate price to users. Do not use traditional market data for the stock. Use the official pricing from Ondo, or a provider such as CoinGecko. Scaled UI makes this look share-like on Solana and BNB Chain, but not on Ethereum.

> **Do my users need to conduct KYC with Ondo directly?**
>
> No. Individual users do not need to complete KYC with Ondo.
>
> Compliance obligations differ based on your business model and structure. DEXs and self-custodial swaps may not require direct KYC on their users to transact in Ondo tokens. Other businesses may be obligated to perform KYC, which Passage supports.
>
> In all cases you are obligated to perform certain compliance functions and apply geographic restrictions, which Passage will help you support. Contact your Passage representative about the compliance model appropriate for your business.

> **Which jurisdictions?**
>
> Ondo tokens are not available in the following jurisdictions: Afghanistan, Belarus, Crimea, Cuba, Donetsk People's Republic (DNR) Ukraine, Luhansk People's Republic (LNR) Ukraine, Kherson region Ukraine, Zaporizhzhia region Ukraine, Iran, Libya, Myanmar, North Korea (DPRK), Russia, Sevastopol Ukraine, Somalia, South Sudan, Sudan, Syria, United States (including states, territories, possessions, and federal districts), and Canada.
>
> There may be additional restrictions for specific tokens. Each offering outlines its full restricted list.

> **How does a user buy?**
>
> Tokens are available through an RFQ purchase flow. Users place an order and then confirm the price before the purchase processes. Purchases can only be made in USDC.
>
> Tokens are generally minted directly via Ondo, available instantly and atomically. Tokens and stablecoins settle in a single transaction. Fractional tokens are supported.
>
> Because it is an RFQ system connected directly to Ondo Global Markets, it generally provides good pricing up to the individual token limits offered via the RFQ.

> **What are the market hours?**
>
> Hours depend on the asset. On weekdays, Ondo follows the sessions of the US market from Sunday evening to Friday evening, US Eastern time: pre-market, regular hours, post-market, and overnight. About half of Ondo's assets trade in all four sessions, close to 24 hours a day, 5 days a week. The rest trade in fewer sessions, and some only during regular US market hours.
>
> A smaller set also trades over weekends and US market holidays, in Ondo's Off-Hours session. Users can buy and sell these assets through Passage whenever that session is open. They include NVIDIA (`NVDAon`), Tesla (`TSLAon`), Apple (`AAPLon`), and the S\&P 500 (`SPYon`). The **Trading window** column of [Equities](/assets/equities), [Fixed income](/assets/fixed-income), and [Commodities](/assets/commodities) shows each asset's hours and marks these as 24/7. See [Trading windows](/assets/catalog#trading-windows) for the full schedule.
>
> Liquidity is lower outside regular hours, especially on weekends. Spreads can be wider and the largest order smaller. A weekend asset can also pause for a while if it reaches its Off-Hours limit, until trading frees the limit up. Users should check the price quoted by the RFQ before they buy or sell.
>
> Trading pauses for a few minutes between sessions, during corporate actions on a ticker, and if risk limits trip. Live status for each asset, including the current weekend list, is at [status.ondo.finance/market](https://status.ondo.finance/market).

> **Are there order maximums or minimums?**
>
> Each asset has different order sizing limits, visible in the offer details. The minimum is \$1.

> **Can a user sell?**
>
> Yes. The selling flow is identical to the purchase flow: an atomic burn redeeming to USDC.

> **Dividends?**
>
> Dividends are auto-reinvested net of withholding taxes, reflected as an increasing token balance on Solana (support coming soon) and as tracker value on Ethereum. There is no cash distribution.

> **Voting rights?**
>
> Ondo token holders do not own the underlying stock, so they are not entitled to voting rights. Proxy voting may be available where Ondo enables it.

> **Are the tokens transferable?**
>
> Yes, peer-to-peer and into DeFi protocols across Ethereum, BNB Chain, and Solana, and bridgeable to HyperEVM. There is no allowlisting on Ondo tokens.

> **Can these assets be used in DeFi?**
>
> Yes, widely. Certain Ondo tokens may be used as collateral in lending, or for perps on Ondo's perp platform. AMM pools also exist, but liquidity is often very thin. Passage's Ondo swaps tend to have much better pricing at larger sizes.

> **Do my users get tax documents?**
>
> No. Your users will not get tax documents from Passage or Ondo related to purchases and sales of Ondo tokens, dividends, or any other corporate actions.

> **Why would a transaction fail?**
>
> The usual cause is timing. Each asset trades only in its own sessions, and trading pauses between sessions, during corporate actions on a given ticker, and if risk limits trip. A weekend asset also pauses when it reaches its Off-Hours limit. Live status is published at [status.ondo.finance/market](https://status.ondo.finance/market). Transfers are unaffected by any of this and keep working when mint and redeem are paused.
>
> Mint and redeem also require completed onboarding. Holding tokens does not make someone eligible to redeem, so a user who picked up tokens on a secondary market and never onboarded has no redemption path. Their only options are to keep holding or to sell on a secondary market where permitted.

> **What if I end the integration?**
>
> Users keep and control their tokens.

## Build it

> **[Ondo Swap](/sdk/ondo-swap)**
>
> The buy and sell paths used by Ondo assets.

> **[Asset catalog](/assets/catalog)**
>
> Every asset Ondo issues, by asset class, with ticker and type.


# Superstate
Source: https://docs.passage.coinlist.co/assets/partners/superstate

Tokenized US equities through Opening Bell. Each token represents direct ownership of the underlying share.

Companies sell stock to individuals directly through Opening Bell, typically at a discount, or through IPOs. Each token represents direct ownership of the underlying share.

## What it is

Users purchase shares directly from the company, for example Tesla or NVIDIA, often at a discount to the currently traded price. Your users hold an asset issued by the company directly, tokenized through Superstate. Superstate acts as the transfer agent and records the ownership both offchain and onchain.

Superstate tokenized assets are direct ownership with full rights, not a wrapper or indirect economic exposure only.

## Ownership model

Direct ownership. The token represents real ownership of the underlying share, so holding the token means owning the equity itself. Owners receive dividends directly and can vote their shares, and ownership is recorded in the name of the investor.

This distinction may matter to your users. A Superstate token and an [Ondo](/assets/partners/ondo) token can track the same stock and still carry meaningfully different rights. Superstate equities are typically available to U.S. individuals, whereas Ondo equities are not.

## How users buy

Direct issuance, minting from the issuer. The user pays a stablecoin and receives the tokenized share in the same transaction, with no separate settlement step.

Superstate assets are allowlisted, so a user's wallet has to be registered against the offer before a swap or transfer can settle. This allowlisting is how ownership is recorded offchain. Passage provides all the transactions and flows for allowlist registration end to end, including proving the user controls the wallet and broadcasting the allowlist transaction where the contract requires one.

## What users can do with it

Hold it, or use it in permissioned DeFi. The allowlists that gate Superstate assets are the same ones that make permissioned Uniswap pools and RWA lending markets available to your users, so these assets are not just static positions sitting in a wallet.

Tokenized stock can also be redeemed directly for shares offline via Superstate.

If your users want to send or transfer their shares after purchase, they will need to allowlist each new wallet. Allowlisting is once per wallet per offer, so a wallet cleared for one offer is not automatically cleared for another, and any transaction to a non-allowlisted wallet will fail.

Superstate powers [tokenized stocks](/use-cases/tokenized-assets) and [permissioned DeFi pools](/use-cases/permissioned-defi-pools).

## FAQ

> **What does my user actually own?**
>
> Real shares. Superstate is the SEC-registered transfer agent and records legal ownership onchain as tokens move. No wrappers, derivatives, or a separate share class.

> **Who is the issuer of record?**
>
> The public company itself. Superstate is the transfer agent maintaining the registry across book-entry, tokenized, and DeFi-protocol holdings.

> **Do my users need a separate Superstate account?**
>
> No, only a CoinList account. Passage KYC satisfies the requirement.
>
> To redeem for ordinary shares offchain, the user will need to complete that process with Superstate.

> **What is the allowlist requirement?**
>
> A wallet must be allowlisted before it can hold tokenized shares, and supported networks vary by equity. Adding a wallet to the allowlist requires the user to complete KYC and some additional requirements, then sign a transaction onchain.
>
> Allowlisting is once per wallet per offer, so a wallet cleared for one offer is not automatically cleared for another. It can be completed as part of the purchase process, or independently per wallet for transfers. See [Allowlist a wallet](/sdk/swap-flow#step-3-allowlist-the-wallet).

> **Which jurisdictions?**
>
> Different assets and offerings may have different eligibility requirements. In general, Superstate assets are available in most geographies including the U.S. OFAC-sanctioned countries are always restricted. Check the specific offering requirements for eligibility restrictions.

> **How does a user buy?**
>
> Direct issuance, minting from the issuer.

> **Is there a minimum?**
>
> Minimums are set by each issuing company and may differ from offer to offer. Minimums apply to direct issuance only. Secondary purchases on a supported DEX have no issuer-imposed floor.

> **Can a user sell?**
>
> Yes, tokens can be sold via permissioned DeFi pools such as those offered by Uniswap. As of today, there are no live pools.
>
> Users can also convert the token into traditional equity via Superstate.

> **Are there lock-ups?**
>
> No.

> **Dividends and distributions?**
>
> Real dividends, paid out to the holder rather than reinvested. There are two routes, and the issuing company picks which one applies, so it can differ by asset.
>
> * **Onchain:** paid in USDC or another crypto asset, using the wallet information Superstate collects from investors.
> * **Fiat:** the dividend is paid out in cash. Superstate coordinates with the company's existing transfer agent to make that happen.

> **Can it be transferred out?**
>
> Yes, between allowlisted wallets, with restrictions enforced at the token level. Transactions or transfers between non-allowlisted wallets will fail onchain.
>
> We recommend adding a check to the onchain allowlist before allowing a user to transfer tokens. You can allowlist additional wallets through Passage for users without a purchase transaction. See [Allowlist a wallet](/sdk/swap-flow#step-3-allowlist-the-wallet).
>
> Users can also burn to book-entry and DRS-transfer to a traditional brokerage, which takes 2 to 3 business days.

> **Do my users get tax documents?**
>
> Yes, if relevant to their holding period. Holders of Superstate tokenized equities directly own the underlying asset and receive dividends directly. The dividends are taxable, and tax documents are provided directly to the investor from Superstate, via the email associated with their Passage account.
>
> As part of onboarding to the allowlist, the user is required to submit tax documentation through Passage. For U.S. investors, this information is collected automatically as part of KYC. Non-U.S. investors are required to complete a W-8 form.

> **Can these assets be used in DeFi?**
>
> Yes, but each pool needs to be specially configured because of the allowlist. Kamino pools exist on Solana and Aave pools exist on Ethereum.
>
> No permissioned Uniswap pools are live today.

> **Why would a transaction fail?**
>
> Most commonly the wallet is not allowlisted for that offer. Allowlisting is per wallet per offer, so a wallet cleared for one Superstate offer is not automatically cleared for another. Transfers also require the receiving wallet to be allowlisted, so sending to an unverified address will fail. Restrictions are enforced at the token level, meaning the transaction reverts onchain rather than being blocked beforehand.
>
> On the sell side, a swap can fail because no DEX pool is live for that asset, or because the pool is too thin for the size. For direct issuance, purchases below an issuer's minimum will be rejected, and offerings can close once the size is reached.

> **What if I end the integration?**
>
> Users keep the tokens in their own wallet and can hold or liquidate independently.

## Build it

> **[Allowlist a wallet](/sdk/swap-flow#step-3-allowlist-the-wallet)**
>
> Register a user's wallet against the offer with `authorizeWallet` before they buy.

> **[Superstate Swap](/sdk/swap-flow)**
>
> The purchase path used by Superstate assets.


# React SDK changelog
Source: https://docs.passage.coinlist.co/changelogs/react

Release history for @passage-cl/react, formerly @coinlist-co/react

> [!NOTE]
>
> This changelog covers the [`@passage-cl/react`](https://www.npmjs.com/package/@passage-cl/react) SDK. Up to v0.12.1 it was published as [`@coinlist-co/react`](https://www.npmjs.com/package/@coinlist-co/react).

**v0.14.0**

October 21, 2026 - The Centrifuge sell checkout, on-chain Centrifuge claims, and the coinlist\_account requirement

This release completes the Centrifuge vault journey. `CheckoutContainer` now mounts a redemption checkout for `side="sell"`, and the SDK encodes claims on-chain itself instead of asking the API for calldata. The vault status reports each direction separately, and the API's refusals arrive as typed reasons. The requirements checklist knows the new `coinlist_account` requirement.

> [!NOTE]
>
> Centrifuge is `@alpha`, outside the compatibility contract, so its breaking changes ship in a minor release. Nothing outside the Centrifuge types breaks.

### Breaking Changes

#### Centrifuge claims are encoded by the SDK

`passage.centrifuge.createClaim` and `passage.centrifuge.createClaimProceeds` are removed, with `CentrifugeVaultClaimTransaction` and `CentrifugeVaultClaimProceedsTransaction`. Their endpoints, `POST /v1/centrifuge/vault/claim` and `/claim-proceeds`, do not exist on the API. A claim is the vault proxy's own unauthenticated call, so `passage.centrifuge.claim` now calls the proxy's `deposit` or `redeem` from the wallet with the maximum amount, which claims everything claimable. No API request and no approval come first.

| Before | After |
| - | - |
| `ClaimCentrifugeVaultParams` `{ wallet, chain, symbol, direction }` | `{ wallet, vault, direction }`, where `vault` is a `CentrifugeVault` |
| `CentrifugeClaimPhase` `'preparing' \| 'awaiting-wallet' \| 'confirming'` | `'awaiting-wallet' \| 'confirming'` |
| `CentrifugeClaimStepUi` `'preparing' \| 'awaiting-wallet' \| 'confirming'` | `'awaiting-wallet' \| 'confirming'` |
| `CentrifugeClaimError` `{ step: 'prepare', reason: 'nothing-to-claim' \| 'frozen' \| 'generic' }` | `{ step: 'nothing-to-claim' }`. `frozen` and `generic` are gone |
| `CentrifugeClaimResult.claimed: BlockchainAmount` | `settlement: CentrifugeClaimSettlement \| null` |
| `CentrifugeVaultClaimed.claimed` (the `onClaimed` payload) | `settlement: CentrifugeClaimSettlement \| null` |
| `CentrifugeClaimFailureUi` includes `'wallet-frozen'` | Removed |
| `CentrifugeClaimDialogUi.amount` | `estimate` |

`CentrifugeClaimSettlement` is `{ assets, shares }`, read from the `Deposited` or `Redeemed` event in the receipt. It is `null` only when the receipt cannot be decoded.

**Migration:**

```ts theme={null}
// Before
const result = await passage.centrifuge.claim({ wallet, chain, symbol, direction: "deposit" });
if (result.type === "success") console.log(result.claimed);

// After
const result = await passage.centrifuge.claim({ wallet, vault, direction: "deposit" });
if (result.type === "success") console.log(result.settlement?.shares);
```

#### Centrifuge vault status reports each direction

`CentrifugeVaultStatus` is now `{ chain, symbol, deposit, redeem, asOf }`. `deposit` and `redeem` are each a `CentrifugeDirectionState`: `'active'`, `'paused'` (it can come back) or `'stopped'` (permanent for that proxy on that chain).

| Removed | Use instead |
| - | - |
| `vaultAddress`, `linked`, `permissioned`, `membershipValidUntil`, `halted`, `priceUpdatedAt` | Nothing. The API no longer reports them |
| `orderability`, `CentrifugeOrderability`, `CentrifugeOrderReason`, `CentrifugeVaultReason` | `status.deposit` or `status.redeem` |

**Migration:**

```ts theme={null}
// Before
const canBuy = status.orderability.type === "orderable";

// After
const canBuy = status.deposit === "active";
const canSell = status.redeem === "active";
```

#### Centrifuge checkout and claim types

| Before | After |
| - | - |
| `CentrifugeBuyReviewUiState`, with `investAmount` | `CentrifugeReviewUiState`, with `amount` |
| `CentrifugeBuyReviewUiEvent` | `CentrifugeReviewUiEvent` |
| `CentrifugeOrderPlaced` `{ wallet, amount, transaction, txHash }` | `CentrifugeBuyOrderPlaced \| CentrifugeSellOrderPlaced`. Each has `side` and its own `transaction` |
| `useCentrifugeBuyCheckoutViewModel` `onOrderPlaced(order: CentrifugeOrderPlaced)` | `onOrderPlaced(order: CentrifugeBuyOrderPlaced)` |
| `CentrifugeOrderPlacedUiState` visible `outputAsset`, `totalCost` | `asset`, `amount`, `claims` |
| `CentrifugeClaimActionUi` `{ type: 'blocked', reason }`, `CentrifugeClaimBlockedReasonUi` | Removed. Nothing about the vault blocks a claim |

**Migration:** a `config["centrifuge::vault"].onOrderPlaced` handler now runs for both directions. Read `order.side` before `order.transaction`.

```ts theme={null}
onOrderPlaced: (order) => {
  if (order.side === "buy") track("deposit", order.txHash);
  else track("redemption", order.txHash);
},
```

### Added

#### Centrifuge sell checkout

`<CheckoutContainer side="sell">` for a `centrifuge::vault` offer now mounts a redemption checkout. Before, it rendered an empty container.

* The steps are wallet, amount and review. A preselected wallet skips the wallet step, as on the buy side.
* The amount is a number of the vault's share tokens, bounded by the wallet's balance. The offer's dollar minimum applies to deposits only.
* Placing the order approves the vault proxy for the shares when the allowance is short, builds the request and broadcasts it. A redemption pays nothing yet: the fund fulfils it later, and the user claims the USDC in `ClaimContainer`.
* The checkout blocks with "Redeeming is paused right now" when the vault's `redeem` direction is paused or stopped.
* `config["centrifuge::vault"].onOrderPlaced` fires after the redemption request mines, with `order.side === "sell"`.
* To build your own UI, use `useCentrifugeSellCheckoutViewModel` (`@alpha`) with `CentrifugeSellCheckoutUiState` and `CentrifugeSellCheckoutUiEvent`.

| Method | Endpoint |
| - | - |
| `buildRedeemTransaction({ symbol, chain, walletAddress, amount })` | `POST /v1/centrifuge/vault/sell` |
| `prepareSell`, `sell` (browser only) | Approve the share token, then the endpoint above, through the wallet |

`passage.centrifuge.placeRequest` now broadcasts either a buy or a redeem transaction.

#### Typed Centrifuge refusals

When the API refuses to build a Centrifuge request, `prepareBuy`, `prepareSell`, `buy` and `sell` return `{ step: 'build-refused', reason }` instead of `build-transaction`. `reason` is a `CentrifugeRequestRefusal`: `'requirements-not-met'`, `'insufficient-balance'`, `'direction-paused'`, `'direction-stopped'`, `'vault-refused'` or `'no-proxy-on-chain'`. The checkout shows its own message for each. See [Errors](/sdk/errors).

`ApproveThenBuildError` and `ApproveThenBuildResult` take this reason as an optional type parameter that defaults to `never`, so the Ondo error types are unchanged.

#### Claim estimates

Each claimable row and the claim dialog show a `~` estimate of what the claim pays, at the vault's spot price. After the claim mines, the dialog shows the exact amount from the receipt. `CentrifugeDepositPosition` gains `estimatedShares`, `CentrifugeRedeemPosition` gains `estimatedAssets`, and `CentrifugeClaimRowUi` gains `estimate`.

#### `coinlist_account` requirement

`RequirementType` gains `'coinlist_account'`. The checklist shows it as "CoinList Account", "Sign in with a CoinList account." The user meets it by signing in, so its action opens no page. Code with an exhaustive `switch` over `RequirementType` needs the case. See [Requirements](/sdk/requirements).

### Changed

* **The Centrifuge buy checkout** blocks only when the vault's `deposit` direction is paused or stopped. Before, it also blocked on an unlinked, halted or unpermissioned vault, or a stale price.
* **The Centrifuge claim card** no longer polls the vault status. Each row leads with what the claim pays, in that token's icon, and the claim dialog is titled with it ("Claiming \~964.12 deJTRSY").
* **The Centrifuge order-placed dialog** shows the amount invested or redeemed, the receiving wallet, and a notice to claim once the order is processed.

### Fixed

* Centrifuge claims work. Before, both claim directions failed with a `404`.
* A Centrifuge request whose signature went stale, because it expired or a claim moved the wallet's nonce, now reports `request-expired`, so placing it again builds a fresh one.

**v0.13.0**

October 19, 2026 - The SDK moves to @passage-cl/react, a smaller public API, the token-sale and Centrifuge checkouts, ClaimContainer, and session expiry handling

> [!WARNING]
>
> **The SDK has moved to a new package: `@passage-cl/react`.** v0.13.0 and every later version are published only under the new name. `@coinlist-co/react` stops at v0.12.1, gets no further updates, and will be deprecated on npm. To upgrade, uninstall the old package, install the new one and update every import path.
>
> ```bash theme={null}
> npm uninstall @coinlist-co/react
> npm install @passage-cl/react
> ```
>
> | Before | After |
> | - | - |
> | `@coinlist-co/react` | `@passage-cl/react` |
> | `@coinlist-co/react/universal` | `@passage-cl/react/universal` |
> | `@coinlist-co/react/server` | `@passage-cl/react/server` |

This release renames the SDK to Passage, in its package name and in its exported names. There are no deprecated aliases, so every app has to migrate. It also shrinks the public API to root Containers, their viewmodels, data hooks and namespaces, and the package now ships as ESM only. `CheckoutContainer` takes `side` as a prop and needs no `config`. It mounts the SDK's own CoinList token-sale checkout and a Centrifuge vault checkout, and honors a preselected wallet in every flow. The new `ClaimContainer` shows the second leg of an asynchronous offer. Session renewal is single-flight, and the new `onSessionExpired` tells you when a session ends.

### Breaking Changes

#### The package is now `@passage-cl/react`

The SDK is published as [`@passage-cl/react`](https://www.npmjs.com/package/@passage-cl/react). The `/universal` and `/server` entry points keep their subpaths. See the install commands and the table above.

**Migration:** replace `@coinlist-co/react` with `@passage-cl/react` in `package.json` and in every import, then apply the renames below.

#### Exported names are rebranded to Passage

Every export that named the SDK after CoinList is renamed. The old names are gone.

| Entry point | Before | After |
| - | - | - |
| `.` | `CoinListProvider`, `CoinListProviderProps` | `PassageProvider`, `PassageProviderProps` |
| `.` | `useCoinList()`, `UseCoinListResult` | `usePassage()`, `UsePassageResult` |
| `.` | `useCoinList().coinlist` | `usePassage().passage` |
| `.` | `CoinListClient`, `createCoinListClient` | `PassageClient`, `createPassageClient` |
| `.` | `CoinListClientInitializationError` | `PassageClientInitializationError` |
| `.` | `CoinListStyleScope`, `CoinListStyleScopeProps` | `PassageStyleScope`, `PassageStyleScopeProps` |
| `.` | `CoinListContextProvider` | `PassageProvider` (the alias is merged into the provider) |
| `.` | `CoinListContext`, `CoinListContextValue` | No longer exported. Read the client with `usePassage()` |
| `./server` | `CoinListServer`, `createCoinListServer` | `PassageServer`, `createPassageServer` |

The field on the hook result is renamed too: `const { coinlist } = useCoinList()` becomes `const { passage } = usePassage()`. The members of the client and server are unchanged, so `coinlist.offers.list()` becomes `passage.offers.list()`. The provider-missing error now reads `usePassage() must be used within PassageProvider. Wrap your app with <PassageProvider config={...}>.`

Names that mean CoinList the company keep the CoinList name. These include `CoinListSignInButton`, `CoinListSignInCardContainer`, the `CoinListTokenSale*` checkout and participation names, `passage.tokenSale`, the `coinlist::*` offer types, `ClientConfig.coinlistBaseUrl`, and the `coinlist.*` browser storage keys.

**Migration:** a find-and-replace over your source, in this order:

```text theme={null}
@coinlist-co/react           -> @passage-cl/react
createCoinListClient         -> createPassageClient
createCoinListServer         -> createPassageServer
CoinListClientInitializationError -> PassageClientInitializationError
CoinListClient               -> PassageClient
CoinListServer               -> PassageServer
CoinListProvider             -> PassageProvider
UseCoinListResult            -> UsePassageResult
useCoinList                  -> usePassage
CoinListStyleScope           -> PassageStyleScope
```

Then rename the destructured `coinlist` field of `usePassage()` to `passage`.

```tsx theme={null}
// Before
import { CoinListProvider, useCoinList } from "@coinlist-co/react";
const { coinlist } = useCoinList();
await coinlist.offers.list();

// After
import { PassageProvider, usePassage } from "@passage-cl/react";
const { passage } = usePassage();
await passage.offers.list();
```

#### CSS class names and selectors are rebranded

| Before | After |
| - | - |
| `.clco-sdk-root` (the scope class on every SDK component) | `.pcl-sdk-root` |
| Tailwind prefix `clcosdk:` | `pclsdk:` |
| `--clcosdk-*` theme variables | `--pclsdk-*` |
| `clcosdk-on-light`, `clcosdk-on-dark`, `clcosdk-status-dot-ping` | `pclsdk-on-light`, `pclsdk-on-dark`, `pclsdk-status-dot-ping` |
| `@keyframes clco-status-ping` | `@keyframes pcl-status-ping` |
| Injected `<style>` href `clco-sdk-styles` | `pcl-sdk-styles` |

The `--color-*` design tokens keep their names. Only the selector they are defined on changed.

**Migration:** a stylesheet that overrides tokens on `.clco-sdk-root` must target `.pcl-sdk-root` instead.

```css theme={null}
/* Before */
.clco-sdk-root { --color-brand-primary: #0052ff; }

/* After */
.pcl-sdk-root { --color-brand-primary: #0052ff; }
```

The `name` on every log record from `pinoClientLogger` and `pinoServerLogger` is now `@passage-cl/react`. Update any log filter that matches on the old name.

#### ESM only, Node engines and bounded React peers

* The package ships ES modules only. The CommonJS builds, `main`, `module` and the `require` export conditions are removed. Bundlers and Next.js consume ESM natively. A plain-Node `require()` works only through Node's built-in `require(esm)`.
* `engines.node` is now `^20.19.0 || >=22.12.0`.
* The `react` and `react-dom` peer ranges are now `^18.0.0 || ^19.0.0`, instead of `>=18.0.0`. `viem ^2` is unchanged.

#### Universal names are exported from `/universal` only

Each name now has exactly one entry point. These names were exported from both `@coinlist-co/react` and `/universal`, and are now exported only from `@passage-cl/react/universal`:

`HttpError`, `HttpResponse`, `EvmWallet`, `EvmSigner`, `ConnectWallet`, `BroadcastTxParams`, `WriteContractParams`, `WalletError`, `RedactedWalletError`, `RpcFailureReason`, `KycToken`, `KycLevelName`, `Logger`, `LogLevel`, `ProductionLogLevel`, `LogScope`, `LogValue`, `LogCause`, `LogBinding`, `LogBindings`, `SafeEvent`, `SafeFields`, `DebugEvent`, `UnredactedFields`, `RequestId`, `FrontlineEventId`, `PinoLoggerOptions`.

**Migration:**

```ts theme={null}
// Before
import { HttpError, type EvmWallet } from "@coinlist-co/react";

// After
import { HttpError, type EvmWallet } from "@passage-cl/react/universal";
```

#### The public API is Containers, viewmodels, data hooks and namespaces

The public surface is now: each feature's root Container, the viewmodel behind it, the data hooks it is built from, and the namespaces. Views, sub-screens, step viewmodels and the standalone flow functions are no longer exported. To build your own UI, use the product's top-level viewmodel, whose state still carries each step's UI types.

| Removed | Use instead |
| - | - |
| `OndoBuyCheckoutContainer`, `OndoSellCheckoutContainer`, `SuperstateSwapCheckoutContainer` | `CheckoutContainer` (with `side="sell"` for an Ondo sell) |
| Every checkout View and step: `OndoBuyCheckoutView`, `OndoBuyAmountView`, `OndoBuyReviewView`, `OndoSellCheckoutView`, `SuperstateSwapCheckoutView`, `SuperstateAmountView`, `SlippagePicker` and the rest | `CheckoutContainer`, or `useOndoBuyCheckoutViewModel`, `useOndoSellCheckoutViewModel`, `useSuperstateSwapCheckoutViewModel` with your own markup |
| Step viewmodels: `useOndoBuyAmountViewModel`, `useOndoBuyReviewViewModel`, `useOndoSellAmountViewModel`, `useOndoSellReviewViewModel`, `useOndoSidebarViewModel`, `useOndoWalletSelectViewModel`, `useSuperstateAmountViewModel`, `useSuperstateReviewViewModel`, `useSuperstateSidebarViewModel`, `useSuperstateWalletViewModel`, with their options, results and `validate*` helpers | The product's top-level viewmodel |
| `OffersGridView`, `OffersAssetGrid`, `useOffersGridViewModel`, `OffersGridUiState`, `OffersGridUiEvent` | `OffersGridContainer`, or lay out `OfferAssetCard` and `OfferSaleCard` yourself |
| `CoinListSignInCardView` | `CoinListSignInCardContainer` or `useCoinListSignInCardViewModel` |
| Requirement screens: `IdentityVerificationContainer`, `TaxDocumentModalContainer`, `ConnectWalletModalContainer`, their Views and viewmodels, `RequirementItem`, `ConnectedWalletList`, `VerificationOverlay` | `RequirementsChecklistContainer`, or `useRequirementsChecklistViewModel` and the data hooks (`useKycToken`, `useTaxDocument`, `useConnectWallet`, `useRequirements`, `useOptionAddresses`) |
| `useCheckoutOfferTokenMetadata`, `offerTokenIdentifier`, `tokenMetadataOf` | `useTokenMetadata`, `useTokenRegistry` |
| `executeTokenSale` | `passage.tokenSale.execute` |
| `prepareOndoBuy`, `prepareOndoSell`, `executeOndoSwap` | `passage.ondo.prepareBuy`, `passage.ondo.prepareSell`, `passage.ondo.executeSwap` |
| `executeSwap`, `authorizeWallet` (Superstate) | `passage.superstate.execute`, `passage.superstate.authorizeWallet` |
| `connectExternalWalletFlow`, `ConnectWalletFlowParams` | `passage.wallets.connect(params)` with `ConnectWalletParams` (see Added) |
| `SwapQuote.fromPreview` | `passage.superstate.getQuote(params)` (see Added) |
| `OndoBuyExecutionResult`, `OndoSellExecutionResult` | `OndoSwapExecutionResult<OndoBuyTransaction>`, `OndoSwapExecutionResult<OndoSellTransaction>` |
| `ensureErc20Allowance`, `submitErc20Approval` and their `Erc20AllowanceResult`, `SubmitErc20ApprovalResult` | Approvals run inside `prepare*` and `execute`. Read an allowance with `passage.erc20.getAllowance` |
| `fetchAllPages` | The namespaces' `list()` methods, which paginate for you |

These are removed with no replacement: `classifyWalletError` (flows return an already classified `WalletError`), `offerAssetIconUrl`, `offerIconUrl`, `stablecoinIconUrl`, `tokenLogoUrl`, `tokenLogoSrcSet`, `USDC_ICON_URL`, `USDT_ICON_URL`, `formatMonthYear`, `formatCountdown`, `formatSaleCardCountdown`, `useCountdown`, the Ondo and Superstate constants and ABIs (`ONDO_*`, `DEFAULT_ONDO_AMOUNT_TO_COMPUTE_PRICE`, `DEFAULT_ONDO_SELL_TOKENS_TO_COMPUTE_PRICE`, `ondoQuoteOfferDeadline`, `DEFAULT_AMOUNT_TO_COMPUTE_PRICE`, `SUPERSTATE_ISSUER_NAME`, `SUPERSTATE_SUPPORTED_INPUT_ASSETS`, `SUPERSTATE_SWAP_CONTRACT_ADDRESS_SEPOLIA` (call `superstateSwapContractAddress(chain)` instead), `SWAP_POLL_INTERVAL_MS`, `SUPERSTATE_SWAP_ABI`, `ERC20_ABI`), the step enums `OndoBuyStep`, `OndoSellStep` and `SuperstateSwapStep`, `ondoLoadErrorReason`, `ERC20_BALANCE_POLL_INTERVAL_MS`, `quoteIsStale`, `quoteOverAsks`, `decodeSwappedOutputAmount`, `BPS_DENOM`, `applyBps`, `QueryParamValue`, `QueryParamValues`, `User`, `UserId`, `UserEmail`, `PaginatedResponseDto`, `ServerNamespaceContext`, `ServerAuthConfig`, and the client auth internals (`OAUTH_STATE_KEY`, `OAUTH_CODE_VERIFIER_KEY`, `ClientAuthConfig`, `ClientAuthSession`).

The `*NamespaceImpl` classes and the `fromDto` companions are no longer part of the published types. Reach every namespace through `PassageClient` or `PassageServer`.

The `*Params` types of the client flow methods (`PrepareOndoBuyParams`, `ExecuteSwapParams`, `AuthorizeWalletParams` and the rest) no longer carry the namespaces the SDK injects. A call on `passage.*` passes the same object as before. Only code that builds these types with `ondo`, `erc20`, `swap`, `wallets` or `tokenSale` fields breaks. `ExecuteOndoSwapParams` loses `now`.

`OauthClientResult` and `OauthClientErrorReason` are renamed `OAuthClientResult` and `OAuthClientErrorReason`.

> [!NOTE]
>
> Everything tagged `@alpha` in the published types is public but outside the compatibility contract, and may still change in a minor release. That covers the new Centrifuge, claim and token-sale checkout surfaces.

#### `CheckoutContainer` takes `side` as a prop, and `config` is optional

| Before | After |
| - | - |
| `config: CheckoutConfig`, with every key required | `config?: CheckoutConfig`, defaulting to `{}`, with every key optional |
| `defaultCheckoutConfig(...)`, `RequiredCheckoutConfig` | Removed. Pass a plain object or omit `config` |
| `config["ondo::swap"].side: () => OrderBookSide` | `side?: OrderBookSide` prop, default `"buy"` |
| `config["ondo::swap"].symbol` | Removed. The SDK derives the symbol from `offer.asset.code` |
| `config["coinlist::token_sale"].render` | Removed. The SDK renders the token sale itself. The entry is `{ onOrderPlaced? }` (see Added) |

Only `offer`, `chain` and `wallets` are required. `side` is read once at mount: Ondo mounts its buy or sell checkout, a Centrifuge vault mounts its buy checkout for `"buy"` and an empty container for `"sell"`, and Superstate and the token sale ignore it. To change the side, remount with a `key` that covers the offer, the chain and the side. A sell page that forgets `side` now renders the buy checkout instead of failing to compile.

**Migration:**

```tsx theme={null}
// Before
const config = defaultCheckoutConfig({
  "ondo::swap": { symbol: (offer) => AssetSymbol(offer.asset.code), side: () => "sell" },
  "coinlist::token_sale": { render: (offer) => <MyTokenSalePage offer={offer} /> },
});
<CheckoutContainer offer={offer} chain={chain} wallets={wallets} config={config} />

// After
<CheckoutContainer
  key={`${offer.id}:${chain}:sell`}
  offer={offer}
  chain={chain}
  side="sell"
  wallets={wallets}
/>
```

See [Checkout](/sdk/checkout).

#### `CheckoutWalletSelection` takes an `externalAdapter`

`CheckoutWalletSelection` is now the shared `WalletSelection` plus `preselected`. The two callbacks move into one adapter, and `null` hides the external-wallet row for a host with embedded wallets only.

| Before | After |
| - | - |
| `connectExternal: () => Promise<void>` | `externalAdapter: { connect, disconnect } \| null` |
| `disconnectExternal: () => Promise<void>` | `externalAdapter.disconnect` |

**Migration:**

```ts theme={null}
// Before
const wallets = { embedded, external, preselected: null, connectExternal: open, disconnectExternal: disconnect };

// After
const wallets = { embedded, external, preselected: null, externalAdapter: { connect: open, disconnect } };
```

A rejected `disconnect` is now logged and the selection is kept. Before, it was an unhandled promise rejection.

In the wallet step's UI state, `externalWallet` is now the three-arm `CheckoutExternalWalletUi` (`hidden`, `disconnected`, or `connected` with `canDisconnect`), and `canDisconnect` moves inside it. See [Wallets](/sdk/wallets).

#### Checkout viewmodel state

* `OndoWalletSelectUiState` and `OndoWalletSelectUiEvent` are replaced by `CheckoutWalletSelectUiState` and `CheckoutWalletSelectUiEvent`. The event has the same shape. The state's `externalWallet` changes as described above.
* `OndoBuyCheckoutUiState.wallet` is now nullable. It is `null` when a preselected wallet skipped the wallet step.
* `OndoBuyQuoteStatusUi` and `OndoSellQuoteStatusUi` merge into `OndoQuoteStatusUi`, with the same shape.
* Superstate's amount step uses the shared `CheckoutAmountUiState` and `CheckoutAmountUiEvent`. `SuperstateAmountUiState` and `SuperstateAmountUiEvent` are removed, `confirmEnabled` becomes `confirmCta: CheckoutCtaUi`, and the confirm event `ON_PREVIEW_ORDER` is renamed `ON_CONFIRM_AMOUNT`.
* The Superstate order dialog state drops `issuer`.

#### Data hooks return a `state` union

These hooks now return a discriminated union instead of loose fields. Each state is `DISABLED | LOADING | ERROR { reason: LoadErrorReason } | CONTENT`.

| Hook | Before | After |
| - | - | - |
| `useSwapQuote` | `{ quote, isLoading, isRefreshing }` | `{ state: LoadSwapQuoteState }` |
| `useErc20Balance` | `{ balance, isLoading }` | `{ state: LoadErc20BalanceState }` |
| `useErc20TokenBalances` | `{ balances, isLoading }` | `{ state: LoadErc20TokenBalancesState }` |
| `useSwapOutputToken` | `{ outputTokenState: SwapOutputTokenState, refetch }` | `{ state: LoadSwapOutputTokenState, refetch }` |

`useSwapQuote` now reaches `ERROR` on a first failure instead of staying in its loading state. A failed refresh behind a quote it already has stays `CONTENT`. `useErc20TokenBalances` and `useSwapOutputToken` report `LOADING` as soon as their request changes, instead of showing the previous request's answer.

The Ondo load states (`LoadOndoPriceState`, `LoadOndoTradingStatusState`, `LoadOndoBuyTransactionState`, `LoadOndoSellTransactionState`) gain a `DISABLED` arm. A hook switched off with nothing in hand reports `DISABLED` instead of `LOADING`. An exhaustive `switch` over these states needs the new case.

#### `useParticipations` is renamed `useCoinListTokenSaleParticipations`

| Before | After |
| - | - |
| `useParticipations` | `useCoinListTokenSaleParticipations` |
| `UseParticipationsOptions` | `UseCoinListTokenSaleParticipationsOptions` |
| `UseParticipationsResult` | `UseCoinListTokenSaleParticipationsResult` |
| `LoadParticipationsState` | `LoadCoinListTokenSaleParticipationsState` |
| `LoadParticipationsReason` | `LoadErrorReason` (same values) |

Its behavior changes too:

* It polls `passage.tokenSale.list(offerId)` every 15 seconds while the page is visible, and reads again when the page becomes visible. `pollInterval?: Seconds` sets the interval.
* It returns `refetch()`.
* A `data` seed skips only the first read. Before, a seed stopped all fetching.
* A switched-off hook with nothing in hand reports `DISABLED` instead of `LOADING`.
* A failed poll keeps the list it already has. A `not-authenticated` failure drops the list and reports `ERROR`.

**Migration:** apply the renames, and add a `DISABLED` case to any exhaustive `switch` over the state.

#### Flow errors separate "not sent" from "sent but not confirmed"

A transaction that was broadcast but whose receipt wait failed used to come back as an ordinary failure, without its hash, so the UI let the user try again and could fill the order twice. It now has its own error arm, carrying the `txHash`:

| Flow | New error arm |
| - | - |
| `passage.ondo.executeSwap` (`OndoSwapExecutionError`) | `{ step: "swap-unconfirmed"; txHash; cause }` |
| `passage.superstate.execute` (`SwapExecutionError`) | `{ step: "swap-unconfirmed"; txHash; cause }` |
| `passage.superstate.authorizeWallet` (`WalletAuthorizationError`) | `{ step: "broadcast-unconfirmed"; txHash; cause }` |

The `swap` and `broadcast` steps now mean only that the wallet never sent the transaction. The built-in review steps disable their button until the user leaves the step, and show "Your order was sent but has not confirmed yet. Check your wallet before placing another." (or the swap and authorization equivalents).

**Migration:** handle the new arms wherever you `switch` on these errors, and do not retry them.

#### `passage.tokenSale.execute` takes the offer

| Before | After |
| - | - |
| `{ wallet, offerId, offerOptionId, assetId, paymentTokenAddress, fundingContractAddress, chain, amount, onProgress? }` | `{ wallet, offer, optionId, chain, inputAsset, amount, approval?, onProgress? }` |

The flow reads the funding contract, the payment token and the asset id from the `CoinListTokenSaleOfferDetail`. It refuses an `unsupported-chain`, an `unsupported-asset` or an `unknown-option` before it prompts the wallet. Pass `approval: { type: "mined", txHash }` to retry a participation whose approval already mined, without a second wallet prompt.

`CoinListTokenSaleOfferDetail` gains `fundingContracts: OfferFundingContract[]`, read from the required `funding_contracts` field of the offer response.

#### Token-sale and Superstate types

* The `Blockchain` and `WalletAddress` newtypes are removed. `CreateParticipationParams` takes `chain: EthereumChain` and `walletAddress: EvmWalletAddress`. `Participation.chain` is now `Chain | null`, and `null` stands for a chain the SDK does not model. `Participation.walletAddress` is `EvmWalletAddress | null`.
* `AllowWalletResponse`'s broadcast arm nests the transaction: `{ action: "broadcast_transaction"; tx: Tx }` instead of `{ action; to; data }`.
* `CoinListSignInButtonProps` is its own interface, and its props no longer accept `null`. Omit a prop instead.

#### Session handling (server)

* `ServerConfig.accessTokenExpiryBufferSeconds` is now a `Seconds`, not a `number`. Build it with `Seconds.of(120)` from `@passage-cl/react/universal`. The default is still 60 seconds.
* `passage.auth.getAccessToken()` on the server now **throws** the underlying error when the access token has expired and the refresh could not get an answer: a 5xx, a network failure or `invalid_client`. It used to return `null` and clear the session. It still returns `null` when there is no session or the session was rejected. Other methods that need a session throw the same error in that case.
* `CompleteOAuthParams` is removed. `passage.auth.completeOAuth(grant)` takes an `AuthorizationGrant` (`{ code, codeVerifier }`) from `@passage-cl/react/universal`, with the same fields.
* `ServerAuthNamespaceImpl` is no longer exported.

**Migration:** an endpoint that serves the browser's `getAccessToken` should map a `null` to "no session" (for example a `204`) and a throw to a failure (for example a `503`). An endpoint that maps every throw to "no session" signs your users out during an outage.

```ts theme={null}
// Before
createPassageServer({ ...config, accessTokenExpiryBufferSeconds: 120 });

// After
import { Seconds } from "@passage-cl/react/universal";
createPassageServer({ ...config, accessTokenExpiryBufferSeconds: Seconds.of(120) });
```

See [OAuth authentication](/sdk/oauth-authentication).

#### Session handling (browser)

A throw from your `ClientConfig.getAccessToken` now leaves the auth state as it was, and `passage.init()` rejects with that error. Before, a throw became `"logged-out"`. `PassageProvider` catches it, so `usePassage().isReady` can be `true` while `passage.auth.getState()` is still `"unknown"`. Resolve `null` for "no session" and throw for "could not find out".

#### An empty base URL throws

`createPassageClient` and `createPassageServer` throw a `ValidationError` when `baseUrl` or `tokensBaseUrl` is an empty or whitespace-only string, for example an environment variable set to nothing. Before, the browser fell back to production for an empty `baseUrl`, and the server built relative URLs. Omit the field to use the default. In React, the error throws from `PassageProvider`'s render.

### Added

#### CoinList token-sale checkout in `CheckoutContainer`

A `coinlist::token_sale` offer now mounts the SDK's own checkout: a wallet step, an amount in USD paid in USDC or USDT, and a review with the estimated tokens, the price per token and the receiving wallet. The amount is checked against the option's minimum, and the checkout is blocked outside the sale window. Placing the order runs `passage.tokenSale.execute`.

* `optionId?: OfferOptionId` on `CheckoutContainer` picks the sale option. It defaults to the first option and is read once at mount.
* `config["coinlist::token_sale"].onOrderPlaced` is called after an order is placed.
* An option with no fixed price, such as an auction, renders "Not available yet" (`no-price`).
* `useCoinListTokenSaleCheckoutViewModel` and its UI types are public (`@alpha`). `TokenSaleApproval` is public and inside the compatibility contract.

#### Centrifuge vaults

`centrifuge::vault` is a new offer type (`@alpha`). Vault offers now appear in offer listings. Before, the SDK dropped them from a list and threw on `passage.offers.get` for one. `CentrifugeVaultOfferDetail` carries `vaultContracts`, and `TokenRole` gains `"vault"`.

* `CheckoutContainer` mounts a Centrifuge buy checkout, which places a deposit request, for `side: "buy"`. It is USDC only and blocks with `unsupported-chain` or `not-orderable` while the vault is paused. `side: "sell"` renders an empty container until the redeem flow ships. `config["centrifuge::vault"].onOrderPlaced` fires after the request mines.
* `passage.centrifuge` exists on both `PassageClient` and `PassageServer`:

| Method | Endpoint |
| - | - |
| `getVaultStatus({ symbol, chain })` | `GET /v1/centrifuge/vault/status` |
| `buildBuyTransaction({ symbol, chain, walletAddress, amount })` | `POST /v1/centrifuge/vault/invest` |
| `createClaim({ symbol, chain, walletAddress })` | `POST /v1/centrifuge/vault/claim` |
| `createClaimProceeds({ symbol, chain, walletAddress })` | `POST /v1/centrifuge/vault/claim-proceeds` |
| `readDepositPosition({ vault, walletAddress })`, `readRedeemPosition(...)` | On-chain read of the vault proxy over JSON-RPC |
| `buy`, `prepareBuy`, `placeRequest`, `claim` (browser only) | The flows above, through the wallet |

* Hooks: `useCentrifugeVaultStatus`, `useCentrifugeVaultStatuses`, `useCentrifugeClaimPositions`, `useCentrifugeClaim`, `useCentrifugeBuyCheckoutViewModel` and `useCentrifugeVaultClaimViewModel`.
* `'CENTRIFUGE'` is a new `LogScope`. A logger that switches over `LogScope` needs the case.

Code with an exhaustive `switch` over `OfferType`, `Offer["type"]`, `OfferDetail["type"]` or `TokenRole` needs a `centrifuge::vault` (or `vault`) case.

#### `ClaimContainer`

`ClaimContainer` (`@alpha`) is a drop-in card, titled "Your orders", for the second leg of an asynchronous offer. Narrow the offer with `AsyncOfferDetail.is(offer)` first.

```tsx theme={null}
{AsyncOfferDetail.is(offer) && <ClaimContainer key={offer.id} offer={offer} wallets={wallets} />}
```

* For a Centrifuge vault, it reads every wallet's pending and claimable positions on-chain, and offers a Claim button on each claimable row. `config["centrifuge::vault"].onClaimed` fires after a claim.
* For a CoinList token sale, it lists your participations in that sale across your account and polls every 15 seconds, so an order placed on the same page appears by itself. There is nothing to claim: the sale delivers tokens and refunds by itself.
* It takes `wallets: WalletSelection`, an optional `walletLabel` resolver, `config`, `enabled` and `className`.
* To build your own claim UI, use `useCentrifugeVaultClaimViewModel` or `useCoinListTokenSaleClaimViewModel` (`@alpha`), with their UI state and event types.

#### Wallet preselection in every checkout

A preselected wallet (`wallets.preselected`) now applies to every provider. Ondo buy and sell, Centrifuge and the token sale skip the wallet step and open on the amount, and the remaining cards renumber. Superstate keeps its wallet step, because that step allow-lists the wallet on-chain, but opens with that wallet's row selected. `preselected` is read once at mount: put it in the `key` if it can change. Before, only Ondo sell honored it.

#### `onSessionExpired`

`Config.onSessionExpired?: () => Promise<void>` tells you when the SDK has given up on a session, on both the client and the server.

* In the browser, it fires after a `401` when your `getAccessToken` twice answers `null` or the very token the API just refused, one second apart, and the user had been logged in.
* On the server, it fires when the same refresh token is rejected twice, 5 to 60 seconds apart, or when an expired session has no refresh token. The `SessionStore` is cleared first.
* It never fires on logout, a 5xx or a network failure. It fires at most once per session within a 60-second window, counted per JavaScript module instance on the server (Next.js middleware and route handlers count separately), so make the handler idempotent. The SDK does not await it, and a rejection is logged and dropped.

#### Ondo market closed

When an Ondo market is paused or closed, the API answers a quote with `409 not_tradable`. The Ondo checkout now shows "Trading is closed right now" until the trading status reports tradable again. `isOndoNotTradableError(error)` (`/universal`) recognizes the error, `isNotTradable(state)` reads the trading-status state, and `OndoLoadErrorReason` and `OndoCheckoutErrorReason` gain `"not-tradable"`.

#### Namespace methods

* `passage.wallets.connect({ wallet, offerId, offerOptionId })` binds a host wallet to an offer option. It replaces `connectExternalWalletFlow`.
* `passage.superstate.getQuote(params)` returns a `SwapQuote`, on both the client and the server.

#### Other additions

* `LoadErrorReason` (`"not-authenticated" | "generic-error"`) is the shared reason on the `ERROR` state of the ERC-20, Superstate quote, Ondo, participation and Centrifuge hooks. On these hooks an HTTP `401`, including one from the JSON-RPC proxy, now reports `not-authenticated` instead of `generic-error`. `useOffers`, `useOfferDetails` and `useRequirements` keep their own reason types.
* `EpochMillis`, `Millis` and `Seconds` time types in `/universal`.
* `WalletSelection`, `ExternalWalletAdapter` and `WalletLabelResolver` in `/universal`.
* `formatShareAmount(amount, locale)`, and a `minFractionDigits` option on `formatAmount`.
* `CheckoutExternalWalletUi`, `CheckoutWalletSelectUiState`, `CheckoutAmountUiState`, `CheckoutBlockedReason`, `OndoQuoteStatusUi` and the `Load*State` types named above.
* `./package.json` is exported.
* The published API is recorded in API reports, and the typed surface outside `@alpha` is the compatibility contract.

### Changed

* **Single-flight session renewal.** On the server, one refresh runs per refresh token per process, shared across `PassageServer` instances. A first `invalid_grant` no longer clears the session, and a 5xx or network failure never clears it. In the browser, concurrent requests share one `getAccessToken` call. A `401` now forces a refresh even when the token looks valid locally. `/oauth/token` is never retried automatically.
* **A session with an invalid `expiresAt`** now throws `ValidationError` instead of being served as fresh forever.
* **Superstate checkout copy** now matches the Ondo and Centrifuge wording. The amount button reads "Confirm amount", approval and swap errors use the shared copy, and the review disclaimer names CoinList's Terms of Service and Privacy Policy as well as Superstate's Terms.
* **Amount validation order** is the same in every checkout: parse, zero, minimum, balance, cap. Ondo buy now reports the minimum before the balance.
* **Amount fields** show the token symbol after the number and accept only digits and one decimal point. The "Powered by CoinList" tag is removed from the sign-in card.
* **`formatAmount`** trims trailing zeros past the minimum after rounding, and Ondo share amounts show at most six decimals.
* **The Superstate review** keeps its in-flight state when the user leaves mid-swap, so a second swap cannot start while the first is still running.

### Fixed

* `passage.auth.logout()` on the server clears the session whatever the revoke failure, including a network error, unless `strict` is set. With `strict`, it rethrows and keeps the session.
* In the browser, `passage.auth.logout()` wins over a `getAccessToken` answer already in flight, so a late answer can no longer sign the user back in.
* `passage.ondo.executeSwap` keeps the `txHash` when the receipt wait fails (see the new `swap-unconfirmed` arm).
* The Ondo transaction hooks no longer get stuck loading when the request changes during a build.
* A nullable field missing from a response now reads as `null` instead of `undefined`.
* A `401` renewed into a persistent 5xx makes 4 attempts instead of 6.
* `instanceof HttpError` holds whichever entry point the error came from.
* Long fund names wrap in the order-confirmation dialogs.

**v0.12.1**

September 28, 2026 - Offers as a union on type, on-chain reads over JSON-RPC, token-registry artwork in the offers grid, and enabled on every data hook

This is a patch release by number, but it breaks compile-time contracts. `Offer` and `OfferDetail` become unions on `type`, so a field that only one kind of offer has can only be read after you narrow. The SDK now reads contract state through JSON-RPC instead of dedicated CoinList endpoints, which changes the return types of the ERC-20 and Superstate reads. `OffersGridContainer`'s `data` prop and the requirements checklist's logged-out handling also change shape.

The release also adds `Config.rpc` for routing on-chain reads to your own node, token-registry names and artwork on the offer cards, the security reference fields on `OfferDetail`, and `enabled` on every data hook that was missing it.

### Breaking Changes

#### `Offer` and `OfferDetail` are unions on `type`

Both types are now discriminated unions with one variant per `OfferType`. Each variant carries only the fields that mean something for it:

| Variant | `type` | Only on this variant |
| - | - | - |
| `CoinListTokenSaleOffer` / `CoinListTokenSaleOfferDetail` | `coinlist::token_sale` | `tagline`, `bannerUrl`, `startsAt`; `logoUrl: string` |
| `SuperstateSwapOffer` / `SuperstateSwapOfferDetail` | `superstate::swap` | `tagline`, `bannerUrl`, `startsAt`; `logoUrl: string \| null` |
| `OndoSwapOffer` / `OndoSwapOfferDetail` | `ondo::swap` | `swapContracts`; `logoUrl: string \| null` |

An Ondo swap trades continuously and runs no sale window, so it has no `tagline`, `bannerUrl` or `startsAt`. Previously it carried a blank string and a 1970 date. Swap offers publish without artwork more often than not, so their `logoUrl` is nullable. The fields every offer shares are `OfferBase` and `OfferDetailBase`, and the sale-window trio is `OfferEditorial`.

**Migration:** narrow on `type` before reading a variant field. A field every offer shares (`id`, `slug`, `tokens`, `endsAt`, and on the detail `name`, `asset` and the rest) reads as before.

```ts theme={null}
// Before
const subtitle = offer.tagline;
const spender = swapSpender(detail.swapContracts, chain);

// After
const subtitle = offer.type === "ondo::swap" ? null : offer.tagline;
const spender =
  detail.type === "ondo::swap" ? swapSpender(detail.swapContracts, chain) : null;
```

Code that builds an `Offer` or `OfferDetail` by hand, such as fixtures, mocks or preloaded server data, has to build a specific variant.

The checkout surface narrows with it. Each provider's viewmodel takes its own variant, and so do the `CheckoutConfig` callbacks:

| API | Before | After |
| - | - | - |
| `useOndoBuyCheckoutViewModel`, `useOndoSellCheckoutViewModel` `offer` | `OfferDetail` | `OndoSwapOfferDetail` |
| `useSuperstateSwapCheckoutViewModel` `offer` | `OfferDetail` | `SuperstateSwapOfferDetail` |
| `config["ondo::swap"].symbol` | `(offer: OfferDetail) => AssetSymbol` | `(offer: OndoSwapOfferDetail) => AssetSymbol` |
| `config["coinlist::token_sale"].render` | `(offer: OfferDetail) => ReactNode` | `(offer: CoinListTokenSaleOfferDetail) => ReactNode` |

An inline callback such as `symbol: (offer) => AssetSymbol(offer.asset.code)` compiles unchanged. A callback you annotated with `OfferDetail` needs the narrower type.

The offer-card UI models follow the same change. On `OfferSaleCardUi`, `tagline` and `startsAt` are now nullable (`null` for an Ondo swap). On both `OfferSaleCardUi` and `OfferAssetCardUi`, `logoUrl: string` is replaced by `logo: OfferLogoUi | null`. See "Token-registry artwork on the offer cards" under Added.

> [!NOTE]
>
> A page from `coinlist.offers.list()` or `listPage()` now **drops** any offer whose `type` this SDK version does not know, instead of failing the whole page. `coinlist.offers.get(id)` still throws `ValidationError` for an unknown type, because a single offer has nothing beside it to keep. `isOfferType(value)` is exported if you receive offer types from somewhere else.

#### `OffersGridContainer` `data` is an object

The grid now loads the token registry alongside the offers, so its server-seed prop takes both.

| Before | After |
| - | - |
| `data?: Offer[]` | `data?: OffersGridData` (`{ offers?: Offer[]; tokens?: TokenMetadata[] }`) |

The change applies to both `OffersGridContainer` and `useOffersGridViewModel`. Each half is independent: seed only `offers` and the client still fetches the registry.

**Migration:**

```tsx theme={null}
// Before
<OffersGridContainer data={offers} />

// After
const server = coinListServerForRSC();
const [offers, tokens] = await Promise.all([server.offers.list(), server.tokens.list()]);
<OffersGridContainer data={{ offers, tokens }} />
```

#### On-chain reads return plain values

`coinlist.erc20` and the read methods of `coinlist.superstate` now call the contract through a viem `PublicClient` instead of a CoinList endpoint that wrapped each value in a DTO. The single-field wrappers are gone:

| Method | Before | After |
| - | - | - |
| `coinlist.erc20.getAllowance(params)` | `Promise<TokenAllowance>` (`{ allowance }`) | `Promise<Uint256>` |
| `coinlist.erc20.getBalance(params)` | `Promise<TokenBalance>` (`{ balance }`) | `Promise<Uint256>` |
| `coinlist.superstate.getAuthorization(params)` | `Promise<SwapAuthorization>` (`{ authorized }`) | `Promise<boolean>` |

`TokenAllowance`, `TokenBalance` and `SwapAuthorization` are removed.

**Migration:** drop the property access.

```ts theme={null}
// Before
const { balance } = await coinlist.erc20.getBalance({ tokenAddress, owner, chain });
const { authorized } = await coinlist.superstate.getAuthorization(params);

// After
const balance = await coinlist.erc20.getBalance({ tokenAddress, owner, chain });
const authorized = await coinlist.superstate.getAuthorization(params);
```

**The logged-out error changes.** These reads no longer throw `NotAuthenticatedError`. By default they go through CoinList's authenticated JSON-RPC proxy, so a logged-out read fails with the proxy's `401`. viem wraps whatever a transport throws, so that `401` reaches you as a viem error wrapping the SDK's `HttpError`. A chain you point at your own node through `Config.rpc` (see Added) needs no CoinList session at all. `coinlist.superstate.allowWallet` is a backend write and still throws `NotAuthenticatedError`.

#### Superstate `SwapStatus` is a union, and paused is not stopped

`SwapStatus` was `{ stopped: Uint256; swapLevel: Uint256 }`. It is now:

```ts theme={null}
type SwapStatus =
  | { state: "active" }
  | { state: "paused"; pausedLevels: PauseFlags }
  | { state: "stopped" };
```

| Before | After |
| - | - |
| `isStopped(status)` | `!isSwapAvailable(status)` |
| `SwapStatus.fromDto`, `SwapPreview.fromDto` | `SwapStatus.fromContract`, `SwapPreview.fromContract` |

A `paused` contract may still be swapping. `pausedLevels` is a bitmask over operations, and only the `SWAP_LEVEL` bit halts swaps. Ask `isSwapAvailable(status)` rather than comparing `state` to `"active"`.

`SwapExecutionError` gains a `swap-paused` arm, and `swap-stopped` now means the swap is permanently closed:

| `step` | Meaning | Copy to show |
| - | - | - |
| `swap-paused` | **New.** The contract has suspended swapping and may resume. | "Try again shortly." |
| `swap-stopped` | The contract is permanently halted. | "This swap has closed." |

**Migration:** add a `swap-paused` case wherever you `switch` on `result.error.step` from `coinlist.superstate.execute`.

> [!WARNING]
>
> `SUPERSTATE_SWAP_CONTRACT_ADDRESS_SEPOLIA` now points at a different contract. The old Sepolia deployment cannot serve the contract's current ABI. If you hard-coded the previous address instead of importing the constant, switch to the constant.

#### The requirements checklist no longer renders a sign-in card

`unauthenticatedState` is removed from `RequirementsChecklistContainer` and `RequirementsChecklistView`, and `RequirementsChecklistUiState` loses its `not-authenticated` arm. A logged-out session now renders the checklist's error state and fetches nothing. The `loading` and `error` arms now carry the `title` (and `loading` also the `description`), so the header stays in place while the rows load or fail.

**Migration:** gate on auth before mounting the checklist, and render the sign-in card yourself.

```tsx theme={null}
// Before
<RequirementsChecklistContainer offerId={offer.id} optionId={option.id} {...copy} />

// After
const { isReady, coinlist } = useCoinList();
return isReady && coinlist.auth.getState() === "logged-in" ? (
  <RequirementsChecklistContainer offerId={offer.id} optionId={option.id} {...copy} />
) : (
  <CoinListSignInCardContainer />
);
```

A host that drives `useRequirementsChecklistViewModel` behind its own markup drops its `not-authenticated` case. `useRequirements` itself still reports `reason: "not-authenticated"`.

#### `ONDO_QUOTE_EXPIRY_THRESHOLD_MS` is replaced

| Before | After |
| - | - |
| `ONDO_QUOTE_EXPIRY_THRESHOLD_MS` (5 s buffer before Ondo's deadline) | `ONDO_QUOTE_MAX_TTL_MS` (15 s) and `ondoQuoteOfferDeadline(expiresAt, nowMs?)` |

The review step now offers a committed quote until the earlier of Ondo's deadline and 15 seconds after it was built, instead of until 5 seconds before Ondo's deadline.

**Migration:** only for hosts building their own Ondo review step. Count down to `ondoQuoteOfferDeadline(transaction.expiresAt)` instead of `expiresAt` minus the old threshold.

### Added

#### Route on-chain reads to your own node

`Config` takes an optional `rpc: RpcConfig`, which maps each `EthereumChain` to an RPC URL or a viem `Transport`:

```ts theme={null}
import { fallback, http } from "viem";

createCoinListClient({
  clientId,
  redirectUri,
  rpc: {
    ethereum_mainnet: "https://eth-mainnet.example.com/v2/KEY",
    ethereum_sepolia: fallback([http(primaryUrl), http(backupUrl)]),
    // base_* unset: proxied through CoinList
  },
});
```

A chain you leave out falls back to CoinList's proxy (`POST /v1/chains/{chain}/rpc`) on its own, so overriding mainnet does not opt Sepolia out. The SDK always builds the `PublicClient` itself, so the chain definition, Multicall batching and retry policy stay the same whatever transport you pass. `createCoinListServer` takes the same option.

Alongside it:

* `viemChain(chain)` returns the viem `Chain` definition the SDK uses for an `EthereumChain`.
* `isSwapAvailable`, `SWAP_LEVEL` and `PauseFlags`, for the Superstate status above.
* Logging: a new `RPC` `LogScope`, and an `rpc` arm on `LogCause` with `reason: RpcFailureReason` (`reverted`, `node-rejected`, `transport`, `malformed-response`, `unknown`). Each reason names a remedy, not the viem error class. Nothing is read off the thrown error above `debug`.

#### Token-registry artwork on the offer cards

`OffersGridContainer` now loads the public token registry alongside the offers. Each card takes its name, ticker and logo from the registry when it lists the offer's token, and falls back to the offer's own fields otherwise. The grid waits for both loads, so a card paints once with its final artwork. If the registry fails, the cards fall back to the offer's own fields instead of failing the grid.

| Export | What it is |
| - | - |
| `useTokenRegistry({ data?, enabled? })` | Loads the whole registry in one request and indexes it. Returns `{ state, refetch }`, where `state` is `LoadTokenRegistryState` (`DISABLED`, `LOADING`, `ERROR`, `CONTENT`). No polling. |
| `TokenRegistrySnapshot` | `fromTokens(tokens)`, `get(snapshot, { chain, address })`, `forOffer(snapshot, offer)`. Exported from `/universal`. |
| `offerDisplayTokens(offer)` | The tokens an offer is about, most specific first: `swap` entries, then `distribution`, never `funding`. |
| `OfferLogoUi`, `LogoImageUi` | `{ light, dark }` logo with `src` and optional `srcSet`. `dark` is `null` when the registry has no dark variant. |

`OfferSaleCardUi.fromOffer` / `fromDetail` and `OfferAssetCardUi.fromOffer` / `fromDetail` take an optional second argument, the offer's `TokenMetadata | null`. Registry values win when both exist.

#### Security reference fields on `OfferDetail`

`OfferDetailBase` gains five nullable fields describing the underlying security:

| Field | Example | Notes |
| - | - | - |
| `issuer` | `"Ondo Global Markets"` | The issuer of the *token*. The security's issuer is `name`. |
| `isin` | `"US0378331005"` | New `Isin` newtype. `null` for offers that tokenize no security *and* for the few whose supplier publishes none. |
| `ticker` | `"QQQ"` | The listing-venue symbol, not the token symbol (`asset.code`, e.g. `"QQQon"`). |
| `instrumentType` | `"Stock"`, `"ETF"` | The supplier's vocabulary, which may grow. Render it as given rather than branching on it. |
| `listingVenue` | `"NASDAQ"` | Recorded by hand, so `null` is normal on a newly listed offer. |

The Ondo checkout sidebar now fills its asset-detail rows from these fields. A `null` field hides its row.

#### `enabled` on the remaining data hooks

These now take `enabled` (default `true`). When it is `false` they send no request, and a seeded or already-fetched `CONTENT` state survives:

* `useOffers`, `useOfferDetails`, `useRequirements`, `useParticipations`
* `useOffersGridViewModel` and `OffersGridContainer`
* `useRequirementsChecklistViewModel` and `RequirementsChecklistContainer`

#### Requirements checklist states

`RequirementsChecklistItemUi` gains optional `statusMessages` (`pending`, `completed` and `rejected` sentences per requirement type), and the content state gains an optional `blockedMessage` for an unsupported jurisdiction. When `blockedMessage` is set, a neutral banner replaces the description, rows and Continue. The View also renders an explicit empty state when an option has no requirements.

### Changed

* **`CheckoutContainer` mounts only the matching provider's container.** It used to call every provider's viewmodel on every render and disable the ones that did not match. `config["ondo::swap"].symbol` and `side` now run only when an `ondo::swap` offer is showing, so they no longer have to handle Superstate and token-sale offers. `enabled` is forwarded to the mounted container as-is.
* **Ondo quotes are offered for at most 15 seconds.** The review step's countdown runs to the earlier of Ondo's deadline and 15 seconds after the quote was built, then asks for a fresh one.
* **Requirements checklist design and copy.** The footer shows an "N/M completed" counter, and **Continue** stays disabled until every requirement is met. The default labels are now **Identity Verification** (was **KYC Verification**) and **Tax Documentation** (was **Document**), with new descriptions for KYC, accreditation and tax documents. A tax document whose status is `in_progress` stays a required step until the user signs it. The loading, error and unsupported-jurisdiction states were redesigned.

### Fixed

* **Superstate's confirmed output amount.** The `Swapped` event ABI declared two non-indexed words where the contract emits three. As a result, `decodeSwappedOutputAmount` read the protocol fee as the amount received, and `executeSwap` reported that fee as the confirmed `outputAmount`. It now decodes the amount received.
* **Amounts with a leading or trailing decimal point.** `parseBlockchainAmount` now accepts `.25` (read as `0.25`) and `25.` (read as `25`). A bare `.` is still rejected.
* **Checkout loading skeletons.** The price skeletons in `AssetSummaryRow` and the Ondo and Superstate sidebars no longer stack flush against each other while loading.

**v0.12.0**

September 17, 2026 - The /universal entry point, the Ondo sell flow, structured logging, and Base support

Three things change every call site: the `/shared` subpath is now `/universal`, Ondo's one-directional swap API forks into buy and sell, and the Ondo swap contract is read off the offer instead of a constant the SDK held.

The release also adds a complete Ondo **sell** checkout, an optional structured `logger` on `Config`, and Base mainnet and Base Sepolia in the chain model.

### Breaking Changes

#### `@coinlist-co/react/shared` is now `@coinlist-co/react/universal`

The subpath is renamed. Nothing it exports is renamed with it, and the entry point gained exports rather than losing any.

| Before | After |
| - | - |
| `@coinlist-co/react/shared` | `@coinlist-co/react/universal` |

`shared` described where the code sat in the repository; `universal` describes what it is - the half of the SDK that runs unchanged in a browser and on a backend. The old name also collided with the SDK's internal `shared/` directories, which mean something else entirely.

**Migration:** find and replace the import path. There is no compatibility alias - the old subpath is gone from `exports`, so a missed one is a resolution error at build time rather than a silent fallback.

```ts theme={null}
// Before
import { AssetSymbol, type OfferDetail } from "@coinlist-co/react/shared";
// After
import { AssetSymbol, type OfferDetail } from "@coinlist-co/react/universal";
```

The other two entry points, `@coinlist-co/react` and `@coinlist-co/react/server`, are untouched.

> [!NOTE]
>
> `/universal` now also exports `EvmWallet` and the wallet-address constructors, `WalletError`, `Logger` and the rest of the logging types, and `swapSpender`. A host that was reaching for those through `@coinlist-co/react` can keep doing so; both barrels name them.

#### Ondo forks into buy and sell

Ondo ships two products on one `ondo::swap` offer type. Preparing an order now depends on which one, so the single method became two; broadcasting stays one, because it reads calldata and a deadline and knows about neither direction.

| Before | After |
| - | - |
| `coinlist.ondo.prepareSwap(params)` | `coinlist.ondo.prepareBuy(params)` or `coinlist.ondo.prepareSell(params)` |
| `coinlist.ondo.buildSwapTransaction(params)` | `coinlist.ondo.buildBuyTransaction(params)` or `coinlist.ondo.buildSellTransaction(params)` |
| `coinlist.ondo.executeSwap(params)` | unchanged |

A purchase approves the funding coin and a sale approves the asset, and the two builders are two endpoints - `POST /v1/ondo/swap/buy` and `POST /v1/ondo/swap/sell` - whose `amount` is denominated in a different token on each. A single method taking a `side` would have re-merged exactly that distinction.

**Migration:** pick the method that matches the direction. The parameters are otherwise unchanged apart from the required `swapContracts` below.

```ts theme={null}
// Before
const prepared = await coinlist.ondo.prepareSwap({ wallet, symbol, chain, tokenAddress, amount });
// After
const prepared = await coinlist.ondo.prepareBuy({
  wallet, symbol, chain, tokenAddress, amount,
  swapContracts: offer.swapContracts,
});
```

The React surface forked with it. Every buy screen's component and viewmodel is now `OndoBuy*`, the new sell screens are `OndoSell*`, and the two steps both products share kept their unqualified names:

| Before | After |
| - | - |
| `OndoAmountView` | `OndoBuyAmountView` |
| `OndoReviewView` | `OndoBuyReviewView` |
| `OndoOrderConfirmed` | `OndoBuyOrderConfirmed` |
| `useOndoAmountViewModel` | `useOndoBuyAmountViewModel` |
| `useOndoReviewViewModel` | `useOndoBuyReviewViewModel` |
| `useOndoSwapTransaction` | `useOndoBuyTransaction` |
| `OndoWalletSelectView`, `OndoSidebarView` | unchanged |
| `useOndoWalletSelectViewModel`, `useOndoSidebarViewModel` | unchanged |

#### The Ondo swap contract is read off the offer

`ondoSwapContractAddress(chain)` is **removed**, and `OfferDetail` gains a required `swapContracts: OfferSwapContract[]`.

One constant can only name one deployment, and beta and production run different contracts on the same chain - so whichever one it named, the other approved a spender that could not fill the order. The address now arrives per environment on the offer.

**Migration:** pass `offer.swapContracts` to `prepareBuy`, `prepareSell` and `useOndoBuyAmountViewModel`; read a single address with `swapSpender(offer.swapContracts, chain)`. Code that constructs an `OfferDetail` by hand - fixtures, mocks, preloaded server data - adds the field, with `[]` meaning "cannot be swapped anywhere".

```ts theme={null}
import { swapSpender } from "@coinlist-co/react/universal";

// Before
const spender = ondoSwapContractAddress(chain);
// After
const spender = swapSpender(offer.swapContracts, chain); // EvmContractAddress | null
```

`OndoSwapExecutionError` loses its `spender-mismatch` arm as a result: the backend compares the built transaction's destination to the contract it serves on the offer, so a third comparison would check one source against itself.

> [!WARNING]
>
> `ondoSwapContractAddress` is deleted rather than deprecated on purpose. A constant that keeps returning a stale address fails silently against the wrong contract, where a removed export is a compile error.

#### `CheckoutConfig` for Ondo requires `side`

`config["ondo::swap"]` takes a new required `side: () => OrderBookSide`.

A thunk rather than a resolver taking the offer, because no offer can answer it: `offer.type` is `ondo::swap` both ways, and the direction is a property of the page. This is the one config entry that is per-*render* rather than per-integration, so a host with a buy page and a sell page closes the thunk over whatever selects the direction.

```tsx theme={null}
const checkoutConfig = defaultCheckoutConfig({
  "ondo::swap": {
    symbol: (offer) => AssetSymbol(offer.asset.code),
    side: () => "buy",
  },
  "coinlist::token_sale": { render: (offer) => <MyTokenSalePage offer={offer} /> },
});
```

**Migration:** add `side`. It is required with no default because the wire parameter behind it defaults to `buy` silently, and an unstated direction should be a compile error rather than a purchase.

> [!WARNING]
>
> `side` is **read once, at mount**. The flow holds an approval granted for whichever coin that side spends, so a resolver that starts answering differently mid-flow is ignored. Remount with a `key` covering the offer, the chain and the side.

#### The Ondo checkout state is a union

`OndoBuyCheckoutUiState` - and the new `OndoSellCheckoutUiState` - are now discriminated unions rather than product types:

```ts theme={null}
type OndoBuyCheckoutUiState =
  | { type: "content"; wallet; amount; review; sidebar; orderConfirmed }
  | { type: "error"; reason: OndoCheckoutErrorReason };
```

A chain with no Ondo contract on it is known before any step runs, and the old shape had to render a wallet picker leading nowhere and a confident `0 USDC` balance before refusing on Confirm. `OndoCheckoutErrorReason` is `'unsupported-chain'` today.

**Migration:** only for hosts driving `useOndoBuyCheckoutViewModel` behind their own markup. `switch` on `state.type` first, then read the steps off the `content` arm.

#### `OfferCard` is now two components

| Before | After |
| - | - |
| `OfferCard`, `OfferCardProps` | `OfferSaleCard` (`OfferSaleCardProps`) and `OfferAssetCard` (`OfferAssetCardProps`) |

One card cannot be both a live-sale tile and a browse row. `OfferSaleCard` is the dark sale card with the countdown; `OfferAssetCard` is the light catalog row. Each takes its own UI model - `OfferSaleCardUi` or `OfferAssetCardUi`, both with `fromOffer` and `fromDetail` companions - rather than an `Offer`.

**Migration:** pick the card that matches the surface and map the offer through its UI model.

```tsx theme={null}
// Before
<OfferCard offer={offer} onClick={...} />
// After
<OfferSaleCard offer={OfferSaleCardUi.fromOffer(offer)} onClick={...} />
```

#### `CheckoutAssetUi.fromOffer` takes token metadata

Checkout asset icons now resolve from the public token registry first and fall back to the offer's own artwork, so `CheckoutAssetUi.fromOffer` takes the offer's `TokenMetadata | null` alongside it. This affects hosts composing their own checkout viewmodel from the step-level hooks; pass `null` to keep the previous behavior.

### Added

#### The Ondo sell flow

A complete sell checkout, mirroring buy. `CheckoutContainer` renders it when `config["ondo::swap"].side()` returns `"sell"` - no other host change is required.

| Rung | What ships |
| - | - |
| L3 | `OndoSellCheckoutContainer`, `OndoSellCheckoutView`, `OndoSellAmountView`, `OndoSellReviewView`, `OndoSellOrderConfirmed` |
| L2 | `useOndoSellCheckoutViewModel` and its `.types`, plus `useOndoSellAmountViewModel`, `useOndoSellReviewViewModel`, `useOndoSellTransaction` |
| L1 | `coinlist.ondo.prepareSell`, `coinlist.ondo.buildSellTransaction` |

A sale sells the **asset** and settles into USDC, so the approval is granted on the asset's contract. The SDK ships no registry entry for a provider's asset, so its address and decimals come off the sell quote and nowhere else.

See [Ondo Swap](/sdk/ondo-swap) for the whole flow.

#### `CheckoutWalletSelection.preselected`

A host that already knows the wallet can skip the wallet step: set `preselected` to a ready `EvmWallet` and the checkout opens on the amount, renumbering the cards that remain. A sell page reached from a position knows which wallet holds it, and asking again would be a question with one answer.

It lives on the wallet seam rather than in a provider's config because nothing about it is one provider's - but **only the Ondo sell checkout honors it today**, so do not assume a skip from the field being set.

#### Structured logging

The SDK can now report what it is doing. `Config` takes an optional `logger`, and **with none the SDK logs nothing at all** - no `console` fallback, at any level, on any codepath.

```tsx theme={null}
import { pinoClientLogger } from "@coinlist-co/react";

<CoinListProvider
  config={{ clientId, redirectUri, logger: pinoClientLogger({ isDev: true, level: "debug" }) }}
>
```

* **`Logger`** (from `@coinlist-co/react/universal`) is the port: `debug`, `info`, `warn`, `error`, and `level()`. Implement it over your own sink in four methods.
* **Two shipped implementations**, one per environment: `pinoClientLogger` from `@coinlist-co/react` and `pinoServerLogger` from `@coinlist-co/react/server`.
* **Every line is structured**: a constant `msg` naming what happened, a `scope` (`HTTP`, `OFFERS`, `ONDO`, `HOOKS`, …), and a bag of fields carrying every value that varies. Field names follow OpenTelemetry where a stable key exists.
* **Every event is a lambda**, checked against `level()` before it runs, so an expensive `debug` line costs nothing at `info` and nothing at all with no logger supplied.

> [!WARNING]
>
> **`'debug'` is unredacted.** It reports request and response bodies, full URLs, headers and operation parameters verbatim - bearer tokens, KYC answers, tax-document fields, wallet signatures. `info`, `warn` and `error` are redacted by construction: those levels accept scalar fields only, so a body or a DTO cannot be put on one. Built with `isDev: false`, `'debug'` does not typecheck. The SDK's advice is to leave `logger` undefined in production entirely.

`pino ^10` is a new runtime dependency and does not tree-shake: every integration pays roughly 3 kB gzipped whether or not it logs.

#### Base mainnet and Base Sepolia

`EthereumChain` gains `base_mainnet` (8453) and `base_sepolia` (84532), with chain ids, network names, explorers, and Base USDC and USDT in the token registry. Adding a chain is a deliberate compile error until every lookup table has an entry, so a host switching on `EthereumChain` exhaustively will need two more arms.

No provider has a swap contract deployed on Base, so an Ondo or Superstate checkout there renders the `unsupported-chain` state.

#### Smaller additions

* **`coinlist.tokens.list(chain?)`** fetches the registry's complete snapshot in a single request - every chain with no argument, one chain with it. Prefer it over `get()` in a loop when rendering a catalog. Unlike `get`, a missing snapshot throws rather than answering `[]`.
* **`Offer.tokens` and `OfferDetail.tokens`**, the `(chain, address)` entries an offer's assets live at, keyed by role.
* **`OffersAssetGrid`**, a responsive browse grid of `OfferAssetCard` leaves. Pure - no fetch, no provider - and distinct from `OffersGridView`, which lays out sale cards.
* **`useErc20Balance`**, the address-keyed counterpart to `useErc20TokenBalances`, for a token whose contract address arrives at runtime and has no registry symbol to look up.
* **`useCheckoutOfferTokenMetadata`**, which keys the registry lookup by the offer's token entry for the checkout chain.
* **`OndoCheckoutError`** and `OndoCheckoutErrorReason`, the flow-level error surface both Ondo products share.
* **Release candidates on npm.** Every merge to `main` now publishes `<next-patch>-rc.<short-sha>` under the `rc` dist-tag, so a fix can be tried before it is tagged: `npm install @coinlist-co/react@rc`.

### Changed

* **Checkout asset logos resolve from the token registry first**, taking the vector logo or the smallest raster variant covering the render width, and falling back to `Offer.logoUrl` and then a neutral placeholder. Every absence - loading, error, disabled, unlisted, no token entry - falls back rather than rendering a broken image.
* **An Ondo checkout on a chain with no contract now fails at the flow level**, before any step runs. It previously displayed a `0` balance for a token the flow would never spend and refused on Confirm, as though the amount were the problem.
* **`useTokenMetadata` moved** from the tokens feature to the shared hooks, now that checkout is its second consumer. The import path is unchanged: it is still exported from `@coinlist-co/react`.
* **`lucide-react` is now `^1`** (from `^0.577`). It is a bundled dependency, not a peer, so no host action is needed.

### Fixed

* **An offer token on a chain the SDK does not model no longer blanks the offers list.** One Base token took down the whole catalog: `Offer.fromDto` runs inside the paginated response's `map`, so one unparseable item threw away the page. Unknown chains are now skipped, costing that token its logo.
* **The Ondo amount step no longer strands the user when a quote expires while an error is showing.** The refresh action is reachable from that state.
* **The Ondo amount input reads `USDC` with a `max` affordance**, matching the Superstate checkout.

### Removed

* **`identity_verified`, `proof_of_address` and `source_of_funds`** are gone from `RequirementType`. They were left over from an abandoned modular-KYC effort and the backend no longer returns them, so a `switch` over requirement types needs three fewer arms.

**v0.11.0**

August 25, 2026 - Namespaced client and server surfaces, the Ondo buy flow, a drop-in CheckoutContainer, and token metadata

This is the largest release since the SDK went out, and almost every call site changes. It finishes the namespace migration v0.10.0 started, splits every component with behavior into a `Container` / `View` pair, adds a second swap provider (Ondo) with a complete checkout UI, and introduces `CheckoutContainer` so a host can render any offer type without knowing which provider is behind it.

Nothing below changes behavior. Parameters and return types are unchanged unless a row says otherwise.

### Breaking Changes

#### Every remaining flat method moved into a namespace

`CoinListClient` and `CoinListServer` now expose nothing but namespaces. `init()` is the single exception on the client, because it is lifecycle rather than domain; `CoinListServer` has no top-level member at all.

**Client**

| Before | After |
| - | - |
| `coinlist.getAuthState()` | `coinlist.auth.getState()` |
| `coinlist.startOAuth()` | `coinlist.auth.startOAuth()` |
| `coinlist.completeOAuth()` | `coinlist.auth.completeOAuth()` |
| `coinlist.logout()` | `coinlist.auth.logout()` |
| `coinlist.fetchOffers()` | `coinlist.offers.list()` |
| `coinlist.fetchOffersPage(params)` | `coinlist.offers.listPage(params)` |
| `coinlist.fetchOfferDetails(id)` | `coinlist.offers.get(id)` |
| `coinlist.fetchOfferRequirements(offerId)` | `coinlist.requirements.forOffer(offerId)` |
| `coinlist.fetchRequirementStatuses(offerId)` | `coinlist.requirements.statuses(offerId)` |
| `coinlist.fetchPii()` | `coinlist.requirements.getPii()` |
| `coinlist.submitDocument(documentType, fields)` | `coinlist.requirements.submitDocument({ documentType, fields })` |
| `coinlist.createKycToken(levelName, reset)` | `coinlist.requirements.createKycToken({ levelName, reset })` |
| `coinlist.handleRequirement(requirement)` | `coinlist.requirements.handle(requirement)` |
| `coinlist.createWalletOwnershipChallenge(params)` | `coinlist.wallets.createOwnershipChallenge(params)` |
| `coinlist.connectExternalWallet(offerId, params)` | `coinlist.wallets.connectExternal({ offerId, ...params })` |
| `coinlist.listOptionAddresses(offerId, offerOptionId)` | `coinlist.wallets.list({ offerId, offerOptionId })` |
| `coinlist.removeOptionAddress(offerId, addressId)` | `coinlist.wallets.remove({ offerId, addressId })` |
| `coinlist.contactSupport()` | `coinlist.support.contact()` |

**Server**

| Before | After |
| - | - |
| `coinlist.completeOAuth(code, codeVerifier)` | `coinlist.auth.completeOAuth({ code, codeVerifier })` |
| `coinlist.accessToken()` | `coinlist.auth.getAccessToken()` |
| `coinlist.clientCredentialsOAuth()` | `coinlist.auth.clientCredentials()` |
| `coinlist.logout()` | `coinlist.auth.logout()` |
| `coinlist.fetchOffers(clientCreds?)` | `coinlist.offers.list(clientCreds?)` |
| `coinlist.fetchOffersPage(params, clientCreds?)` | `coinlist.offers.listPage(params, clientCreds?)` |
| `coinlist.fetchOfferDetails(id, clientCreds?)` | `coinlist.offers.get(id, clientCreds?)` |
| `coinlist.fetchOfferRequirements(offerId, clientCreds?)` | `coinlist.requirements.forOffer(offerId, clientCreds?)` |
| `coinlist.fetchRequirementStatuses(offerId)` | `coinlist.requirements.statuses(offerId)` |
| `coinlist.fetchPii()` | `coinlist.requirements.getPii()` |
| `coinlist.submitDocument(documentType, fields)` | `coinlist.requirements.submitDocument({ documentType, fields })` |
| `coinlist.createKycToken(levelName, reset)` | `coinlist.requirements.createKycToken({ levelName, reset })` |
| `coinlist.createWalletOwnershipChallenge(params)` | `coinlist.wallets.createOwnershipChallenge(params)` |
| `coinlist.connectExternalWallet(offerId, params)` | `coinlist.wallets.connectExternal({ offerId, ...params })` |
| `coinlist.listOptionAddresses(offerId, offerOptionId)` | `coinlist.wallets.list({ offerId, offerOptionId })` |
| `coinlist.removeOptionAddress(offerId, addressId)` | `coinlist.wallets.remove({ offerId, addressId })` |

**Migration:** insert the namespace before the method name, and pass a single object to any method that used to take more than one argument.

```ts theme={null}
// Before
const offers = await coinlist.fetchOffers();
const detail = await coinlist.fetchOfferDetails(offers[0].id);
const addresses = await coinlist.listOptionAddresses(offerId, offerOptionId);

// After
const offers = await coinlist.offers.list();
const detail = await coinlist.offers.get(offers[0].id);
const addresses = await coinlist.wallets.list({ offerId, offerOptionId });
```

```ts theme={null}
// Before, on your backend
await coinListServer(response).completeOAuth(AuthorizationCode(code), CodeVerifier(codeVerifier));
const token = await coinListServer(response).accessToken();

// After
await coinListServer(response).auth.completeOAuth({
  code: AuthorizationCode(code),
  codeVerifier: CodeVerifier(codeVerifier),
});
const token = await coinListServer(response).auth.getAccessToken();
```

#### `coinlist.swap` is now `coinlist.superstate`

A second swap provider shipped in this release, so a namespace called `swap` could only ever mean one of them. Provider namespaces are named after the provider; CoinList's own namespaces stay named after what they do.

| Before | After |
| - | - |
| `coinlist.swap.executeSwap(params)` | `coinlist.superstate.execute(params)` |
| `coinlist.swap.authorizeWallet(params)` | `coinlist.superstate.authorizeWallet(params)` |
| `coinlist.swap.getPreview(params)` | `coinlist.superstate.getPreview(params)` |
| `coinlist.swap.getAuthorization(params)` | `coinlist.superstate.getAuthorization(params)` |
| `coinlist.swap.getStatus(params)` | `coinlist.superstate.getStatus(params)` |
| `coinlist.swap.getOutputToken(params)` | `coinlist.superstate.getOutputToken(params)` |
| `coinlist.swap.allowWallet(params)` | `coinlist.superstate.allowWallet(params)` |
| `coinlist.swap.requestWalletOwnershipChallenge(params)` | `coinlist.wallets.createOwnershipChallenge(params)` |

**Migration:** replace `coinlist.swap.` with `coinlist.superstate.`, rename `executeSwap` to `execute`, and take the ownership challenge from `coinlist.wallets`. `authorizeWallet` keeps its name, its parameters, its phases, and its error steps.

```ts theme={null}
// Before
const result = await coinlist.swap.executeSwap({ wallet, contractAddress, chain, inputTokenAddress, quote, slippageBps });
// After
const result = await coinlist.superstate.execute({ wallet, contractAddress, chain, inputTokenAddress, quote, slippageBps });
```

#### Token-sale and ERC-20 methods dropped their stuttering prefixes

| Before | After |
| - | - |
| `coinlist.tokenSale.executeTokenSale(params)` | `coinlist.tokenSale.execute(params)` |
| `coinlist.tokenSale.fetchParticipations(offerId?)` | `coinlist.tokenSale.list(offerId?)` |
| `coinlist.tokenSale.fetchParticipationsPage(params)` | `coinlist.tokenSale.listPage(params)` |
| `coinlist.tokenSale.fetchParticipation(id)` | `coinlist.tokenSale.get(id)` |
| `coinlist.erc20.getTokenAllowance(params)` | `coinlist.erc20.getAllowance(params)` |
| `coinlist.erc20.getTokenBalance(params)` | `coinlist.erc20.getBalance(params)` |

`coinlist.tokenSale.createParticipation(params)` is unchanged.

#### `Offer.type` values changed

`OfferType` was `'sale' | 'swap'`. It is now `'coinlist::token_sale' | 'superstate::swap' | 'ondo::swap'`, so an offer names the provider that settles it rather than the shape of the transaction. Two providers now issue swap offers, and `'swap'` could not tell them apart.

| Before | After |
| - | - |
| `offer.type === 'sale'` | `offer.type === 'coinlist::token_sale'` |
| `offer.type === 'swap'` | `offer.type === 'superstate::swap'` or `'ondo::swap'` |

**Migration:** switch on the new values exhaustively rather than testing for one. A `default` branch that assumes "everything else is a token sale" now catches Ondo offers it cannot render.

```ts theme={null}
switch (offer.type) {
  case 'coinlist::token_sale': return <TokenSale offer={offer} />;
  case 'superstate::swap':     return <Swap offer={offer} />;
  case 'ondo::swap':           return <OndoBuy offer={offer} />;
}
```

> [!NOTE]
>
> If you render `CheckoutContainer` (below), you do not switch at all: it dispatches on `offer.type` for you, and a future offer type becomes a compile error in your `CheckoutConfig` rather than a blank screen.

#### Components split into `Container` and `View`

Every component that has behavior is now a `Container` (owns the props, calls the viewmodel) and a `View` (pure, driven by a state object). Both halves are exported, along with the viewmodel between them, so you can keep the SDK's logic and supply your own markup.

| Before | After |
| - | - |
| `<OffersGrid />` | `<OffersGridContainer />` |
| `<CoinListSignInCard />` | `<CoinListSignInCardContainer />` |
| `<RequirementsChecklist />` | `<RequirementsChecklistContainer />` |
| `<ConnectWalletModal />` | `<ConnectWalletModalContainer />` |
| `<IdentityVerification />` | `<IdentityVerificationContainer />` |
| `<TaxDocumentModal />` | `<TaxDocumentModalContainer />` |

**Migration:** append `Container` to the component name. Props are unchanged.

```tsx theme={null}
// Before
import { OffersGrid } from "@coinlist-co/react";
<OffersGrid maxColumns={3} onOfferClick={onOfferClick} />

// After
import { OffersGridContainer } from "@coinlist-co/react";
<OffersGridContainer maxColumns={3} onOfferClick={onOfferClick} />
```

`OfferCard`, `RequirementItem` and `ConnectedWalletList` are pure already and keep their names.

#### `useSwapTokenBalances` is now `useErc20TokenBalances`

Reading ERC-20 balances is not specific to a swap - the token sale and the Ondo buy flow need the same thing - so the hook moved out of the swap feature.

**Migration:** rename the import and the call. The options (`address`, `chain`, `assets`, `pollIntervalMs`, `enabled`) and the returned `{ balances, isLoading }` are unchanged. The poll-interval constant is now `ERC20_BALANCE_POLL_INTERVAL_MS`.

### Added

#### Ondo buy flow

Ondo is the SDK's second swap provider. `coinlist.ondo` covers the reads and the two halves of placing an order.

| Method | Endpoint |
| - | - |
| `coinlist.ondo.getTradingStatus({ symbol, side })` | `GET /v1/ondo/swap/trading-status` |
| `coinlist.ondo.getQuote({ symbol, side, tokenAmount \| notionalValue, duration? })` | `GET /v1/ondo/swap/quote` |
| `coinlist.ondo.buildSwapTransaction({ symbol, chain, walletAddress, amount })` | `POST /v1/ondo/swap/transaction` |

The wallet-driven half is client-only, and is deliberately two calls rather than one:

* `coinlist.ondo.prepareSwap({ wallet, symbol, chain, tokenAddress, amount, onProgress? })` submits the ERC-20 approval, then builds the transaction.
* `coinlist.ondo.executeSwap({ wallet, transaction, chain, now?, onProgress? })` broadcasts it.

> [!NOTE]
>
> Built calldata is only good for about a minute and an approval takes most of one to mine. Doing both behind a single button would hand the user an expired quote, so the SDK splits the flow where the user's decision is. Both calls are total: every failure comes back as `{ type: "error", error: { step } }` rather than throwing.

The reads are free to poll while the user sizes an order; `prepareSwap` is not, because building a transaction spends an attestation. No CoinList fee is applied to a read quote - `buildSwapTransaction` takes the gross amount and Ondo prices the remainder after the fee comes off.

Ondo runs no sandbox, so the read params take no `chain`: every environment prices against Ondo production on Ethereum mainnet. `buildSwapTransaction` is the exception, because it names a real contract on a real chain.

Also new: `ondoSwapContractAddress(chain)`, `ONDO_POLL_INTERVAL_MS`, `ONDO_QUOTE_EXPIRY_THRESHOLD_MS`, `ONDO_SUPPORTED_INPUT_ASSETS`, and `DEFAULT_ONDO_AMOUNT_TO_COMPUTE_PRICE`.

#### `CheckoutContainer`, a drop-in checkout for any offer type

`CheckoutContainer` switches on `offer.type` and renders the matching provider's checkout, so a host renders one component for every offer in its catalog.

```tsx theme={null}
import { CheckoutContainer, defaultCheckoutConfig } from "@coinlist-co/react";
import { AssetSymbol } from "@coinlist-co/react/shared";

const config = defaultCheckoutConfig({
  "ondo::swap": { symbol: (offer) => AssetSymbol(offer.asset.code) },
  "coinlist::token_sale": { render: (offer) => <MyTokenSalePage offer={offer} /> },
});

<CheckoutContainer offer={offer} chain="ethereum_sepolia" wallets={wallets} config={config} />
```

`CheckoutConfig` is keyed by `OfferType` with **every key required**, so a new offer type in the catalog breaks the build rather than rendering nothing. `defaultCheckoutConfig` fills in the entries that have a sensible default.

`wallets` is a `CheckoutWalletSelection`: the embedded wallets, the connected external one, and the two lambdas that connect and disconnect it. The SDK ships no wallet stack, so this is where you plug in Privy, AppKit, or your own.

> [!NOTE]
>
> `coinlist::token_sale` is a host render slot until the SDK ships that flow. The Ondo `symbol` resolver must be total: React hooks cannot be called conditionally, so every provider's viewmodel runs for every offer and the resolver is called for Superstate and token-sale offers too, where its answer is discarded. Return anything for an offer you do not recognize rather than throwing.

#### Superstate swap checkout UI

The Superstate swap UI moved into the SDK from the reference app: `SuperstateSwapCheckoutContainer` and `SuperstateSwapCheckoutView`, the step views (`SuperstateWalletView`, `SuperstateAmountView`, `SuperstateReviewView`, `SuperstateOrderConfirmed`, `SuperstateSidebarView`, `SlippagePicker`), and the viewmodels behind them.

Each product exposes a single god viewmodel wrapping the whole flow - `useSuperstateSwapCheckoutViewModel()`, `useOndoBuyCheckoutViewModel()` - **plus the smaller hooks it is composed from**, so you can write your own viewmodel against the same pieces.

#### Token metadata from the CoinList registry

`coinlist.tokens` resolves display metadata - name, symbol, decimals, and light and dark logos - keyed by `(chain, address)` rather than by symbol, which can collide.

| Method | Returns |
| - | - |
| `coinlist.tokens.get({ chain, address })` | `TokenMetadata`, or `null` when the registry has no entry |
| `coinlist.tokens.list(chain)` | Every token on a chain, in one request |

It is public and unauthenticated: unlike every other namespace, its methods never require a logged-in user, and it works on the server with a read-only session store. `useTokenMetadata({ chain, address, enabled })` is the hook form.

`OfferDetail` gained a `tokens` field carrying the `(chain, address)` pairs to look up. `TokenLogo` is `VECTOR` (one SVG) or `RASTER` (webp variants at 32-512px); pick the smallest variant that covers your render size.

> [!NOTE]
>
> `OfferToken.chain` is a `Chain`, which spans Solana as well as EVM, while `coinlist.tokens.get` takes an `EthereumChain`. Narrow before you look a token up - an offer may list a token on a chain the registry routes do not serve.

#### A global `locale` on `CoinListProvider`

```tsx theme={null}
<CoinListProvider config={config} locale="fr-FR">
```

A BCP-47 tag applied to number, date and currency formatting in every SDK component in the tree. Defaults to `'en-US'` - a fixed constant, never `navigator.language`, so server and client render the same markup. A plain string, so a Next.js server layout can pass `params.locale` straight through.

It does not reach embedded third-party flows: the Sumsub UI language stays on `RequirementsChecklistContainer#identityVerificationOptions.locale`.

#### `HttpError` and `apiErrorCode`

`HttpError` is now exported from both `@coinlist-co/react` and `@coinlist-co/react/shared`; `apiErrorCode` from `@coinlist-co/react/shared`. `HttpError` is what every API call rejects with when the backend refuses a request, so without it there is no way to catch a 4xx by type. `apiErrorCode(error)` reads the `code` out of the response body, which is what tells two 422s apart.

```ts theme={null}
import { apiErrorCode, HttpError } from "@coinlist-co/react/shared";

try {
  await coinlist.tokenSale.createParticipation(params);
} catch (error) {
  if (error instanceof HttpError) {
    switch (apiErrorCode(error)) { /* ... */ }
  }
}
```

#### Smaller additions

* `SolanaChain` (`'solana_mainnet' | 'solana_devnet'`) and `Chain`, the union of it with `EthereumChain`, both with validating constructors that throw `ValidationError` on an unknown value. Solana offers are not executable yet - this is the type surface an offer's tokens are parsed against, ahead of the `SolanaWallet` seam.
* `EvmSigner`, the signing-only half of `EvmWallet` (`address` + `signMessage`). The external-wallet ownership proof needs nothing more, so a host can satisfy that flow without implementing on-chain capabilities.
* `tokensBaseUrl` on `ClientConfig` and `ServerConfig`, to point `coinlist.tokens` at a non-production registry.
* `CoinListSignInButton`, the button on its own for hosts that do not want the card.
* `VerificationOverlay`, and every requirements viewmodel and `.types` module.
* `useOndoPrice`, `useOndoTradingStatus`, `useOndoSwapTransaction` for composing your own Ondo viewmodel.
* Formatting and presentation helpers: `useCountdown`, and the `asset-icon`, `date` and `duration` formatters.

### Changed

* **Requirements, offers and wallets are the same namespace on both sides.** `coinlist.offers`, `coinlist.requirements` and `coinlist.wallets` expose identical method names on `CoinListClient` and `CoinListServer`; the server adds an optional trailing `clientCreds` on the reads that can run without a user session, and the client adds `requirements.handle`.
* **Ondo reads live under `/v1/ondo/swap/*`** and take a required `side`. Ondo reports its limits per side, so a trading status fetched without one answers 422 rather than guessing `buy`.
* **`getQuote` refuses a request sized by both `tokenAmount` and `notionalValue`**, throwing `ValidationError`. TypeScript accepts an object carrying both, and the previous behavior silently dropped `notionalValue`.
* **`Participation`, `SwapQuote` and the other provider types moved modules** inside the package. They are still exported under the same names from `@coinlist-co/react/shared`, so only deep imports break - and deep imports were removed in v0.5.0.

### Removed

* `coinlist.swap.requestWalletOwnershipChallenge` - use `coinlist.wallets.createOwnershipChallenge`, which is the same call and is shared by the checklist and the allow-list flow.

**v0.10.1**

July 27, 2026 — Fix token-sale participation amount sent in the wrong units

### Fixed

#### Token-sale participations recorded the amount in the wrong units

`coinlist.tokenSale.executeTokenSale` recorded the participation with the raw base-unit amount (e.g. `"25000000"` for 25 USDC) instead of a decimal token amount (`"25"`). The participations API rescales the amount by the asset's decimals to check it against the on-chain approval allowance, so the base-unit value overflowed the approved allowance — the backend rejected every participation and funds failed to commit. `executeTokenSale` now records the decimal amount, so participations go through as expected.

If you drive the lower-level [`coinlist.tokenSale.createParticipation`](/sdk/invest-flow#reading-and-writing-imperatively) yourself, pass `amount` as a decimal token amount (e.g. `"100"` for 100 USDC), not raw base units. This has always been what the backend expects; only the `CreateParticipationParams.amount` doc comment was wrong, and it is now corrected.

**v0.10.0**

July 24, 2026 — Token-sale flow, erc20/tokenSale namespaces, and stricter offer models

### Breaking Changes

#### Participation methods moved to the `tokenSale` namespace

The flat participation methods on `CoinListClient` and `CoinListServer` now live under `coinlist.tokenSale`, mirroring how swaps sit under `coinlist.swap`.

| Before | After |
| - | - |
| `coinlist.fetchParticipations(offerId?)` | `coinlist.tokenSale.fetchParticipations(offerId?)` |
| `coinlist.fetchParticipationsPage(params)` | `coinlist.tokenSale.fetchParticipationsPage(params)` |
| `coinlist.fetchParticipation(id)` | `coinlist.tokenSale.fetchParticipation(id)` |
| `coinlist.createParticipation(params)` | `coinlist.tokenSale.createParticipation(params)` |

**Migration:** insert the `tokenSale` namespace before the method name. The parameters and return types are unchanged.

```ts theme={null}
// Before
const participations = await coinlist.fetchParticipations(offerId);
// After
const participations = await coinlist.tokenSale.fetchParticipations(offerId);
```

#### ERC-20 reads moved from `swap` to a new `erc20` namespace

`getTokenAllowance` and `getTokenBalance` are generic ERC-20 reads shared across the swap and token-sale flows, so they moved off `coinlist.swap` onto `coinlist.erc20`.

| Before | After |
| - | - |
| `coinlist.swap.getTokenAllowance(params)` | `coinlist.erc20.getTokenAllowance(params)` |
| `coinlist.swap.getTokenBalance(params)` | `coinlist.erc20.getTokenBalance(params)` |

**Migration:** replace `swap.getTokenAllowance` with `erc20.getTokenAllowance` and `swap.getTokenBalance` with `erc20.getTokenBalance`. The endpoints and parameters are unchanged.

#### `Offer.endsAt` and `OfferDetail.endsAt` are now nullable

An offer can legitimately have no end date, so `endsAt` is now `Date | null` (was `Date`). `fromDto` maps a missing end date to `null`.

**Migration:** handle the `null` case when reading `endsAt`.

```ts theme={null}
// Before — endsAt was always a Date
const label = offer.endsAt.toLocaleDateString();
// After — endsAt may be null
const label = offer.endsAt ? offer.endsAt.toLocaleDateString() : "No end date";
```

### Added

#### Token-sale flow

A new `tokenSale` namespace encapsulates the on-chain invest flow, mirroring `executeSwap`. On the client, `coinlist.tokenSale.executeTokenSale()` runs a sale end-to-end against a connected `EvmWallet`:

```ts theme={null}
const result = await coinlist.tokenSale.executeTokenSale({
  wallet,
  offerId,
  offerOptionId,
  assetId,
  paymentTokenAddress,    // ERC-20 the user pays with (e.g. USDC/USDT)
  fundingContractAddress, // the approve() spender
  chain,
  amount,                 // BlockchainAmount, base units
  onProgress,             // optional phase callback
});
```

It reads the current allowance, submits an ERC-20 `approve()` for the sale amount (resetting a stale non-zero allowance to `0` first for USDT-style tokens), waits for it to mine, and records the participation with CoinList. Wallet connection and chain switching remain the host's responsibility. See [CoinList Token Sale](/sdk/invest-flow) for the end-to-end integration.

> [!NOTE]
>
> An `approve()` is submitted even when the existing allowance already covers the amount: the backend requires a fresh approval transaction hash on every participation and verifies it on-chain before confirming.

Failures are returned as typed, step-tagged errors rather than thrown. The reset-to-zero and the main approval are reported distinctly (`allowance-reset` / `allowance-reset-reverted` versus `approval` / `approval-reverted`) so you can tell which of the two wallet prompts the user rejected, and the approval hash is surfaced on a backend failure so recording can be retried without re-approving on-chain. New types: `ExecuteTokenSaleParams`, `TokenSaleExecutionPhase`, `TokenSaleExecutionError`, `TokenSaleExecutionResult`, and the shared `Erc20ApprovalError` (reused across the swap and token-sale flows).

#### `erc20` namespace

`coinlist.erc20` exposes the generic ERC-20 reads shared across on-chain flows:

| Method | Endpoint |
| - | - |
| `erc20.getTokenAllowance` | `GET /v1/token/allowance` |
| `erc20.getTokenBalance` | `GET /v1/token/balance` |

#### Offer type

`Offer` and `OfferDetail` now expose a `type` field (`OfferType`, one of `'sale'` or `'swap'`) so you can distinguish token-sale offers from swap offers. `OfferType` is exported from `@coinlist-co/react/shared`.

### Changed

#### Stricter offer models

Fields the backend now guarantees as non-null are typed as required (`string` instead of `string | null`):

* `Offer`: `tagline`, `bannerUrl`, `logoUrl`.
* `OfferDetail`: `tagline`, `bannerUrl`, `logoUrl`, `category`.

`OfferDetail.about` stays nullable. `OfferCard` now hides its "Ends" row when an offer has no end date.

**v0.9.0**

July 20, 2026 — Swap namespace, external-wallet connect, and KYC/tax/PII flows

This release folds in the 0.7.0 and 0.8.0 development versions.

### Added

#### Swap namespace

`client.swap` and `server.swap` wrap the swap, token, and wallet endpoints:

| Method | Endpoint |
| - | - |
| `swap.getOutputToken` | `GET /v1/swap/output-token` |
| `swap.getPreview` | `GET /v1/swap/preview` |
| `swap.getStatus` | `GET /v1/swap/status` |
| `swap.getTokenAllowance` | `GET /v1/token/allowance` |
| `swap.getTokenBalance` | `GET /v1/token/balance` |
| `swap.getAuthorization` | `GET /v1/wallet/authorized` |
| `swap.allowWallet` | `POST /v1/offers/{offer_id}/allow-wallet` |
| `swap.requestWalletOwnershipChallenge` | `POST /v1/wallet-ownership` |

On the client, the namespace also drives a caller-supplied wallet:

* `authorizeWallet({ wallet, offerId, contractAddress, chain, onProgress })` — proves wallet ownership and allow-lists it for a swap offer, with typed progress phases and a `success` / `error` result. Idempotent: returns success immediately if the wallet is already authorized.
* `executeSwap({ wallet, contractAddress, chain, inputTokenAddress, quote, slippageBps, onProgress })` — runs the full on-chain swap: status check, ERC-20 approval (with USDT-style allowance reset), swap submission, and confirmation. The confirmed output is decoded from the `Swapped` event.

`viem ^2` is a new peer dependency.

#### Swap hooks

* `useSwapOutputToken` — reads the swap contract's output token (the tokenized equity).
* `useSwapQuote` — polls a live quote (15s default), skipping until the output-token decimals and a valid amount are known.
* `useSwapTokenBalances` — polls the user's balance for one or more input assets.

#### Wallet abstraction

`EvmSigner` / `EvmWallet` interfaces plus typed `WalletError` classification — bring your own wallet stack (wagmi, viem, Privy, …). New phase and error types: `WalletAuthorizationPhase`, `WalletAuthorizationError`, `SwapExecutionPhase`, `SwapExecutionError`, `SwapExecutionResult`.

See [Superstate Swap](/sdk/swap-flow) for the end-to-end integration.

#### External wallet connect

Prove and bind an external wallet to an offer option:

* `createWalletOwnershipChallenge(params)` → `POST /v1/wallet-ownership`
* `connectExternalWallet(offerId, params)` → `POST /v1/offers/{offer_id}/addresses`
* `listOptionAddresses(offerId, offerOptionId)` → `GET /v1/offers/{offer_id}/addresses`
* `removeOptionAddress(offerId, addressId)` → `DELETE /v1/offers/{offer_id}/addresses/{id}`

UI: `ConnectWalletModal` and `ConnectedWalletList` (list, change, and remove bound wallets), with the `useConnectWallet` and `useOptionAddresses` hooks.

#### Identity, KYC, and tax documents

* `createKycToken(levelName?, reset?)` → `POST /v1/kyc-token` (Sumsub)
* `fetchPii()` → `GET /v1/pii`, pre-fill data for tax forms
* `submitDocument(documentType, fields)` → `POST /v1/documents/{document_type}/submission`
* Components `IdentityVerification` and `TaxDocumentModal`; hooks `useKycToken` and `useTaxDocument`.
* `handleRequirement` now resolves the `kyc_approved`, `identity_verified`, `proof_of_address`, `source_of_funds`, `accreditation`, `external_wallet`, `whitelisted_wallet`, `document`, and `jurisdiction` requirement types.

> [!NOTE]
>
> `identity_verified`, `proof_of_address`, and `source_of_funds` have since been removed from the API. The SDK still handles them, but offers no longer return them, so you do not need to write branches for those three.

#### App-level authentication

`CoinListServer.clientCredentialsOAuth()` performs the OAuth 2.0 `client_credentials` grant for app-level access without a user session. The server offer reads (`fetchOffers`, `fetchOffersPage`, `fetchOfferDetails`, `fetchOfferRequirements`) accept an optional `clientCreds` argument to use it.

#### Shared (`@coinlist-co/react/shared`)

* `BlockchainAmount` (with `add` / `sub`), `parseBlockchainAmount`, `formatAmount`, `computeSlip`, and the `Bps` newtype.
* Constants and helpers: `DEFAULT_SLIPPAGE_BPS`, `SLIPPAGE_OPTIONS_BPS`, `SWAP_POLL_INTERVAL_MS`, `SUPERSTATE_SWAP_CONTRACT_ADDRESS_SEPOLIA`, `TOKEN_REGISTRY`, `USDC_SYMBOL`, `txExplorerUrl`.
* Swap, KYC, PII, document-submission, and wallet-ownership types.

### Changed

#### `CoinListProvider` is safe to mount app-wide

The provider is now an alias of `CoinListContextProvider` and renders no DOM or styles. Components self-scope their styling through `CoinListStyleScope`, so mounting the provider high in your tree no longer affects the rest of the app.

**v0.6.0**

July 2, 2026 — Required approvalTransactionHash, stricter wallet type, CSS isolation

### Breaking Changes

#### `approvalTransactionHash` is required on `createParticipation`

`CreateParticipationParams` now requires `approvalTransactionHash` — the hash of the ERC-20 allowance transaction that precedes the participation. Submit the approval on-chain first, then pass its hash.

```ts theme={null}
await coinlist.createParticipation({
  offerId,
  offerOptionId,
  chain,
  walletAddress,
  amount,
  assetId,
  approvalTransactionHash, // ← now required
});
```

#### `WalletAddress` narrowed to `` `0x${string}` ``

`WalletAddress` is now the template-literal type `` `0x${string}` `` instead of `string`. Values that aren't `0x`-prefixed literals need validation or a cast at the boundary.

### Added

#### CSS isolation

SDK styles are isolated behind a prefixed Tailwind build with scoped provider injection, and context is separated from styling so the context functions can be used without pulling in SDK styles. This work completes in v0.9.0, where `CoinListProvider` becomes safe to mount app-wide.

#### `coinlist.co` support

Added first-class support for the `coinlist.co` environment.

**v0.5.1**

May 7, 2026 — Read-only SessionStore support

### Breaking Changes

#### `SessionStore.setSession` is now optional

`setSession` has been changed from a required method to an optional one (`setSession?`). This formalizes **read-only store** mode for execution contexts — such as Next.js Server Components — that can read cookies but cannot write them.

Previously the only workaround was a no-op `setSession: async () => {}`, which silently discarded refreshed sessions after consuming the refresh token over the network, effectively causing a silent logout. Omitting `setSession` is now the explicit, safe contract: the SDK skips token refresh entirely, making no network calls and consuming no refresh tokens.

**Migration:** if you currently pass a no-op `setSession`, remove it. If your store is writable, no change is needed.

```ts theme={null}
// Before — no-op workaround (caused silent logout bug)
createCoinListServer({
  sessionStore: {
    getSession: () => getServerSession(),
    setSession: async () => {}, // ← remove this
  },
});

// After — read-only store (safe, explicit)
createCoinListServer({
  sessionStore: {
    getSession: () => getServerSession(),
  },
});
```

### Added

#### `WritableSessionStoreRequiredError`

New error class exported from `@coinlist-co/react/server`. `completeOAuth()` and `logout()` throw this immediately when called on a read-only store (no `setSession`), before any network call is made.

### Fixed

#### No unnecessary network retries on expired tokens in read-only mode

Previously, when a request returned a 401 and the store was read-only, the SDK would retry the request with the same expired token — wasting a round-trip that always failed. The SDK now detects the read-only store and surfaces the 401 immediately without retrying.

**v0.5.0**

May 5, 2026 — API consistency, new /shared entry point, and Base\* component removal

### Breaking Changes

#### Client methods renamed: `fetchAll*` → `fetch*`

`fetchAllOffers` and `fetchAllParticipations` have been renamed on both `CoinListClient` and `CoinListServer` to drop the redundant `All` prefix.

| Before | After |
| - | - |
| `CoinListClient.fetchAllOffers()` | `CoinListClient.fetchOffers()` |
| `CoinListClient.fetchAllParticipations(offerId?)` | `CoinListClient.fetchParticipations(offerId?)` |
| `CoinListServer.fetchAllOffers()` | `CoinListServer.fetchOffers()` |
| `CoinListServer.fetchAllParticipations(offerId?)` | `CoinListServer.fetchParticipations(offerId?)` |

**Migration:** do a global find-and-replace in your codebase:

```
fetchAllOffers(    →  fetchOffers(
fetchAllParticipations(  →  fetchParticipations(
```

#### Hooks renamed: `useCoinList*` → `use*`

The `CoinList` infix has been dropped from all hook names and their associated option/result/reason types.

| Before | After |
| - | - |
| `useCoinListOffers` | `useOffers` |
| `UseCoinListOffersOptions` | `UseOffersOptions` |
| `UseCoinListOffersResult` | `UseOffersResult` |
| `useCoinListOfferDetails` | `useOfferDetails` |
| `UseCoinListOfferDetailsOptions` | `UseOfferDetailsOptions` |
| `UseCoinListOfferDetailsResult` | `UseOfferDetailsResult` |
| `useCoinListRequirements` | `useRequirements` |
| `UseCoinListRequirementsOptions` | `UseRequirementsOptions` |
| `UseCoinListRequirementsResult` | `UseRequirementsResult` |
| `useCompleteCoinListOAuth` | `useCompleteOAuth` |
| `UseCompleteCoinListOAuthOptions` | `UseCompleteOAuthOptions` |
| `CompleteCoinListOAuthFailureReason` | `CompleteOAuthFailureReason` |

**Migration:** rename the hook calls and any imported types. Example:

```tsx theme={null}
// Before
import { useCoinListOffers, useCoinListRequirements } from '@coinlist-co/react';
const { offersState } = useCoinListOffers({ serverOffers: data });

// After
import { useOffers, useRequirements } from '@coinlist-co/react';
const { offersState } = useOffers({ data });
```

#### SSR prop renamed: `serverOffers` / `serverData` → `data`

The SSR pre-fetch prop has been unified to `data` across all hooks and components that accept server-side data. The `RequirementsServerData` type is also renamed to `RequirementsData`.

| Before | After |
| - | - |
| `UseOffersOptions.serverOffers` | `UseOffersOptions.data` |
| `UseOfferDetailsOptions.serverData` | `UseOfferDetailsOptions.data` |
| `UseParticipationsOptions.serverData` | `UseParticipationsOptions.data` |
| `UseRequirementsOptions.serverData` | `UseRequirementsOptions.data` |
| `OffersGrid` prop `serverOffers` | `OffersGrid` prop `data` |
| `RequirementsChecklist` prop `serverData` | `RequirementsChecklist` prop `data` |
| `RequirementsServerData` type | `RequirementsData` type |

**Migration:** rename the prop/option to `data` wherever you pass pre-fetched server results.

#### `LoadRequirementsState` CONTENT shape: `requirementsByOptionId` → `requirements`

If you read the `CONTENT` state returned by `useRequirements` (or previously `useCoinListRequirements`) directly, the field name has changed.

```tsx theme={null}
// Before
if (requirementsState.type === 'CONTENT') {
  const byOption = requirementsState.requirementsByOptionId;
}

// After
if (requirementsState.type === 'CONTENT') {
  const byOption = requirementsState.requirements;
}
```

#### `Base*` components removed

`BaseOffersGrid`, `BaseOffersGridProps`, `BaseRequirementsChecklist`, and `BaseRequirementsChecklistProps` have been removed. The connected components (`OffersGrid`, `RequirementsChecklist`) now accept all the same customization props directly — including the optional `data` prop for pre-fetched server data — so there is no longer a need for a separate base variant.

**Migration:** replace `BaseOffersGrid` and `BaseRequirementsChecklist` usage with the main components and pass the same props directly.

#### Import paths restructured — new `@coinlist-co/react/shared` entry point

Sub-path exports (`/client`, `/client/hooks`, `/client/components`, `/client/core`) have been removed. The package now exposes three canonical entry points:

| Entry point | Contents |
| - | - |
| `@coinlist-co/react` | React client — components, hooks, `CoinListClient` |
| `@coinlist-co/react/server` | Node/SSR — `CoinListServer` |
| `@coinlist-co/react/shared` | **New** — isomorphic domain types (`Offer`, `Participation`, `Requirement`, errors, pagination, etc.) |

Domain types that were previously re-exported from both `@coinlist-co/react` and `@coinlist-co/react/server` are now the sole responsibility of `@coinlist-co/react/shared`. They remain re-exported from the client and server entry points as well, so most imports will continue to work without changes. However, if you were importing from the now-deleted sub-paths, update your imports:

```ts theme={null}
// Before (sub-path imports — no longer valid)
import { CoinListClient } from '@coinlist-co/react/client';
import { useOffers } from '@coinlist-co/react/client/hooks';

// After
import { CoinListClient, useOffers } from '@coinlist-co/react';
```

#### `OffersGridProps` type renamed from `Props`

The exported type for `OffersGrid` props was the generic name `Props`. It is now exported as `OffersGridProps`.

```ts theme={null}
// Before
import type { Props } from '@coinlist-co/react';

// After
import type { OffersGridProps } from '@coinlist-co/react';
```

**v0.4.0**

April 30, 2026 — SSR data fetching, useParticipations hook, and requirement action defaults

### Added

#### Server (`@coinlist-co/react/server`)

* `CoinListServer` now exposes the full data-fetching surface previously only available on `CoinListClient`: `fetchAllOffers()`, `fetchOffersPage()`, `fetchOfferDetails()`, `fetchAllParticipations()`, `fetchParticipationsPage()`, `fetchParticipation()`, `createParticipation()`, `fetchOfferRequirements()`, and `fetchRequirementStatuses()`. Use these in Next.js Route Handlers and Server Components without shipping any client bundle.
* `@coinlist-co/react/server` now re-exports all shared types — `Offer`, `OfferDetail`, `Participation`, `Requirement`, `RequirementStatusInfo`, pagination helpers, `NotAuthenticatedError`, and related types — so you no longer need to import them from the client entry.

#### Client (`@coinlist-co/react`, `@coinlist-co/react/client`)

* `useParticipations(offerId?)` hook — loads all participations for the authenticated user with a `LOADING / CONTENT / ERROR` state machine, optionally filtered by offer. New exported types: `UseParticipationsResult`, `LoadParticipationsState`, `LoadParticipationsReason`.
* `handleRequirement(requirement)` on `CoinListClient` — opens the corresponding CoinList page for completing a requirement in a new tab (`/verify-identity`, `/wallet`, etc.). No-op for `jurisdiction` requirements.
* `contactSupport()` on `CoinListClient` — opens the CoinList support ticket page in a new tab.

### Changed

#### Components

* `RequirementsChecklist`: `onRequirementAction` and `onContactSupport` props have been renamed to `onRequirementActionOverride` and `onContactSupportOverride`. Both now **default** to `CoinListClient#handleRequirement` and `CoinListClient#contactSupport` respectively, so most integrations can omit them entirely. Pass `null` to disable the corresponding button/link.
* `RequirementItem`: `onAction` and `onContactSupport` now accept `null` (in addition to `undefined`) to suppress rendering of action buttons.

### Removed

#### Client (`@coinlist-co/react`, `@coinlist-co/react/client`)

* `sandbox` option removed from `ClientConfig`. Sandbox offers are no longer toggled via the SDK config.
* `StaticRequirementsChecklistProps` type removed. Use `RequirementsChecklist` with the connected API or `BaseRequirementsChecklist` for fully custom rendering.

**v0.3.0**

April 23, 2026 — Requirements API, sandbox mode, and participations filtering

### Added

#### Client (`@coinlist-co/react`, `@coinlist-co/react/client`)

* `fetchOfferRequirements(offerId)` on `CoinListClient` — returns requirements grouped by option ID (`Record<OfferOptionId, Requirement[]>`).
* `fetchRequirementStatuses(offerId)` on `CoinListClient` — returns the authenticated user's status for each requirement.
* `useCoinListRequirements(offerId)` hook for loading requirements and statuses with a `LOADING / CONTENT / ERROR` state machine.
* `sandbox` option on `ClientConfig` — when `true`, passes `sandbox=true` to offers API calls so sandbox offers are included.
* New exported types: `Requirement`, `RequirementId`, `RequirementType`, `RequirementStatusValue`, `RequirementStatusInfo`, `ParticipationsPaginationParams`.
* New exported enums/constants: `RequirementVariant`, `RequirementStatus`, `ChecklistStatus`.
* New hook types: `UseCoinListRequirementsResult`, `LoadRequirementsState`, `LoadRequirementsReason`.
* `fetchAllParticipations(offerId?)` and `fetchParticipationsPage(params)` now accept an optional `offerId` to fetch participations for a specific offer. `fetchParticipationsPage` takes the new `ParticipationsPaginationParams` type (superset of `PaginationParams`) which carries the `offerId` field.

### Fixed

#### Components

* Fixed missing dark mode CSS variables in Next.js projects — prebuilt styles now include the full set of design-system tokens so components render correctly under `dark` class or `prefers-color-scheme: dark`.

**v0.2.0**

April 13, 2026 — Participations API

### Added

#### Client (`@coinlist-co/react`, `@coinlist-co/react/client`)

* `fetchAllParticipations()` on `CoinListClient` for fetching all participations across pages.
* `fetchParticipationsPage()` on `CoinListClient` for paginated participation fetching.
* `fetchParticipation()` on `CoinListClient` for fetching a single participation by id.
* `createParticipation()` on `CoinListClient` for creating a new participation.
* New exported types: `Participation`, `ParticipationId`, `ParticipationStatus`, `CreateParticipationParams`, `Blockchain`, `WalletAddress`.

**v0.1.2**

April 8, 2026 — Support UI component customization

### Added

#### Client (`@coinlist-co/react`, `@coinlist-co/react/client`)

* Added support for passing `className` and `containerClassName` to `<OffersGrid />`, `<OfferCard />`, and `<CoinListSignInCard />`.

**v0.1.1**

April 7, 2026 — Publish missing exports

### Fixed

#### Client (`@coinlist-co/react`, `@coinlist-co/react/client`)

* Re-export offer, offer detail, and pagination types from the package root and client core entry so you can type against `Offer`, `OfferDetail`, pagination params, and related helpers without reaching into internal modules.
* Export `BaseCoinListSignInCard` and `BaseCoinListSignInCardProps` from `@coinlist-co/react/client` for custom sign-in layouts built on the same primitives as `CoinListSignInCard`.

**v0.1.0**

April 2026 — Offers UI and OAuth helpers

### Added

#### Client (`@coinlist-co/react/client`)

* `fetchAllOffers()`, `fetchOffersPage()`, and `fetchOfferDetails()` on `CoinListClient` for fetching offers data.
* `<OffersGrid />` — batteries-included component that loads offers and displays them in a responsive grid, with `<OfferCard />` for each tile.
* `useCoinListOffers()` hook for loading offers when you want full control over layout instead of the grid.
* `useCoinListOfferDetails()` hook for a single offer’s details.
* `useCompleteCoinListOAuth()` hook to run the OAuth redirect callback once on mount.
* Optional `authorizationPageUrl` on client config so you can point `startOAuth()` at a non-production authorization page.

**v0.0.1**

March 2026 — Initial release

### Added

#### Client (`@coinlist-co/react/client`)

* `CoinListProvider` and `useCoinList()` hook for React context-based SDK initialization.
* `createCoinListClient(config)` factory for manual or non-React usage.
* OAuth 2.0 with PKCE via `startOAuth()` and `completeOAuth()`.
* `getAuthState()` and `logout()`.

#### Server (`@coinlist-co/react/server`)

* `createCoinListServer(config)` factory for BFF / Next.js API routes.
* `completeOAuth()`, `accessToken()` (auto-refreshing), and `logout()`.

#### Components

* `CoinListSignInCard` and `CoinListSignInButton` for OAuth sign-in flows.
* `RequirementsChecklist` / `RequirementItem` — eligibility checklist with accordion UI.
* `PoweredByCoinList` attribution badge.
* Prebuilt CSS — no `tailwindcss` peer dependency required.

#### Infrastructure

* Subpath exports: `@coinlist-co/react`, `@coinlist-co/react/client`, `@coinlist-co/react/server`.
* Requires React 18+.


# Eligibility and compliance
Source: https://docs.passage.coinlist.co/eligibility-compliance

Passage runs KYC, eligibility, and ongoing screening so you can offer regulated assets without standing up a compliance function.

The short version: you do not have to worry about compliance but you still get to provide compliant assets and offerings.

## Who performs KYC?

Passage does. Users are taken through Passage KYC and AML screening as part of onboarding, run by a dedicated compliance team, covering KYC, KYB, accreditation checks, and jurisdiction-specific workflows. Issuers determine the requirements for each offering and Passage implements them. None of it lands on your engineering or compliance roadmap.

## Can eligibility requirements vary by offering?

Yes. Issuers configure eligibility per offering, including jurisdiction restrictions, KYC level, accreditation requirements, wallet requirements, and other conditions. Requirements also differ by asset category. Token sales have different rules than tokenized stocks.

Eligibility requirements can vary by issuer, asset, and jurisdiction, creating significant implementation and maintenance overhead. The Passage SDK does most of the work for you: Passage reads the requirements for the offering your user is interested in and walks them through exactly those steps, nothing extra. Your app never has to know what the rules are, or notice when an issuer changes them.

To read requirements and gate your invest flow on them, see [Fetch offers](/sdk/fetch-offers) and [Sale details](/sdk/sale-details).

## When is eligibility checked?

Before a user can invest. Passage checks each user against the requirements for that specific offering, and anyone ineligible or restricted is screened out before the transaction can complete.

Screening does not always stop at purchase. Some issuers require ongoing screening of allowlisted wallets, Superstate being one example, and Passage runs that monitoring. You don't need to perform additional compliance screening post-transaction. Where an offering calls for post-distribution checks, we handle those too.

## Do I need my own licenses to integrate Passage?

International adoption, clearer global regulatory frameworks, and targeted SEC relief in the U.S. have made it possible to offer access to digital asset securities, RWAs, cryptocurrencies, and other financial products on the same interface without blurring regulatory obligations. As a non-custodial service, Passage is designed to allow maximum flexibility for you and your app. Licensing obligations depend on your jurisdiction and your existing regulatory status, so treat this as a starting point rather than legal advice and talk to us early about your setup.

Passage was designed to help keep the regulatory weight off your build. Passage can support the most stringent regulated activity and everything down to unregulated offerings, so you can move quickly across the full spectrum.

> [!NOTE]
>
> CoinList does not provide investment, legal, or tax advice. Nothing in this documentation constitutes or should be construed as investment, legal, or tax advice, or as an investment recommendation.

## Does my existing KYC carry over?

If you already perform some form of identity verification, talk to us and we will see what options exist to accommodate your setup.

> **[Next: Wallets and chains](/wallets-chains)**
>
> Who controls the keys, which wallets you can support, and which chains are live.


# Offer onchain assets with one integration
Source: https://docs.passage.coinlist.co/index

Passage is an SDK that lets fintech platforms offer tokenized real-world assets, token sales, and other offerings to their users through a single integration.

It is built for digital wallets, neobanks, protocols, investment apps, and exchanges.

**You bring the app and the users. Passage brings the assets, the compliance, and all the plumbing in between.**

> **[Understand Passage](/what-is-passage)**
>
> Learn how the platform works before you integrate.

> **[Start building](/sdk/quickstart)**
>
> Jump into the SDK and ship your first flow.

> **[Stay compliant](/eligibility-compliance)**
>
> See what Passage takes on so your team does not have to.

## What does Passage solve?

Offering tokenized assets the hard way means signing up every issuer one at a time, then rebuilding KYC, eligibility, allowlisting, funding, and settlement for each of them. Passage does that work once, so you never have to do it at all.

| What you get | What it means |
| - | - |
| **One integration, a whole catalog** | Passage connects you to multiple tokenization platforms (Superstate, Ondo, WisdomTree, CoinList, with more coming). Every platform we add shows up for you with no extra build on your side. |
| **Compliance is our job, not yours** | Every issuer carries its own compliance, jurisdiction, disclosures, and eligibility requirements. Passage runs KYC, AML screening, accreditation, and jurisdiction checks, and tracks the requirements as issuers change them. You get to offer regulated assets and stay compliant without standing up a compliance function or repeating the work for each issuer. |
| **We take care of the unglamorous parts** | Allowlist registration, funding contracts, payments, settlement, distributions, and reporting all sit on our side of the line. |
| **A marketplace that keeps growing** | Instead of a single-source catalog, your users get an expanding, multi-platform selection of assets. You can pick and choose which assets and offerings to make available to your users, or offer everything. |

The result is one surface to build against instead of one per issuer. Individual issuers can still attach their own one-off requirements to an offering, and when they do, Passage walks your users through them inside the same flow.

## What can I offer my users?

| Category | What your users get |
| - | - |
| **Equities** | Tokenized US stocks and equity funds, including diversified exposure such as the S\&P 500, embedded natively in your app. |
| **Fixed income (yield)** | US Treasury funds, corporate credit, and CLOs (ETFs and mutual funds). |
| **Commodities** | Gold, silver, oil, and natural gas, as a single token. |
| **Token sales** | Access to token offerings run through CoinList. |
| **DeFi utility** | Allowlisted access to permissioned pools and lending markets, for example Uniswap V4 permissioned pools or Kamino lending pools. |

See [Asset catalog](/assets/catalog) for the live catalog.

## Am I the kind of company this is for?

Passage is built for consumer fintech platforms: digital wallets, neobanks, protocols, investment apps, and exchanges that want to offer regulated, tokenized financial products and assets to their users without building compliance and issuer infrastructure themselves. See [Eligibility and compliance](/eligibility-compliance).

## How do I start building?

Head to the [SDK quickstart](/sdk/quickstart).

> **[SDK quickstart](/sdk/quickstart)**
>
> Credentials, install, and your first offer.

> **[API reference](/api-reference)**
>
> REST endpoints for custom integrations.

> **[Contact sales](mailto:sales@coinlist.co)**
>
> Talk to us about your integration.

> **[Next: What is Passage?](/what-is-passage)**
>
> The three parties in an offer, the user journey, and who holds the money.


# Building the Checkout flow
Source: https://docs.passage.coinlist.co/sdk/checkout

Render CheckoutContainer with an offer, a chain and your wallets. It picks the right provider's flow for you.

`CheckoutContainer` is the **plug-and-play checkout**: hand it an offer and it renders whichever provider that offer belongs to. Superstate swap, Ondo buy, Ondo sell, CoinList token sale, Centrifuge deposit, Centrifuge redemption - you write one integration, not six.

This is the highest rung of the SDK (**L3, components**) and the one to start from. Reach for the hooks below it only when you need markup the SDK does not give you.

> [!NOTE]
>
> `CheckoutContainer` is the only checkout component the SDK exports. The per-provider containers it mounts are internal, so routing on `offer.type` is never your problem: when a new provider ships, `CheckoutContainer` renders it.

## Prerequisites

* A completed [OAuth](/sdk/oauth-authentication) session with a working `PassageProvider`
* An `OfferDetail` from [Display offer details](/sdk/sale-details)
* A [`CheckoutWalletSelection`](/sdk/wallets#checkoutwalletselection-what-checkout-takes) built from your wallet stack

## Render it

```tsx theme={null}
"use client";

import {
  CheckoutContainer,
  type CheckoutConfig,
  type CheckoutWalletSelection,
} from "@passage-cl/react";
import type { OfferDetail, OrderBookSide } from "@passage-cl/react/universal";

// Per-integration, not per-offer: build it once and pass the same object
// for every offer you render. Every key is optional.
const checkoutConfig: CheckoutConfig = {
  "ondo::swap": {
    onOrderConfirmed: (order) => {
      console.info("Ondo order mined", order.txHash);
    },
  },
};

export function Checkout({
  offer,
  wallets,
  side = "buy",
}: {
  offer: OfferDetail;
  wallets: CheckoutWalletSelection;
  side?: OrderBookSide;
}) {
  return (
    <CheckoutContainer
      key={`${offer.id}:ethereum_mainnet:${side}`}
      offer={offer}
      chain="ethereum_mainnet"
      side={side}
      wallets={wallets}
      config={checkoutConfig}
    />
  );
}
```

That is the whole integration. Only `offer`, `chain` and `wallets` are required: `<CheckoutContainer offer={offer} chain={chain} wallets={wallets} />` renders every provider on its defaults. The container is **self-scoped**: it renders fully styled with no style provider in the tree.

### Props

| Prop | Type | Required | Description |
| - | - | - | - |
| `offer` | `OfferDetail` | Yes | The offer being bought. Its `type` decides which provider renders. Read once, at mount. |
| `chain` | `EthereumChain` | Yes | Where the order executes: balance reads, the approval, and the broadcast all go here. Read once, at mount. |
| `wallets` | `CheckoutWalletSelection` | Yes | The wallets the buyer can spend from, your connector for an external one, and an optional `preselected` wallet. See [Wallets](/sdk/wallets) and [Wallets and the wallet step](#wallets-and-the-wallet-step). |
| `side` | `OrderBookSide` | No | Default `"buy"`. `"sell"` liquidates a holding instead of investing in it. Read once, at mount. See [`side`](#side-buy-or-sell). |
| `optionId` | `OfferOptionId` | No | Which option of a token sale is bought. Default: the offer's first option. Only token sales read it. Read once, at mount. |
| `config` | `CheckoutConfig` | No | Default `{}`. Per-provider callbacks, keyed by offer type. See [CheckoutConfig](#checkoutconfig). |
| `enabled` | `boolean` | No | Default `true`. `false` turns off every request and timer in the mounted provider, for a checkout that is mounted but not on screen yet. |
| `className` | `string` | No | Applied to the rendered provider view. |

## One mount, one offer, one chain

**To render a different offer, chain, side, option or preselected wallet, remount rather than reassign.** Give the container a `key` that changes with them, as the example above does. Add `wallets.preselected?.address` to the key if your preselection can change on one page.

`offer`, `chain`, `side`, `optionId` and `wallets.preselected` are read as fixed for the lifetime of the mount. Each provider's viewmodel owns a step machine - which wallet was authorized, how much is being spent - and that progress is bound to the order it was made against: a Superstate wallet authorization is allowlisted per offer, and an ERC-20 approval is granted per chain, for one specific token. Changing any of them in place would carry a completed step onto an order it was never made for. Worse, a swap could land mid-execution, between an approval and the broadcast it was granted for. So the container does not try: later values are ignored.

The rest of `wallets` stays live. A newly connected external wallet appears as a row without a remount.

React discards the old flow's state along with its component instance, which is the only reset that cannot strand an in-flight transaction.

## `side`: buy or sell

`side` is a prop rather than something the offer says, because no offer can answer it: `offer.type` is `ondo::swap` in both directions, and the direction is a property of your page rather than of the catalog. It is a prop rather than a config entry because it is per-*render*, while the config is per-integration, so one config object serves a buy page and a sell page.

| Offer type | `"buy"` (default) | `"sell"` |
| - | - | - |
| `ondo::swap` | The Ondo buy checkout | The Ondo sell checkout |
| `centrifuge::vault` | The vault deposit checkout | The vault redemption checkout |
| `superstate::swap`, `coinlist::token_sale` | Ignored: one direction only | Ignored |

A Centrifuge redemption is a request, not a sale. The user enters how many of the vault's shares to redeem, bounded only by what the wallet holds: the offer's dollar minimum applies to deposits only. The review approves the vault for that many shares, unless the allowance already covers them, and broadcasts the request. Placing it pays nothing yet. The fund fulfills the request later, and the user then claims the USDC in a second transaction, for example with `ClaimContainer`. A deposit works the same way in the other direction: the user claims the shares once the fund fulfills it.

> [!WARNING]
>
> **`side` is read once, at mount.** The flow below it holds an approval granted for whichever coin that side spends, so a re-render with a new `side` is ignored by design. A buy/sell toggle on one page works only if `side` is in the container's `key`. A forgotten `side` on a sell page renders the buy checkout.

Unmounting a checkout does not cancel an order already in flight. A Superstate swap, an Ondo swap or a token-sale order still goes through, and your `onOrderConfirmed` or `onOrderPlaced` callback still fires for it. A Centrifuge checkout unmounted while its approval mines broadcasts no request: the approval stays on-chain, no order is placed, and `onOrderPlaced` does not fire. Gate a toggle where it can reach an executing flow, for example by disabling it once the user is past the amount step.

## Wallets and the wallet step

`wallets` is a [`CheckoutWalletSelection`](/sdk/wallets#checkoutwalletselection-what-checkout-takes): `embedded`, `external`, an `externalAdapter` with `connect` and `disconnect`, and `preselected`. Set `externalAdapter` to `null` for a host with embedded wallets only. The external-wallet row is then hidden, unless `external` holds a connected wallet: that wallet still shows, with no way to disconnect it.

Every checkout runs the same three steps - wallet, amount, review - and every provider honors `wallets.preselected`:

| Provider | With `preselected` set |
| - | - |
| Ondo buy, Ondo sell, Centrifuge buy, Centrifuge sell, CoinList token sale | The wallet step is skipped. The flow opens on the amount, and the two remaining cards are numbered 1 and 2. After an order, the flow resets to the amount step. |
| Superstate | The wallet step stays, because it allowlists the wallet on-chain. It opens with the preselected wallet's row already selected. A wallet that matches no row (in neither `embedded` nor `external`) selects nothing. |

## CheckoutConfig

`CheckoutConfig` is keyed by `OfferType`, and **every key is optional**, as is the `config` prop itself. A provider you say nothing about runs on its defaults.

Nothing in the config is per-offer. It is per-*integration*, so you build one object and pass the same one for every offer you render. Anything the SDK can derive from the offer, it derives: Ondo's API symbol comes from `offer.asset.code`, and a token sale's funding contract, coins and price come off the offer.

| Key | Field | What you supply |
| - | - | - |
| `ondo::swap` | `onOrderConfirmed?: (order: OndoOrderPlaced) => void` | Optional. Fired once an Ondo swap has mined, either direction. The confirmation dialog shows regardless. |
| `superstate::swap` | `onOrderConfirmed?: (order: SuperstateOrderPlaced) => void` | Optional. Fired once a Superstate swap has mined. Superstate needs nothing else: the swap contract is looked up from the chain, and the funding assets are the provider's own constants. |
| `coinlist::token_sale` | `onOrderPlaced?: (order: TokenSaleOrderPlaced) => void` | Optional, `@alpha`. Fired once the participation is recorded. The order dialog shows either way. |
| `centrifuge::vault` | `onOrderPlaced?: (order: CentrifugeOrderPlaced) => void` | Optional, `@alpha`. Fired once a deposit or redemption request has mined. `order.side` (`"buy"` or `"sell"`) says which. The dialog shows either way. |

Use the callbacks to navigate, refresh a portfolio or log. The SDK already shows the confirmation.

## Token sales

`coinlist::token_sale` offers mount the SDK's own token-sale checkout: pick a wallet, enter an amount in USD paid in USDC or USDT, then review and place the order through `passage.tokenSale.execute`. The amount is checked against the option's minimum, and the amount and review steps are blocked outside the sale window.

Pass `optionId` to choose which option is bought; it defaults to the first. Some offers cannot take an order at all, and the checkout renders a "not available" screen in their place:

| Reason | When |
| - | - |
| `unsupported-chain` | The sale names no funding contract on `chain`. |
| `unknown-option` | `optionId` is not one of the offer's options. |
| `no-price` | The option has no fixed price, such as an auction. |
| `no-payable-asset` | The sale accepts no coin the SDK can pay with on `chain`. |

## What happens underneath

`CheckoutContainer` switches on `offer.type` and mounts only the matching provider's container, handing it the offer narrowed to its variant. Only that provider's viewmodel runs, so the others fetch nothing and hold no timers. `enabled` is forwarded to the mounted container as-is: it pauses a checkout that is mounted but not on screen yet.

The `switch` on `offer.type` is exhaustive, and its `default` branch assigns to `const exhaustive: never`, so a new offer type is a compile error inside the SDK until it has a branch.

> **Build your own UI with hooks (L2)**
>
> Each product exposes a **god viewmodel** wrapping its entire flow, plus the data hooks it is built from. Call one behind your own markup when you want the SDK's logic, state and error handling but not its UI.
>
> ```tsx theme={null}
> import {
>   type CheckoutWalletSelection,
>   useOndoBuyCheckoutViewModel,
> } from "@passage-cl/react";
> import type { OndoSwapOfferDetail } from "@passage-cl/react/universal";
>
> export function MyOndoBuyCheckout({
>   offer,
>   wallets,
> }: {
>   offer: OndoSwapOfferDetail;
>   wallets: CheckoutWalletSelection;
> }) {
>   const { state, onEvent } = useOndoBuyCheckoutViewModel({
>     offer,
>     chain: "ethereum_mainnet",
>     wallets,
>   });
>
>   // Render your own markup from `state`, and send user actions to `onEvent`.
>   return null;
> }
> ```
>
> | Viewmodel | `offer` |
> | - | - |
> | `useOndoBuyCheckoutViewModel`, `useOndoSellCheckoutViewModel` | `OndoSwapOfferDetail` |
> | `useSuperstateSwapCheckoutViewModel` | `SuperstateSwapOfferDetail` |
> | `useCoinListTokenSaleCheckoutViewModel` (`@alpha`, also takes `optionId`) | `CoinListTokenSaleOfferDetail` |
> | `useCentrifugeBuyCheckoutViewModel`, `useCentrifugeSellCheckoutViewModel` (`@alpha`) | `CentrifugeVaultOfferDetail` |
>
> Each takes `offer`, `chain`, `wallets`, `enabled?` and its provider's callback (`onOrderConfirmed` or `onOrderPlaced`), and returns `{ state, onEvent }`. `state` is a discriminated union you `switch` on exhaustively, with a flow-level `error` arm for an offer that has no checkout to render, such as one that cannot settle on the chain you passed. In the `content` arm of every flow except Superstate, `wallet` is `null` exactly when `preselected` skipped the wallet step.
>
> The step components and step viewmodels are not exported. A god viewmodel is the smallest unit of the SDK's checkout logic you can call.
>
> If you call these directly you are routing on `offer.type` yourself. Narrow the offer and call each viewmodel inside its own component, so only the matching one is mounted. That routing is exactly what `CheckoutContainer` does for you.
>
> Per-provider detail: [Superstate Swap](/sdk/swap-flow), [Ondo Swap](/sdk/ondo-swap), [CoinList Token Sale](/sdk/invest-flow). The conventions the hooks share - `enabled`, `data`, and the shape of `state` - are in [SDK structure](/sdk/structure#hooks).

> **Drive it yourself with the client (L1)**
>
> Below the hooks are plain TypeScript namespaces on `PassageClient`, with no React and no state. Use them for a non-React app, a custom state layer, or a step the SDK's flows do not cover.
>
> ```ts theme={null}
> const { passage } = usePassage();
>
> // Ondo: approve, then commit a firm quote, then broadcast it.
> // prepareBuy spends the funding coin; prepareSell delivers the asset.
> const prepared = await passage.ondo.prepareBuy(buyParams);
> const filled = await passage.ondo.executeSwap(swapParams);
>
> // Superstate: prove the wallet, then swap.
> await passage.superstate.authorizeWallet(authorizeParams);
> await passage.superstate.execute(superstateSwapParams);
>
> // CoinList token sale: approve and record a participation.
> await passage.tokenSale.execute(tokenSaleParams);
>
> // Centrifuge: approve, build and broadcast a request. buy approves USDC;
> // sell approves the vault's share token. The fund fulfills the request
> // later, and passage.centrifuge.claim collects the result.
> await passage.centrifuge.buy(depositParams);
> await passage.centrifuge.sell(redeemParams);
> ```
>
> These return **step-tagged results rather than throwing**, so you can map each failure to your own copy. The full parameters, progress phases and error steps live on each provider's page.

## Next steps

> **[Superstate Swap](/sdk/swap-flow)**
>
> Wallet allowlisting, live quotes, and what Superstate needs from you.

> **[Ondo Swap](/sdk/ondo-swap)**
>
> Both directions, what each one approves, and the two-call order.

> **[CoinList Token Sale](/sdk/invest-flow)**
>
> The approval, the participation, and tracking participations.

> **[Errors and edge cases](/sdk/errors)**
>
> Every error shape the flows return, and how to handle it.


# Errors and edge cases
Source: https://docs.passage.coinlist.co/sdk/errors

Every error shape the SDK flows return, what causes it, and how to handle it.

The SDK draws a line between two kinds of failure.

* **Flow-level failures** are expected outcomes. The on-chain flows (`passage.superstate.execute`, `passage.superstate.authorizeWallet`, `passage.tokenSale.execute`, `passage.ondo.prepareBuy`, `passage.ondo.prepareSell`, `passage.ondo.executeSwap`, `passage.centrifuge.buy`, `passage.centrifuge.prepareBuy`, `passage.centrifuge.sell`, `passage.centrifuge.prepareSell`, `passage.centrifuge.placeRequest`, `passage.centrifuge.claim`) and `passage.wallets.connect` return a tagged result rather than throwing, so you handle them with a branch, not a `catch`.
* **Thrown errors** are for genuinely exceptional conditions, such as calling an authenticated method without a session.

```tsx theme={null}
const result = await passage.superstate.execute(swapParams);

if (result.type === "success") {
  showReceipt(result.swapTxHash, result.outputAmount);
} else {
  handleSwapError(result.error); // result.error.step tells you where it stopped
}
```

## Wallet errors

`WalletError` is the shared vocabulary for anything the user's wallet does. It appears as the `cause` on any step that asked the wallet to sign or send.

| `type` | Meaning | Suggested handling |
| - | - | - |
| `user_rejected` | The user dismissed the wallet prompt. | Not an error state. Return the user to the previous step so they can retry. |
| `insufficient_funds` | The wallet's native token cannot pay the gas plus the transaction's `value`. A short ERC-20 balance does not produce this. | Tell the user what is short. Retrying without a top-up will fail again. |
| `contract_reverted` | The transaction reverted on-chain. Carries a `reason`: the contract's `require` string, panic description, custom error name or selector, or `null` when the revert carried no data. | Surface a generic message and log `reason`. Usually a stale quote or a failed eligibility check. |
| `timeout` | The receipt did not arrive in time. Carries the `hash`. | The transaction may still confirm. Link the user to an explorer with `hash` rather than prompting a resend. |
| `unknown` | Unclassified. Carries the original `cause`. | Show a generic error and log `cause`. |

The SDK classifies whatever your `EvmWallet` throws into a `WalletError` inside each flow, so you never classify one yourself. `WalletError` is exported from `@passage-cl/react/universal`.

### Sent but not confirmed

A swap or a request that the wallet sent but whose receipt wait then failed has its own step, with the transaction hash: `swap-unconfirmed` (Superstate and Ondo), `broadcast-unconfirmed` (Superstate wallet authorization) and `request-unconfirmed` (Centrifuge deposits and redemptions). The transaction may still mine, so sending it again can fill the order twice. Look up `txHash` before you offer a retry. The SDK's own checkouts disable the place-order button until the user leaves the step.

The plain `swap`, `broadcast` and `request` steps mean the wallet never sent the transaction, so retrying is safe. An ERC-20 approval has no unconfirmed step: `approve()` sets the allowance rather than adding to it, so a failed receipt wait is reported as `approval`, and sending it again cannot approve twice.

## Superstate swap errors

`passage.superstate.execute` returns `SwapExecutionError`, tagged by step.

| `step` | What happened |
| - | - |
| `status-check` | Reading the swap contract's status failed. |
| `swap-paused` | The swap contract has suspended swapping and may resume. Ask the user to try again shortly. |
| `swap-stopped` | The swap contract is permanently halted. The swap has closed. |
| `allowance-check` | Reading the current ERC-20 allowance failed. |
| `approval` | The ERC-20 approval did not complete: the user declined it, or its receipt wait failed. A failed reset to zero lands here too. Carries a `WalletError` cause. |
| `approval-reverted` | The approval transaction, or the reset before it, reverted on-chain. |
| `swap` | The wallet never sent the swap transaction, so swapping again is safe. Carries a `WalletError` cause. |
| `swap-unconfirmed` | The swap was sent but its receipt wait failed. Carries `txHash` and a `WalletError` cause. It may still mine, so look up `txHash` before swapping again. |
| `swap-reverted` | The swap transaction reverted on-chain. |

The wallet is only asked to sign after all read-only checks pass, so a user never signs a transaction the swap would revert on for a reason the SDK could have caught first.

## Token sale errors

`passage.tokenSale.execute` returns `TokenSaleExecutionError`.

| `step` | What happened |
| - | - |
| `unsupported-chain` | The offer names no funding contract on the requested chain. Returned before the wallet is asked for anything. |
| `unsupported-asset` | The offer does not accept `inputAsset` on that chain. Returned before the wallet is asked for anything. |
| `unknown-option` | The offer has no option with that `optionId`. Returned before the wallet is asked for anything. |
| `allowance-check` | Reading the current ERC-20 allowance failed. |
| `allowance-reset` | The user did not sign the reset to zero, or its receipt wait failed. Carries a `WalletError` cause. |
| `allowance-reset-reverted` | The reset transaction reverted on-chain. |
| `approval` | The ERC-20 approval did not complete: the user declined it, or its receipt wait failed. Carries a `WalletError` cause. |
| `approval-reverted` | The approval transaction reverted on-chain. |
| `participation` | The approval succeeded but recording the participation failed. Carries `approvalTxHash`. |

> [!WARNING]
>
> The `participation` step is the one to handle carefully. The user's funds are already approved on-chain, but the participation was not recorded. Keep `approvalTxHash` and retry with `approval: { type: "mined", txHash: approvalTxHash }`, which records the participation against that approval without prompting the wallet again.

### Allowance resets

Every flow that approves an ERC-20 resets a non-zero allowance to zero first. USDT-style tokens reject a non-zero to non-zero `approve()`, so the SDK resets before re-approving. This means those users see two wallet prompts instead of one, which is worth reflecting in your loading copy. The progress phases `resetting-allowance` and `confirming-allowance-reset` tell you when it happens.

Only the token sale reports a failed reset as its own step, `allowance-reset` or `allowance-reset-reverted`. The other flows report it as `approval` or `approval-reverted`. A token sale also approves on every new participation, even when the current allowance already covers the amount.

## Ondo swap errors

Placing an Ondo order is two calls, so it has two error types. `passage.ondo.prepareBuy` and `passage.ondo.prepareSell` both return `OndoSwapPreparationError` - every arm names a *remedy* rather than a direction, and an unsupported chain, a refused approval and a build that would not complete are fixed the same way whichever token was being approved.

| `step` | What happened |
| - | - |
| `unsupported-chain` | The offer names no CoinList swap contract on the requested chain. Carries the `chain`. Both Ondo checkouts surface this as a flow-level `error` state before any step runs. |
| `allowance-check` | Reading the current ERC-20 allowance failed. |
| `approval` | The ERC-20 approval did not complete: the user declined it, or its receipt wait failed. A failed reset to zero lands here too. Carries a `WalletError` cause. |
| `approval-reverted` | The approval transaction, or the reset before it, reverted on-chain. |
| `insufficient-allowance` | The approval mined, but the backend still reads a short allowance. Usually its RPC node lagging a block. **Retry, do not re-approve.** |
| `build-transaction` | Building the transaction failed. |

`passage.ondo.executeSwap` returns `OndoSwapExecutionError`, for either direction.

| `step` | What happened |
| - | - |
| `quote-expired` | The built calldata is at or past its deadline. Build a fresh transaction. |
| `swap` | The wallet never sent the swap transaction, so placing the order again is safe. Carries a `WalletError` cause. |
| `swap-unconfirmed` | The swap was sent but its receipt wait failed. Carries `txHash` and a `WalletError` cause. It may still mine, so placing the order again can fill it twice. Look up `txHash` first. |
| `swap-reverted` | The swap transaction reverted on-chain. |

> [!NOTE]
>
> `quote-expired` is a refusal to broadcast rather than a failure of a broadcast. It would revert on-chain and cost the user gas, and it is fixed by building a fresh transaction rather than by retrying the same one.

> [!NOTE]
>
> **`spender-mismatch` was removed in v0.12.0.** The spender now comes off the offer's `swapContracts`, and the backend compares the built transaction's destination to the contract it serves there, so a third comparison would check one source against itself. A wrong spender still surfaces, as `insufficient-allowance`.

### Closed markets

`passage.ondo.getQuote` throws an `HttpError` when the market is closed or paused, as it does for any refused request. The API answers that case with a 409 and the code `not_tradable`, and `isOndoNotTradableError(error)` from `@passage-cl/react/universal` recognizes it. Tell the user to come back when the market opens rather than offering a retry.

```ts theme={null}
import { isOndoNotTradableError } from "@passage-cl/react/universal";

async function loadQuote() {
  try {
    return await passage.ondo.getQuote(quoteParams);
  } catch (error) {
    if (isOndoNotTradableError(error)) {
      return showMarketClosed();
    }
    throw error;
  }
}
```

The Ondo hooks report the same case as the reason `not-tradable` (`OndoLoadErrorReason`). While the user is still on the step the flow opened on, both Ondo checkouts replace the flow with a "Trading is closed right now" screen until the market opens. Past that step, the amount step shows the block instead, so a closed market never takes an order dialog off the screen. The review step does not read the trading status: an order there can still be placed while its quote is valid.

## Centrifuge errors

> [!NOTE]
>
> Centrifuge is `@alpha`, outside the compatibility contract. Its error types can still change in a minor release.

### Preparing a request

`passage.centrifuge.prepareBuy` returns `CentrifugeBuyPreparationError` for a deposit, and `passage.centrifuge.prepareSell` returns `CentrifugeSellPreparationError` for a redemption. Both have the steps of `OndoSwapPreparationError` above, plus `build-refused`. `unsupported-chain` means the offer's `vaultContracts` names no proxy on that chain. A redemption approves the vault's share token, not the funding token, so its `approval` and `approval-reverted` steps are about the share token.

| `step` | What happened |
| - | - |
| `build-refused` | The API declined to build the request for a reason the user can act on. Carries a `reason` of type `CentrifugeRequestRefusal`, from the table below. |

| `reason` | API error code | What it means |
| - | - | - |
| `requirements-not-met` | `requirements_not_met` | The user has not completed the offer's requirements, such as KYC. Only deposits get it today. |
| `insufficient-balance` | `insufficient_balance` | The wallet holds less than the amount. |
| `direction-paused` | `deposit_paused`, `redeem_paused` | The vault proxy has paused this direction. It can resume, so ask the user to try again later. |
| `direction-stopped` | `deposit_stopped`, `redeem_stopped` | The vault proxy has stopped this direction for good. |
| `vault-refused` | `vault_refused_request` | Centrifuge itself would refuse the request. Try a different amount, or try again later. |
| `no-proxy-on-chain` | `no_proxy_on_chain` | The offer has no vault proxy on this chain. |

An `insufficient_allowance` code is `insufficient-allowance`, as for Ondo. Any other failed build is `build-transaction`. A wallet that the API's screening blocks has no error code yet, so it is `build-transaction` too.

### Placing a request

`passage.centrifuge.placeRequest` broadcasts a built deposit or redemption and returns `CentrifugeBuyPlacementError`. `passage.centrifuge.buy` runs both halves of a deposit and returns `CentrifugeBuyError`, which is either type. `passage.centrifuge.sell` does the same for a redemption and returns `CentrifugeSellError`.

| `step` | What happened |
| - | - |
| `request-expired` | The built request is stale, so the SDK did not send it. Either its deadline has passed, or the vault proxy refused its signature with an `Expired` or `Unauthorized` revert when the wallet simulated it. A claim between the build and the broadcast moves the wallet's nonce, which causes `Unauthorized`. Either way, placing the request again builds a fresh one. |
| `request` | The wallet never sent the request, so placing it again is safe. Carries a `WalletError` cause. |
| `request-unconfirmed` | The request was sent but its receipt wait failed. Carries `txHash` and a `WalletError` cause. It may still mine, so placing again can queue a second deposit or redemption. |
| `request-reverted` | The request transaction reverted on-chain. |

### Claiming

`passage.centrifuge.claim` returns `CentrifugeClaimError`. The SDK encodes the claim and sends it from the wallet itself, so no API request and no approval come first.

| `step` | What happened |
| - | - |
| `nothing-to-claim` | The vault proxy refused the claim with `InsufficientAmount`, because the wallet has nothing to claim: it was already paid. Do not retry, because a retry gets the same refusal. |
| `broadcast` | The wallet did not send the claim, for any other reason. Carries a `WalletError` cause. |
| `confirm` | The claim was sent but did not confirm. Carries a `WalletError` cause. A transaction that mined and reverted lands here with a `contract_reverted` cause whose `reason` is `null`. |

> [!NOTE]
>
> **v0.14.0 removed the claim's `prepare` step.** `nothing-to-claim` is now a step of its own, and the `frozen` and `generic` reasons are gone, because the SDK no longer asks the API to build a claim.

## Wallet authorization errors

`passage.superstate.authorizeWallet` returns `WalletAuthorizationError`. Like a swap, it splits a failed allow-list transaction into `broadcast` (never sent, safe to retry) and `broadcast-unconfirmed` (sent, carries `txHash`; look it up before authorizing again). See [Superstate Swap](/sdk/swap-flow#error-steps) for the full table and the progress phases.

## Wallet connection errors

`passage.wallets.connect` returns `{ type: "error", error }` with a `ConnectWalletFlowError`, which carries a `code` and a `retryable` flag. It returns `{ type: "cancelled" }` when its `isCancelled` callback abandoned the attempt. The `useConnectWallet` hook surfaces the same failure as a `ConnectWalletError`, which adds display copy in `message`. Respect `retryable` when deciding whether to offer a retry button.

| `code` | Meaning |
| - | - |
| `not_authenticated` | No CoinList session. Send the user through [OAuth](/sdk/oauth-authentication) first. Not retryable. |
| `user_rejected` | The user declined the signature request. |
| `wallet_not_whitelisted` | The wallet is not allowlisted for this offer. Not retryable. See [Superstate Swap](/sdk/swap-flow#step-3-allowlist-the-wallet). |
| `max_wallets_reached` | The user has already connected the maximum number of wallets for the offer option. Not retryable. |
| `unknown` | Unclassified. |

## OAuth errors

`useCompleteOAuth` fails with a `CompleteOAuthFailureReason`, which is either `complete_request_failed` or one of the client-side reasons below.

| Reason | Meaning |
| - | - |
| `user_canceled` | The redirect came back with an `error` parameter, usually because the user declined authorization. |
| `missing_state` | No `state` parameter came back on the redirect. |
| `invalid_state` | The returned `state` did not match the stored value, or no value was stored. Treat as a possible CSRF attempt and restart sign-in. |
| `missing_code` | No authorization code on the redirect. |
| `missing_code_verifier` | The stored PKCE verifier was gone, usually because storage was cleared mid-flow. |
| `complete_request_failed` | The code-for-token exchange against your backend failed: your `postOAuthComplete` resolved `false` or rejected. `useCompleteOAuth` also reports it when `passage.init()` rejects after the exchange, or your `onSuccess` throws. |

## Hook load errors

Data hooks report a failed read as an `ERROR` state with a `reason`: `not-authenticated` or `generic-error`. No retry helps `not-authenticated` until the user signs in. Offer a retry for `generic-error`.

The ERC-20 balance hooks, `useSwapQuote`, `useSwapOutputToken`, the Ondo and Centrifuge hooks and `useCoinListTokenSaleParticipations` use the shared `LoadErrorReason`. On these, `not-authenticated` covers both a `NotAuthenticatedError` and an HTTP 401, including the 401 from CoinList's JSON-RPC proxy that on-chain reads go through, so an expired session reads the same whichever request noticed it.

`useOffers`, `useOfferDetails`, `useRequirements` and `useOptionAddresses` declare their own reason types with the same two values. On these, `not-authenticated` means only a `NotAuthenticatedError` (no signed-in user), and an HTTP 401 reports `generic-error`.

The Ondo hooks widen it to `OndoLoadErrorReason`, which adds `not-tradable` for a closed market.

`useKycToken` reports its own `KycTokenErrorReason`, with the same two values: `not-authenticated` when there is no session, or `generic-error` for everything else.

## Thrown errors

Each error class has exactly one entry point. Import the universal ones (`NotAuthenticatedError`, `HttpError`, `ValidationError`, `InvariantError`, `MathError`, `NotImplementedError`, plus `apiErrorCode` and `isOndoNotTradableError`) from `@passage-cl/react/universal`. The main entry point does not re-export them. Because the package is ESM-only, every entry point shares one copy of each class, so `error instanceof HttpError` holds whichever entry point the failing call came from.

| Error | Entry point | When |
| - | - | - |
| `NotAuthenticatedError` | `/universal` | An API-backed method was called without a session. In the browser, the auth state is not `'logged-in'`. On a `PassageServer`, the session store has no session, or the session was rejected. When the server could not find out, because CoinList's token endpoint or the network failed, the method throws that underlying error instead. |
| `HttpError` | `/universal` | The API refused a request. Carries the `response`; read the body's error code with `apiErrorCode(error)`. `error.requestId` matches the SDK's `HTTP` log lines for the same request. |
| `ValidationError` | `/universal` | A value the SDK cannot accept. Examples: an Ondo quote sized by both `tokenAmount` and `notionalValue`, or by neither; an unrecognized chain string; a response from the backend in a shape the SDK does not understand. `createPassageClient` and `createPassageServer` also throw it when `Config.baseUrl` or `Config.tokensBaseUrl` is an empty or whitespace-only string, with the message `Config.baseUrl is empty. Omit it to use the default, or set a URL.` In React, that throw comes from rendering `PassageProvider`. Omit the field to use the production default. |
| `InvariantError` | `/universal` | The SDK computed something impossible, such as a value outside uint256 after its own arithmetic. Report it as an SDK bug. |
| `MathError` | `/universal` | An arithmetic operation had no answer, such as a division by zero or a result out of range, although every operand was well-formed. |
| `NotImplementedError` | `/universal` | Reserved for a code path that is not implemented yet. No public method throws it in this release. |
| `PassageClientInitializationError` | `@passage-cl/react` | `usePassage()` was called outside `PassageProvider`. Its message is `usePassage() must be used within PassageProvider. Wrap your app with <PassageProvider config={...}>.` |
| `WritableSessionStoreRequiredError` | `/server` | `auth.completeOAuth` or `auth.logout` was called on a `PassageServer` with a read-only session store. |

### Reading an API error code

`HttpError` is what every API call rejects with when the backend refuses a request, so it is the only way to catch a 4xx by type. Catching by type is half of it - telling two 422s apart takes the code inside the body, which is what `apiErrorCode` reads. Below, `insufficient_allowance` is the code `POST /v1/ondo/swap/buy` and `POST /v1/ondo/swap/sell` return when the wallet has not approved the swap contract for the amount. `prepareBuy` and `prepareSell` already absorb it into their `insufficient-allowance` step, so you only write this when you call a builder yourself.

```ts theme={null}
import { apiErrorCode, HttpError } from "@passage-cl/react/universal";

async function buildBuy() {
  try {
    return await passage.ondo.buildBuyTransaction(params);
  } catch (error) {
    if (error instanceof HttpError) {
      switch (apiErrorCode(error)) {
        case "insufficient_allowance":
          return showApprovalPrompt();
        default:
          return showGenericError();
      }
    }
    throw error;
  }
}
```

## Next steps

> **[Allowlist a wallet](/sdk/swap-flow#step-3-allowlist-the-wallet)**
>
> Wallet authorization, its phases, and its error steps.

> **[Package overview](/sdks)**
>
> Entry points and what each one exports.


# Fetch offers
Source: https://docs.passage.coinlist.co/sdk/fetch-offers

List Passage offers with OffersGridContainer, pre-fetch them on your server for SSR, and read token display metadata.

After [OAuth](/sdk/oauth-authentication), you can load every sale the current user can see and render them with the SDK - no hand-written HTTP integration for the common case.

## Prerequisites

* `PassageProvider` with working `getAccessToken` (session established on your backend)
* User signed in: your `getAccessToken` returns a non-null access token after OAuth (see [Set up OAuth authentication](/sdk/oauth-authentication))

## Recommended: OffersGridContainer

`OffersGridContainer` uses `useOffers` internally and renders a responsive grid of offer cards with loading, error, and empty states. It also loads CoinList's public token registry, so each card shows the registry's name and logo for the offer's token where the registry lists it, and the offer's own fields otherwise. The grid waits for both loads before it shows the cards, so each card paints once with its final artwork. If the registry fails to load, the cards fall back to the offer's own fields instead of showing an error.

The grid lists every offer type, including Centrifuge vaults (`centrifuge::vault`). An offer that runs no sale window, an Ondo swap or a Centrifuge vault, renders with no tagline and no countdown to an opening.

```tsx theme={null}
"use client";

import { OffersGridContainer } from "@passage-cl/react";

export function OffersSection() {
  return (
    <OffersGridContainer
      maxColumns={2}
      onOfferClick={(offer) => {
        // Navigate or open your detail route - offer.id is the API offer id
        console.log("Selected offer", offer.id);
      }}
    />
  );
}
```

Optional props:

* **`maxColumns`** - upper bound for the grid when space allows: `1` or `2` (default `2`; larger values are clamped to `2`)
* **`loading`**, **`error`**, **`emptyState`** - replace default slots with your own React nodes
* **`onOfferClick`** - when set, cards become interactive; omit for read-only lists
* **`data`** - `OffersGridData`, `{ offers?, tokens? }` pre-fetched on your server for SSR: `offers` from `passage.offers.list()`, `tokens` from `passage.tokens.list()` on `PassageServer`. Each half skips its own client-side request; pass both for a grid that makes no request of its own.
* **`enabled`** - default `true`. Pass `false` to mount the grid without fetching until it is needed.
* **`className`**, **`containerClassName`** - class names for the grid element and its outer wrapper

The grid's viewmodel and view are internal. For your own layout, such as a carousel, build it from `useOffers` and `useTokenRegistry` and render the public `OfferSaleCard` (or `OfferAssetCard`) yourself:

```tsx theme={null}
"use client";

import {
  OfferSaleCard,
  OfferSaleCardUi,
  useOffers,
  useTokenRegistry,
} from "@passage-cl/react";
import { TokenRegistrySnapshot } from "@passage-cl/react/universal";

export function OffersCarousel() {
  const { offersState } = useOffers();
  const { state: registryState } = useTokenRegistry();

  if (offersState.type !== "CONTENT") return null;
  const registry =
    registryState.type === "CONTENT" ? registryState.registry : null;

  return (
    <div style={{ display: "flex", gap: 16, overflowX: "auto" }}>
      {offersState.offers.map((offer) => (
        <OfferSaleCard
          key={offer.id}
          offer={OfferSaleCardUi.fromOffer(
            offer,
            registry ? TokenRegistrySnapshot.forOffer(registry, offer) : null,
          )}
        />
      ))}
    </div>
  );
}
```

## Server-side pre-fetch

The offer hooks and containers accept `data`. Pass it and the component **uses that data as-is and skips the initial client-side fetch** - the user sees offers in the first paint instead of a spinner.

This is the SSR path. Your Server Component calls `PassageServer`, and the browser renders with the answer already in hand:

```tsx theme={null}
// app/offers/page.tsx - a Server Component
import { OffersGridContainer } from "@passage-cl/react";
import { passageServerForRSC } from "@/lib/passage-server-readonly";

export default async function OffersPage() {
  const passage = passageServerForRSC();
  const [offers, tokens] = await Promise.all([
    passage.offers.list(),
    passage.tokens.list(),
  ]);

  return <OffersGridContainer data={{ offers, tokens }} maxColumns={2} />;
}
```

> [!NOTE]
>
> Use a **read-only** session store in Server Components: they can read cookies but not write them, so a writable store would silently consume a refresh token. See [read-only session stores](/sdk/oauth-authentication#read-only-session-stores-server-components).

The same prop exists on the hooks (`useOffers({ data })`, `useOfferDetails(id, { data })`, `useTokenRegistry({ data })`) and on the other data-backed containers, including `RequirementsChecklistContainer`. `useOffers` and `useOfferDetails` have no `refetch()`, so a seed replaces their fetch entirely. Where a hook exposes `refetch()`, the seed answers the initial render only - an explicit refetch still goes to the network.

`passage.offers.list()` on the server also takes an optional app-level token from `passage.auth.clientCredentials()`, so a public catalog page can render with no user session at all:

```tsx theme={null}
// app/catalog/page.tsx - a public Server Component
import { OffersGridContainer } from "@passage-cl/react";
import { passageServerForRSC } from "@/lib/passage-server-readonly";

export default async function CatalogPage() {
  const passage = passageServerForRSC();
  const offers = await passage.offers.list(
    await passage.auth.clientCredentials(),
  );

  // The seeded offers skip the grid's only authenticated request. The token
  // registry is public, so the grid still loads it with no session.
  return <OffersGridContainer data={{ offers }} />;
}
```

When a user session exists it takes precedence, and the app-level token is only a fallback.

## Going lower

Open these when you need custom layouts or non-React code.

> **Build your own UI with hooks (L2)**
>
> Use `useOffers` from `@passage-cl/react` when you want full control over markup but still prefer reactive loading state.
>
> The hook exposes `offersState`:
>
> * **`LOADING`** - provider not ready or request in flight
> * **`ERROR`** - `reason` is `not-authenticated` when no user is signed in (`NotAuthenticatedError`), and `generic-error` for any other failure
> * **`CONTENT`** - `offers` is every page of offers merged (same data as `passage.offers.list()`)
>
> `useOffers` has no `DISABLED` state: with `enabled: false` and no `data`, it stays `LOADING`. It also has no `refetch()`.
>
> ```tsx theme={null}
> "use client";
>
> import { useOffers } from "@passage-cl/react";
>
> export function CustomOffersLayout() {
>   const { offersState } = useOffers();
>
>   if (offersState.type === "LOADING") return <p>Loading…</p>;
>   if (offersState.type === "ERROR") return <p>Could not load offers.</p>;
>
>   return (
>     <ul>
>       {offersState.offers.map((offer) => (
>         // `Offer` is a union on `type`: an Ondo swap or a Centrifuge
>         // vault runs no sale window, so it has no `tagline` to read
>         // until you narrow.
>         <li key={offer.id}>
>           {offer.type === "coinlist::token_sale" ||
>           offer.type === "superstate::swap"
>             ? offer.tagline
>             : offer.slug}
>         </li>
>       ))}
>     </ul>
>   );
> }
> ```
>
> Pass `data` if you have server-fetched offers to hydrate from: `useOffers({ data })`. Pass `enabled: false` to skip the fetch while the list is not needed yet.

> **Drive it yourself with the client (L1)**
>
> Inside React you usually reach these through `usePassage()`:
>
> * **`passage.offers.list()`** - iterates every paginated page and returns all offers (throws `NotAuthenticatedError` if the user is not logged in)
> * **`passage.offers.listPage(params)`** - one page of API results when you implement your own pagination UI. Pass the previous response's `startingAfter` as `after` to advance.
>
> ```tsx theme={null}
> "use client";
>
> import { usePassage } from "@passage-cl/react";
> import { useEffect } from "react";
>
> export function OffersDebugLogger() {
>   const { passage, isReady } = usePassage();
>
>   useEffect(() => {
>     if (!isReady) return;
>     void passage.offers.list().then((offers) => {
>       console.log(offers.length);
>     });
>   }, [passage, isReady]);
>
>   return null;
> }
> ```
>
> For imperative, non-hook usage, create a `PassageClient` with `createPassageClient` from `@passage-cl/react`. Server code (Next.js Route Handlers, Server Components) should use the equivalent `passage.offers.list()` on `PassageServer` from `@passage-cl/react/server` instead - on the server it also takes an optional app-level token from `passage.auth.clientCredentials()`, so it can run with no user session.

> **Raw HTTP**
>
> The SDK calls the same API documented in the [API reference](/api-reference). Use raw HTTP only if you are not using React, or you need fields or flows the SDK does not expose yet. You still need a valid Bearer access token from your OAuth session.

## Token display metadata

Offers carry chain and address pairs in `offer.tokens`, but not the name, symbol, decimals or logo you need to render them. Those come from CoinList's public token registry through `passage.tokens`.

```tsx theme={null}
"use client";

import { useTokenMetadata } from "@passage-cl/react";
import type { TokenIdentifier } from "@passage-cl/react/universal";

export function TokenBadge({ chain, address }: TokenIdentifier) {
  const { state } = useTokenMetadata({ chain, address });

  if (state.type !== "CONTENT" || state.tokenMetadata === null) return null;
  const { symbol, logo } = state.tokenMetadata;

  return (
    <span>
      <img src={logo.kind === "VECTOR" ? logo.url : logo.original.url} alt="" />
      {symbol}
    </span>
  );
}
```

A `TokenMetadata` carries `identifier`, `name`, `symbol`, `decimals`, `logo` and `logoDark`. `logo` is a union: `VECTOR` is a single SVG `url`, while `RASTER` carries an `original` plus webp `variants` at 32 to 512px - pick the smallest variant that covers your render size, or `original` if none does.

`passage.tokens` is **the one unauthenticated namespace**: no method needs a logged-in user, and reads go to the registry's CDN rather than the CoinList API. It works with no session at all, and with a read-only server session store.

* **`passage.tokens.get(token)`** returns metadata for one token, or `null` when the registry does not list it. The registry is curated, so `null` is a normal answer: fall back to your own display defaults rather than treating it as an error.
* **`passage.tokens.list(chain?)`** returns every token the registry lists, in one request: one chain's snapshot when you pass a `chain`, or the complete snapshot when you omit it. The complete snapshot leaves out tokens on chains the SDK does not model. Prefer it over calling `get` in a loop when rendering a catalog - two hundred tokens is still a single snapshot download. A missing snapshot throws rather than returning `[]`, because its absence is a deployment problem and not an empty catalog.

`useTokenMetadata` takes `enabled` and `data` like the other data hooks, and exposes `refetch()`. A `data` of `null` is a valid seed meaning "not in the registry", and is distinct from leaving `data` undefined. Its state is `DISABLED`, `LOADING`, `ERROR` (always `generic-error`, because the registry is public) or `CONTENT`. With `enabled: false` and no answer in hand it reports `DISABLED`; a seeded or already-fetched answer survives being switched off. For a whole catalog, `useTokenRegistry` loads every token in one request and has the same states.

## Next step

> **[Display offer details](/sdk/sale-details)**
>
> Load the full `OfferDetail` for an id from the grid, which is what checkout takes.


# CoinList Token Sale
Source: https://docs.passage.coinlist.co/sdk/invest-flow

CoinList token sales: the SDK's token-sale checkout, recording a participation with passage.tokenSale.execute, and tracking participations afterwards.

CoinList supplies its own **token sales**. An offer arrives with `type: "coinlist::token_sale"`, and the user commits a stablecoin to buy into it. During the flow the user signs one ERC-20 `approve` to the sale's funding contract, and the SDK records a **participation** against that approval. CoinList takes it from there on its own clock: it verifies the approval, pulls the payment through the allowance in a batch, and allocates tokens and refunds any excess when the sale settles.

> [!NOTE]
>
> **Recommended:** render [`CheckoutContainer`](/sdk/checkout). It routes on `offer.type`, so your integration handles every provider without knowing which one an offer belongs to.

## What the token sale needs from you

**Nothing.** Since v0.13.0 `CheckoutContainer` mounts the SDK's own token-sale checkout (it used to hand this branch back to you through a required `render` slot, which is gone). The funding contract, the coins and the price are all read off the offer, so the `"coinlist::token_sale"` config entry is optional and takes one listener, `onOrderPlaced`, fired once the participation is recorded. The dialog shows either way. Which option the user buys is the `optionId` prop, which defaults to the offer's first option:

```tsx theme={null}
import { type CheckoutConfig, CheckoutContainer } from "@passage-cl/react";

const config: CheckoutConfig = {
  "coinlist::token_sale": {
    onOrderPlaced: (order) =>
      console.log("Participation recorded", order.participation.id),
  },
};

export function TokenSaleCheckout() {
  return (
    <CheckoutContainer
      key={`${offer.id}:${chain}:${optionId}`}
      offer={offer}
      chain={chain}
      optionId={optionId}
      wallets={wallets}
      config={config}
    />
  );
}
```

`optionId` is read **once, at mount**, like `chain` and `side`, so put it in the `key` if the user can switch options on one page. The token-sale entry and `useCoinListTokenSaleCheckoutViewModel` are `@alpha`: public, but outside the compatibility contract.

The checkout runs three steps:

1. **Wallet** - the shared wallet step. It is skipped when you set `wallets.preselected` (see [Wallets](/sdk/wallets#skipping-the-wallet-step)).
2. **Amount** - entered in USD and paid 1:1 in USDC or USDT, with balances and a Max button. It is checked against the option's minimum, and blocked outside the sale window, with a banner that says when the sale opens or that it ended.
3. **Review** - estimated tokens at the option's price, price per token, the receiving wallet and the total. The disclaimer links the option's sale agreement.

Placing the order runs `passage.tokenSale.execute`. On success the **Order placed** dialog opens, the steps reset, and `onOrderPlaced` is called with the wallet, amount, coin, participation, and approval hash. The quantity shown is an estimate: the sale decides each allocation when it settles.

If the approval mines but the participation fails to record, **Place order** records it again against that approval, with no second wallet prompt. Going back to an earlier step drops the approval, because a new amount needs one of its own.

A sale that cannot take an order on the checkout's chain renders an unavailable screen in place of the steps:

| Reason | When |
| - | - |
| `unsupported-chain` | The offer names no funding contract on `chain`. |
| `unknown-option` | `optionId` is not one of the offer's options, or the offer has none. |
| `no-price` | The option has no fixed price, such as an auction. Only fixed-price options can be bought. |
| `no-payable-asset` | None of the offer's funding assets is a coin the SDK can pay with on `chain`. |

> [!NOTE]
>
> The funding contract comes from the offer: `CoinListTokenSaleOfferDetail.fundingContracts`, one `{ chain, address }` per chain, mapped from the API's `funding_contracts`. An offer payload without that key fails mapping with a `ValidationError`. An empty list is valid and means the sale takes no orders anywhere.

The checkout does not check requirements such as KYC. Gate the page on [`RequirementsChecklistContainer`](/sdk/requirements) first, as for every other checkout.

## Prerequisites

* Completed [OAuth](/sdk/oauth-authentication) with a working `PassageProvider`
* A token-sale `OfferDetail` (`CoinListTokenSaleOfferDetail`) and the `OfferOption` the user picked (from [Display offer details](/sdk/sale-details))
* A wallet integration exposed as an `EvmWallet`. The partner demo uses [wagmi](https://wagmi.sh/) + [Reown AppKit](https://reown.com/appkit); any stack that can send transactions works. The adapter is the same one every flow uses - see [Wallets](/sdk/wallets).

```bash theme={null}
npm install @passage-cl/react wagmi @wagmi/core viem @reown/appkit @reown/appkit-adapter-wagmi @tanstack/react-query
```

> **Build your own UI with hooks (L2)**
>
> `useCoinListTokenSaleCheckoutViewModel({ offer, chain, wallets, optionId?, enabled?, onOrderPlaced? })` drives the whole checkout above and returns `{ state, onEvent }`. Call it behind your own markup when you want the SDK's logic and state but not its UI. `state` is `{ type: "error", reason }` for a sale that cannot take an order (the reasons in the table above), or `{ type: "content" }` with `wallet` (`null` when the wallet step was skipped), `amount`, `review`, `sidebar`, and `orderPlaced` slices.
>
> For reading what the user already bought, `useCoinListTokenSaleParticipations` is the data hook - see [Track participations](#track-participations) below. `useErc20TokenBalances` reads the user's stablecoin balances.
>
> For a buy flow of your own without the viewmodel, drive `passage.tokenSale.execute` from your component state. It is a single call that returns a step-tagged result, so there is little to hold beyond the amount and the current phase. The L1 walkthrough below shows exactly that.

> **Drive it yourself with the client (L1)**
>
> `passage.tokenSale` runs the whole flow end-to-end: it resolves the funding contract and the coin from the offer, reads the allowance, submits the ERC-20 `approve`, and records the participation, so you do not hand-roll the on-chain plumbing.
>
> ### Flow at a glance
>
> ```mermaid theme={null}
> flowchart LR
>   connect[connect_wallet]
>   idle[enter_amount]
>   investing[investing]
>   success[success]
>   error[error]
>
>   connect -->|wallet connected| idle
>   idle -->|user confirms amount| investing
>   investing -->|approve mined + recorded| success
>   investing -->|rejected / reverted| error
>   error -->|retry| idle
> ```
>
> 1. **connect\_wallet** - your wallet UI; the SDK only needs the connected account.
>
> 2. **enter\_amount** - the user picks a coin the offer accepts (`offerDetail.fundingAssets`) and enters an amount.
>
> 3. **investing** - `passage.tokenSale.execute` reads the allowance, runs the ERC-20 approval, and records the participation, reporting progress phases.
>
> 4. **success / error** - show the recorded participation, or a readable error.
>
> > [!NOTE]
> >
> > Unlike a Superstate swap, a token sale needs **no wallet allowlisting step** - there's no ownership challenge to sign. The user only signs the ERC-20 `approve`. CoinList moves the payment afterwards, through that allowance.
>
> ### Step 1: Pin the sale parameters
>
> Keep the chain and the coin in one place. `TOKEN_REGISTRY` knows the ERC-20 metadata and per-chain address for USDC and USDT. The funding contract is not a constant: `execute` reads it off the offer.
>
> ```ts constants.ts theme={null}
> import {
>   type EthereumChain,
>   TOKEN_REGISTRY,
>   USDC_SYMBOL,
> } from "@passage-cl/react/universal";
>
> export const SALE_CHAIN: EthereumChain = "ethereum_sepolia";
>
> // The stablecoin the user pays with (USDC, 6 decimals). It must be one of the
> // offer's funding assets.
> export const PAYMENT_ASSET = USDC_SYMBOL;
> export const PAYMENT_TOKEN = TOKEN_REGISTRY.erc20(PAYMENT_ASSET);
>
> // BCP-47 locale used for amount formatting.
> export const LOCALE = "en-US";
> ```
>
> > [!NOTE]
> >
> > This page runs on **Sepolia**. To move to mainnet, set `SALE_CHAIN` to `"ethereum_mainnet"`. The offer must name a funding contract on that chain, or `execute` refuses with `unsupported-chain` - `TOKEN_REGISTRY` already knows the mainnet USDC/USDT addresses.
>
> ### Step 2: Bring your wallet
>
> The token-sale flow drives **any** wallet through the same `EvmWallet` interface as every other flow. It only ever calls `address`, `writeContract`, and `awaitTx` - there is no message to sign - so an adapter you already wrote works unchanged.
>
> > **[Wallets: the EvmWallet seam](/sdk/wallets)**
> >
> > The five methods, the wagmi + AppKit adapter, and how wallet errors are classified.
>
> ```ts theme={null}
> import { buildEvmWallet } from "./wagmiEvmWallet";
> ```
>
> ### Step 3: Execute the sale
>
> `passage.tokenSale.execute` runs the whole on-chain sequence and returns a discriminated result. It never throws. Pass the offer itself: the funding contract, the coin's token address, and its asset id are all read off it. The `amount` is a `BlockchainAmount` in the coin's base units - parse the user's input with `parseBlockchainAmount`.
>
> ```tsx theme={null}
> const parsed = parseBlockchainAmount(amountInput, PAYMENT_TOKEN.decimals);
> if (!parsed.valid || parsed.amount.raw <= 0n) return;
>
> const result = await passage.tokenSale.execute({
>   wallet,
>   offer: offerDetail,     // the CoinListTokenSaleOfferDetail
>   optionId: option.id,    // the OfferOption the user picked
>   chain: SALE_CHAIN,
>   inputAsset: PAYMENT_ASSET,
>   amount: parsed.amount,
>   onProgress: (phase) => setBusy(phase),
> });
>
> if (result.type === "success") {
>   // result: participation, approvalTxHash
>   const explorerUrl = txExplorerUrl(SALE_CHAIN, result.approvalTxHash);
> } else {
>   // result.error.step: "unsupported-chain" | "unsupported-asset" | "unknown-option"
>   //   | "allowance-check" | "allowance-reset" | "allowance-reset-reverted"
>   //   | "approval" | "approval-reverted" | "participation"
>   setError("The investment did not go through.");
> }
> ```
>
> The first three steps are refusals before the wallet is asked for anything: the offer names no funding contract on the chain, does not accept the coin there, or has no option with that id.
>
> Phases (wallet popups marked):
>
> `checking-allowance` → *(`resetting-allowance` → `confirming-allowance-reset`, only when the wallet already holds a non-zero allowance)* → **`approving`** *(wallet popup)* → `confirming-approval` → `recording-participation`
>
> The reset, when it runs, is a transaction of its own and opens a wallet popup too.
>
> > [!NOTE]
> >
> > An `approve` is submitted on **every** participation, even when the existing allowance already covers the amount: the backend requires a fresh approval transaction hash and verifies it on-chain before recording. When the wallet already holds a non-zero allowance for the funding contract, `execute` first resets it to zero in a transaction of its own, whatever the coin, because USDT-style tokens reject a non-zero to non-zero `approve`. A failure there is reported as `allowance-reset` or `allowance-reset-reverted`, distinct from the main approval's `approval` and `approval-reverted`, so you can tell which of the two prompts failed.
>
> When recording fails after the approval mined (`error.step === "participation"`), the error carries the `approvalTxHash`. Retry against it with `approval: { type: "mined", txHash }`: `execute` then skips straight to `recording-participation` and asks the wallet for nothing. Use it only for the same amount, since a new amount needs a new approval.
>
> ```tsx theme={null}
> const retry = await passage.tokenSale.execute({
>   wallet,
>   offer: offerDetail,
>   optionId: option.id,
>   chain: SALE_CHAIN,
>   inputAsset: PAYMENT_ASSET,
>   amount: committedAmount,
>   approval: { type: "mined", txHash: approvalTxHash },
> });
> ```
>
> ### Putting it together
>
> A complete, minimal invest component. It reuses `constants.ts` (Step 1) and the `buildEvmWallet` adapter from [Wallets](/sdk/wallets). When recording fails after the approval mined, it keeps the approval hash and retries against it, until the user changes the amount.
>
> ```tsx MinimalInvest.tsx theme={null}
> "use client";
>
> import {
>   type TokenSaleExecutionPhase,
>   usePassage,
> } from "@passage-cl/react";
> import {
>   type CoinListTokenSaleOfferDetail,
>   EvmWalletAddress,
>   formatAmount,
>   type OfferOption,
>   parseBlockchainAmount,
>   txExplorerUrl,
> } from "@passage-cl/react/universal";
> import { useAppKit, useAppKitAccount } from "@reown/appkit/react";
> import { useState } from "react";
> import type { Hash } from "viem";
> import { useConfig, useWalletClient } from "wagmi";
> import { LOCALE, PAYMENT_ASSET, PAYMENT_TOKEN, SALE_CHAIN } from "./constants";
> import { buildEvmWallet } from "./wagmiEvmWallet";
>
> const GENERIC_ERROR = "Something went wrong. Please try again.";
>
> export function MinimalInvest({
>   offer,
>   option,
> }: {
>   offer: CoinListTokenSaleOfferDetail;
>   option: OfferOption;
> }) {
>   const { passage, isReady } = usePassage();
>   const { open } = useAppKit();
>   const { address, isConnected } = useAppKitAccount();
>   const { data: walletClient } = useWalletClient();
>   const config = useConfig();
>
>   const [amountInput, setAmountInput] = useState("");
>   const [busy, setBusy] = useState<TokenSaleExecutionPhase | null>(null);
>   const [error, setError] = useState<string | null>(null);
>   // An approval that mined for this amount while recording failed.
>   const [minedApproval, setMinedApproval] = useState<Hash | null>(null);
>   const [confirmed, setConfirmed] = useState<{ explorerUrl: string } | null>(
>     null,
>   );
>
>   const parsed = parseBlockchainAmount(amountInput, PAYMENT_TOKEN.decimals);
>   const hasAmount = parsed.valid && parsed.amount.raw > 0n;
>
>   const handleInvest = async () => {
>     if (!isReady || !walletClient || !address || !parsed.valid || !hasAmount) {
>       return;
>     }
>     setError(null);
>     try {
>       const wallet = buildEvmWallet({
>         address: EvmWalletAddress(address),
>         walletClient,
>         config,
>       });
>       const result = await passage.tokenSale.execute({
>         wallet,
>         offer,
>         optionId: option.id,
>         chain: SALE_CHAIN,
>         inputAsset: PAYMENT_ASSET,
>         amount: parsed.amount,
>         approval:
>           minedApproval === null
>             ? { type: "fresh" }
>             : { type: "mined", txHash: minedApproval },
>         onProgress: setBusy,
>       });
>       if (result.type === "success") {
>         setConfirmed({
>           explorerUrl: txExplorerUrl(SALE_CHAIN, result.approvalTxHash),
>         });
>       } else if (result.error.step === "participation") {
>         setMinedApproval(result.error.approvalTxHash);
>         setError("Your approval went through, but recording failed. Try again.");
>       } else {
>         setError(GENERIC_ERROR);
>       }
>     } catch {
>       setError(GENERIC_ERROR);
>     } finally {
>       setBusy(null);
>     }
>   };
>
>   if (confirmed) {
>     return (
>       <div>
>         <h3>Order placed</h3>
>         <p>Your participation in {offer.name} is being processed.</p>
>         <a href={confirmed.explorerUrl} target="_blank" rel="noreferrer">
>           View approval transaction
>         </a>
>       </div>
>     );
>   }
>
>   if (!isConnected || !address) {
>     return <button onClick={() => open()}>Connect wallet</button>;
>   }
>
>   return (
>     <div>
>       <input
>         inputMode="decimal"
>         placeholder={`Amount in ${PAYMENT_TOKEN.symbol}`}
>         value={amountInput}
>         onChange={(e) => {
>           if (e.target.value === "" || /^\d*\.?\d*$/.test(e.target.value)) {
>             setAmountInput(e.target.value);
>             // A new amount needs a new approval.
>             setMinedApproval(null);
>           }
>         }}
>       />
>
>       {parsed.valid && hasAmount && (
>         <p>
>           You invest {formatAmount(parsed.amount, LOCALE)} {PAYMENT_TOKEN.symbol}
>         </p>
>       )}
>
>       <button
>         onClick={handleInvest}
>         disabled={!isReady || !walletClient || !hasAmount || busy !== null}
>       >
>         Invest
>       </button>
>
>       {busy && <p>{investPhaseLabel(busy)}</p>}
>       {error && <p role="alert">{error}</p>}
>     </div>
>   );
> }
>
> function investPhaseLabel(phase: TokenSaleExecutionPhase): string {
>   switch (phase) {
>     case "resetting-allowance":
>       return `Reset your ${PAYMENT_TOKEN.symbol} allowance in your wallet…`;
>     case "approving":
>       return `Approve ${PAYMENT_TOKEN.symbol} in your wallet…`;
>     case "recording-participation":
>       return "Recording your participation…";
>     default:
>       return "Working…";
>   }
> }
> ```
>
> ### Going further
>
> * **Show the user's balance** - `passage.erc20.getBalance({ tokenAddress, owner, chain })` reads the connected wallet's balance for a payment token, so you can validate the amount or render a Max button before investing. `useErc20TokenBalances({ address, chain, assets, enabled })` is the polling hook form; it returns `{ state }`, whose `CONTENT` arm carries a `balances` map.
> * **Lower-level control** - if you drive the ERC-20 `approve` yourself (a custom wallet, batching, a different confirmation UX), skip `passage.tokenSale.execute` and record the participation directly with `passage.tokenSale.createParticipation`, passing the `approvalTransactionHash` you obtained. The spender is the offer's funding contract on your chain, from `offer.fundingContracts`. `execute` is the batteries-included version of exactly that sequence.

## Track participations

A **participation** is the record CoinList keeps of a user taking part in a token sale. It moves through its statuses on the backend's clock - `prepared` → `pending` → `submitted` → `completed` as the approval is verified and the payment committed, then `remit_submitted` → `remitted` when the sale settles and refunds what the allocation did not use (`failed` and `remit_failed` are the failure states). None of it is pushed to the SDK.

> [!NOTE]
>
> To show participations without building any UI, render `ClaimContainer` (`@alpha`) for the token-sale offer. It lists every participation the user placed in that offer, across its options and paying wallets, newest first, and polls like the hook below. Nothing is claimed: the sale pushes the tokens and the refund itself, so its only action is a retry after a load error. It renders nothing for a signed-out user. It still takes the required `wallets` prop, but a token sale's list covers the whole account, so the card reads no wallet.

### Recommended: useCoinListTokenSaleParticipations

```tsx theme={null}
"use client";

import { useCoinListTokenSaleParticipations } from "@passage-cl/react";
import type { OfferId } from "@passage-cl/react/universal";

export function Participations({ offerId }: { offerId?: OfferId }) {
  const { participationsState, refetch } =
    useCoinListTokenSaleParticipations(offerId);

  switch (participationsState.type) {
    case "DISABLED":
      return null;
    case "LOADING":
      return <p>Loading…</p>;
    case "ERROR":
      // reason: "not-authenticated" | "generic-error"
      return (
        <p role="alert">
          Could not load participations ({participationsState.reason}).{" "}
          <button onClick={refetch}>Try again</button>
        </p>
      );
    case "CONTENT":
      return (
        <ul>
          {participationsState.participations.map((participation) => (
            <li key={participation.id}>
              {participation.displayAmount} {participation.asset.code} -{" "}
              {participation.status}
            </li>
          ))}
        </ul>
      );
    default: {
      const exhaustive: never = participationsState;
      return exhaustive;
    }
  }
}
```

The `offerId` is optional: omit it to list every participation for the signed-in user. The hook was `useParticipations` before v0.13.0. It now:

* **Polls** `passage.tokenSale.list(offerId)` every 15 seconds while the page is visible, and reads once more when the page becomes visible again. Pass `pollInterval` (a `Seconds`) to change the interval. That is also how an order placed through `CheckoutContainer` on the same page appears, with nothing for you to wire.
* **Keeps the list on a failed poll.** A failed tick with a list in hand stays `CONTENT`, so `ERROR` means no list has arrived yet. A `not-authenticated` failure is the exception: it drops the list and reports `ERROR`.
* **Reports `DISABLED`** when `enabled: false` is set before any read has answered. A list already in hand survives being switched off.
* **Returns `refetch()`**, which reads again now (a no-op while disabled).

Pass `data` to seed it with participations pre-fetched via `PassageServer#tokenSale.list()`. The seed opens the state and skips only the first client-side read; the poll and `refetch` still read. See [SDK structure](/sdk/structure#hooks).

### Reading and writing imperatively

`passage.tokenSale` is available on both the browser client and `PassageServer`, except `execute`, which needs a wallet.

| Method | Returns |
| - | - |
| `list(offerId?)` | Every participation, auto-paginating. Optionally scoped to one offer. |
| `listPage(params)` | One page, when you implement your own pagination. |
| `get(id)` | A single participation. |
| `createParticipation(params)` | Records a participation. Requires the hash of the ERC-20 approval you submitted first. |
| `execute(params)` | Client only. Approves and records in one call. |

```ts theme={null}
const existing = await passage.tokenSale.list(offerId);

const created = await passage.tokenSale.createParticipation({
  offerId,
  offerOptionId,
  chain: "ethereum_mainnet",
  walletAddress,                  // an EvmWalletAddress
  amount: "1000.00",              // decimal token amount, not base units
  assetId,
  approvalTransactionHash,        // required; verified on-chain before recording
});
```

`createParticipation` takes the same `EthereumChain` and `EvmWalletAddress` as every other flow. The `Blockchain` and `WalletAddress` types it took before v0.13.0 are gone. On the way back, a `Participation`'s `chain` is a `Chain`, or `null` for a chain the SDK does not model, and its `walletAddress` is an `EvmWalletAddress` or `null`.

> [!NOTE]
>
> `amount` is a **decimal token amount** (`"100"` for 100 USDC), not raw base units. The SDK maps the camelCase keys to the API's snake\_case fields; see the [API reference](/api-reference) for the raw request and response schema.

Every method except `execute` requires a logged-in user and throws `NotAuthenticatedError` otherwise. `execute` never throws: logged out, it returns an error step instead.

## Common questions

> **Why an approve instead of a transfer?**
>
> CoinList moves the payment itself, after on-chain verification. The user only signs an allowance up to the amount they want to invest, and nothing leaves their wallet during the flow. CoinList then verifies the approval and pulls the payment through the allowance into the sale's funding contract in a batch, usually within a minute or so. That lets CoinList check every participation before it commits the payment, and batch the transfers.

> **Why is an approval always submitted?**
>
> The backend hard-requires an approval transaction hash on every participation and verifies that exact transaction on-chain (sender, token, spender, and approved amount) before confirming. A participation recorded without a fresh approval always fails, so `passage.tokenSale.execute` submits one even when the standing allowance already covers the amount - the allowance read only decides whether a reset-to-zero is needed first.

> **Do I need wagmi / Reown AppKit specifically?**
>
> No. Anything implementing the `EvmWallet` interface works - viem directly, Privy, ethers with a thin adapter. The token-sale flow only calls `address`, `writeContract`, and `awaitTx`; it never sees your wallet library. It's the same `EvmWallet` every other flow uses.

> **What if recording fails after the approval mined?**
>
> The error comes back as `{ step: "participation", approvalTxHash }`. The approval is already on-chain, so call `passage.tokenSale.execute` again with `approval: { type: "mined", txHash: approvalTxHash }` and the same amount, rather than re-running the whole flow - the user doesn't need to approve again.

> **What about chains other than Ethereum?**
>
> The flow generalizes: the same `EvmWallet` adapter maps each `EthereumChain` to a network, `TOKEN_REGISTRY` knows the payment-token addresses per chain, and the offer's `fundingContracts` names the chains a sale takes orders on. Your account manager will confirm which chains and assets are enabled for your offers.

## Next step

> **[Building the Checkout flow](/sdk/checkout)**
>
> The recommended path: one container that renders whichever provider an offer belongs to.


# Set up OAuth authentication
Source: https://docs.passage.coinlist.co/sdk/oauth-authentication

Authenticate users with Passage and authorize your application using OAuth 2.0 with PKCE and a backend session.

Users authenticate with Passage and authorize your application - no passwords are shared with you. Passage uses OAuth 2.0 with PKCE (Proof Key for Code Exchange) to secure the redirect flow.

This page assumes you run a **backend** you control: the **client secret**, refresh token, and token exchange stay on the server. The React SDK handles PKCE in the browser and session hydration through `getAccessToken`.

## Prerequisites

* A registered `client_id` and `redirect_uri` from Passage - [contact us](mailto:support@coinlist.co) if you need access
* `redirect_uri` must match your OAuth callback page (for example `https://your-domain.com/oauth/coinlist/callback`)
* `client_secret` available **only** on the server
* `@passage-cl/react` installed ([SDK quickstart](/sdk/quickstart))

Working examples line up with the [partner-demo](https://github.com/coinlist/partner-demo) app.

## Wrap your app with PassageProvider

Configure `clientId`, `redirectUri`, and `getAccessToken` so the SDK can run OAuth in the browser and read short-lived access tokens from your session API.

```tsx theme={null}
// app/providers.tsx
"use client";

import { PassageProvider } from "@passage-cl/react";
import type { ClientConfig } from "@passage-cl/react";
import { ClientId, RedirectUri } from "@passage-cl/react/universal";

// Module scope: the provider builds a new client whenever `config` changes
// identity, so do not rebuild it on every render.
const config: ClientConfig = {
  clientId: ClientId(process.env.NEXT_PUBLIC_COINLIST_CLIENT_ID!),
  redirectUri: RedirectUri(process.env.NEXT_PUBLIC_COINLIST_REDIRECT_URI!),
  getAccessToken: async () => {
    const res = await fetch("/api/coinlist/oauth/access-token", {
      credentials: "include",
    });
    // 204: there is no session.
    if (res.status === 204) return null;
    // Anything else that is not a token: the SDK could not find out. Throw.
    if (!res.ok) {
      throw new Error("GET /api/coinlist/oauth/access-token failed");
    }
    const data = (await res.json()) as { value: string; expiresAt: string };
    return {
      value: data.value,
      expiresAt: new Date(data.expiresAt),
    };
  },
  onSessionExpired: async () => {
    // The user's CoinList session ended: send them back to sign in.
    window.location.assign("/?session=expired");
  },
};

export function Providers({ children }: { children: React.ReactNode }) {
  return <PassageProvider config={config}>{children}</PassageProvider>;
}
```

`getAccessToken` has two answers, and the SDK treats them differently:

* **Resolve `null`** when there is no session, for example when your endpoint answers 204. The SDK treats the user as logged out.
* **Throw** when you could not find out, for example on a 5xx or a network failure. The SDK keeps its current auth state and fails only the request in hand.

Never answer `null` for your own backend's failures: that turns every outage into a sign-out.

The SDK asks `getAccessToken` when it initializes (or on its first request, if that comes first), and again when the API refuses the token it holds with a 401. It does not track `expiresAt` itself. Concurrent requests that need a new token share one call. A `null` after a 401, or the very token the API just refused, is only a suspicion: the SDK waits one second and asks once more, and only a second such answer signs the user out. That second answer also calls `onSessionExpired`, if the user had been logged in. It is called on the next microtask and not awaited, and a rejection is logged and dropped. It never fires on `auth.logout()`, a 5xx, a timeout or a network failure.

If `getAccessToken` throws while the SDK initializes, `passage.init()` rejects with that error and the auth state stays `'unknown'`. `PassageProvider` still sets `isReady` to `true`, so in React `isReady` can be `true` while `passage.auth.getState()` is `'unknown'`.

> [!NOTE]
>
> Leave `baseUrl` and `tokensBaseUrl` out of `ClientConfig` to use the production defaults. An empty or whitespace-only value throws a `ValidationError` when the client is built (in React, from `PassageProvider`'s render), so omit the field rather than passing an environment variable that is set but empty.

Since v0.11.0 the provider also takes a `locale`, a BCP-47 tag applied to number, date and currency formatting in every SDK component in the tree. It defaults to `'en-US'`, a fixed constant rather than `navigator.language`, so server and client render the same markup.

It does not reach embedded third-party flows. The Sumsub identity-verification UI takes its language from [`identityVerificationOptions.locale`](/sdk/requirements#props) on `RequirementsChecklistContainer`, and falls back to Sumsub's own default when you omit it.

```tsx theme={null}
<PassageProvider config={config} locale={params.locale}>{children}</PassageProvider>
```

## Sign-in UI (recommended)

Use the packaged sign-in card inside any subtree that already has `PassageProvider`. It calls `passage.auth.startOAuth()` when the user clicks **Continue with CoinList**. Pass `onSignIn` to override that.

```tsx theme={null}
"use client";

import { CoinListSignInCardContainer } from "@passage-cl/react";

export function SignInPanel() {
  return <CoinListSignInCardContainer />;
}
```

If you want the button without the card around it, render `CoinListSignInButton` instead. It has no default action, so pass an `onClick` that calls `passage.auth.startOAuth()`, as in [custom sign-in control](#lower-level-and-custom-integrations).

You do not import any CSS: every SDK component injects its own styles, scoped to the component, when it renders.

For auth gating, loading states, and `OffersGridContainer` after sign-in, see [partner-demo `app/page.tsx`](https://github.com/coinlist/partner-demo/blob/main/app/page.tsx).

## Server: PassageServer and session storage

Create a small factory that binds `createPassageServer` to your outgoing response and session store. The example below uses HTTP-only cookies; adjust to your security model.

```ts passage-server.ts theme={null}
// lib/passage-server.ts
import type { NextResponse } from "next/server";
import type { PassageServer } from "@passage-cl/react/server";
import { createPassageServer } from "@passage-cl/react/server";
import {
  ClientId,
  ClientSecret,
  RedirectUri,
} from "@passage-cl/react/universal";
import { createSessionCookiesStore } from "./session-store";

export function passageServer(outgoingResponse: NextResponse): PassageServer {
  return createPassageServer({
    clientId: ClientId(process.env.NEXT_PUBLIC_COINLIST_CLIENT_ID!),
    clientSecret: ClientSecret(process.env.COINLIST_CLIENT_SECRET!),
    redirectUri: RedirectUri(process.env.NEXT_PUBLIC_COINLIST_REDIRECT_URI!),
    sessionStore: createSessionCookiesStore(outgoingResponse),
  });
}
```

```ts session-store.ts theme={null}
// lib/session-store.ts
import { cookies } from "next/headers";
import { NextResponse } from "next/server";
import type { SessionStore } from "@passage-cl/react/server";
import type { OAuthSession } from "@passage-cl/react/universal";
import { OAuthRefreshToken } from "@passage-cl/react/universal";

const COINLIST_SESSION_COOKIE = "coinlist_session";

/** Copy Set-Cookie headers from the SDK scratch response onto the response you return (e.g. after refresh in `auth.getAccessToken()`). */
export function copyCookiesFromTo(source: NextResponse, target: NextResponse) {
  for (const cookie of source.cookies.getAll()) {
    const { name, value, ...options } = cookie;
    target.cookies.set(name, value, options);
  }
}

export function createSessionCookiesStore(
  outgoingResponse: NextResponse,
): SessionStore {
  return {
    async getSession(): Promise<OAuthSession | null> {
      const raw = (await cookies()).get(COINLIST_SESSION_COOKIE)?.value;
      if (!raw) return null;

      let parsed: {
        accessToken?: { value?: string; expiresAt?: string };
        refreshToken?: string;
      };
      try {
        parsed = JSON.parse(raw);
      } catch {
        return null;
      }

      if (!parsed.accessToken?.value || !parsed.accessToken?.expiresAt)
        return null;
      const expiresAt = new Date(parsed.accessToken.expiresAt);
      if (Number.isNaN(expiresAt.getTime())) return null;

      return {
        accessToken: { value: parsed.accessToken.value, expiresAt },
        ...(parsed.refreshToken
          ? { refreshToken: OAuthRefreshToken(parsed.refreshToken) }
          : {}),
      };
    },

    async setSession(session: OAuthSession | null): Promise<void> {
      if (session == null) {
        outgoingResponse.cookies.delete(COINLIST_SESSION_COOKIE);
        return;
      }

      outgoingResponse.cookies.set(
        COINLIST_SESSION_COOKIE,
        JSON.stringify({
          accessToken: {
            value: session.accessToken.value,
            expiresAt: session.accessToken.expiresAt.toISOString(),
          },
          ...(session.refreshToken
            ? { refreshToken: String(session.refreshToken) }
            : {}),
        }),
        {
          httpOnly: true,
          secure: process.env.NODE_ENV === "production",
          sameSite: "lax",
          path: "/",
        },
      );
    },
  };
}
```

### Read-only session stores (Server Components)

In Next.js **Server Components** you can read cookies but cannot write them, so a writable `SessionStore` is unsafe - a refreshed session would be silently discarded after consuming the refresh token, effectively logging the user out. Since v0.5.1, `setSession` is **optional**: omit it to opt into read-only mode explicitly.

```ts passage-server-readonly.ts theme={null}
// lib/passage-server-readonly.ts
import { cookies } from "next/headers";
import type { SessionStore } from "@passage-cl/react/server";
import { createPassageServer } from "@passage-cl/react/server";
import type { OAuthSession } from "@passage-cl/react/universal";
import {
  ClientId,
  ClientSecret,
  RedirectUri,
} from "@passage-cl/react/universal";

// Read-only store: only `getSession`, no `setSession`.
const readOnlySessionStore: SessionStore = {
  async getSession(): Promise<OAuthSession | null> {
    const raw = (await cookies()).get("coinlist_session")?.value;
    // …parse and return, same as the writable store above
    return parseSession(raw);
  },
};

export function passageServerForRSC() {
  return createPassageServer({
    clientId: ClientId(process.env.NEXT_PUBLIC_COINLIST_CLIENT_ID!),
    clientSecret: ClientSecret(process.env.COINLIST_CLIENT_SECRET!),
    redirectUri: RedirectUri(process.env.NEXT_PUBLIC_COINLIST_REDIRECT_URI!),
    sessionStore: readOnlySessionStore,
  });
}
```

What the SDK does in read-only mode:

* **`auth.getAccessToken()`** returns the stored token as-is, even if it has expired, and logs a warning. It never refreshes, so no refresh token is consumed. A non-null token is not a promise that the API accepts it: check `token.expiresAt > new Date()` before relying on it.
* **API requests** are sent with the stored token. If the API refuses it with a 401, the SDK returns that error without trying to refresh.
* **`auth.completeOAuth()` and `auth.logout()`** reject with `WritableSessionStoreRequiredError` before any network request. Use a writable store in your Route Handlers for those flows.
* **`passage.tokens`** still works. It is unauthenticated, so token metadata reads need no session at all.

> [!WARNING]
>
> Don't fake a writable store with a no-op `setSession: async () => {}`. That used to be the workaround for Server Components, but it silently consumed refresh tokens during a refresh attempt and logged the user out. If you upgrade from a pre-0.5.1 version, **remove** any no-op `setSession` you added. See the [v0.5.1 changelog](/changelogs/react#v0-5-1) for the full migration note.

Use the writable cookie store (above) inside **Route Handlers** for `auth.completeOAuth`, `auth.getAccessToken()`-driven refresh, and `auth.logout`. Use the read-only store inside **Server Components** for plain reads (for example, pre-fetching offers with `passage.offers.list()` for SSR).

## Callback route

On the URL you registered as `redirect_uri`, use **`useCompleteOAuth`**: it validates the redirect (state / PKCE via `passage.auth.completeOAuth`), hands the code to your `postOAuthComplete` to exchange on your backend, then runs `passage.init()` so the client picks up the new session. If `postOAuthComplete` returns `false` or rejects, or `passage.init()` rejects, `onFailure` receives `"complete_request_failed"`.

This matches [partner-demo `app/oauth/coinlist/callback/page.tsx`](https://github.com/coinlist/partner-demo/blob/main/app/oauth/coinlist/callback/page.tsx):

```tsx theme={null}
// app/oauth/coinlist/callback/page.tsx
"use client";

import { useCompleteOAuth } from "@passage-cl/react";
import type { CompleteOAuthFailureReason } from "@passage-cl/react";
import { useRouter } from "next/navigation";

export default function CoinListCallbackPage() {
  const router = useRouter();

  useCompleteOAuth({
    async postOAuthComplete({ code, codeVerifier }) {
      const res = await fetch("/api/coinlist/oauth/complete", {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        credentials: "include",
        body: JSON.stringify({ code, codeVerifier }),
      });
      return res.ok;
    },
    onFailure(reason: CompleteOAuthFailureReason) {
      router.replace(`/?error=${encodeURIComponent(reason)}`);
    },
    onSuccess() {
      router.replace("/");
    },
  });

  return (
    <div className="flex min-h-screen items-center justify-center">
      <p>Completing sign-in…</p>
    </div>
  );
}
```

> [!NOTE]
>
> Put this file at a path that matches `NEXT_PUBLIC_COINLIST_REDIRECT_URI`. Read `reason` on your home page (for example via `useSearchParams`) if you want to show OAuth errors - see partner-demo `app/page.tsx`.

## Exchange the code on your backend

The server SDK performs the token exchange - you do not call the token URL with raw `fetch` in application code. `auth.completeOAuth` takes an `AuthorizationGrant` (`{ code, codeVerifier }`, exported from `@passage-cl/react/universal`), the same pair the browser's `passage.auth.completeOAuth()` returns. It throws `HttpError` if CoinList refuses the exchange, and it never retries it, because an authorization code is single-use.

```ts theme={null}
// app/api/coinlist/oauth/complete/route.ts
import { NextResponse } from "next/server";
import { AuthorizationCode, CodeVerifier } from "@passage-cl/react/universal";

import { passageServer } from "@/lib/passage-server";

interface CompleteOAuthRequest {
  code: string;
  codeVerifier: string;
}

export async function POST(req: Request) {
  const body: CompleteOAuthRequest = await req.json();
  const { code, codeVerifier } = body;

  if (typeof code !== "string" || typeof codeVerifier !== "string") {
    return NextResponse.json({ error: "missing_fields" }, { status: 400 });
  }

  const response = NextResponse.json({ ok: true });

  await passageServer(response).auth.completeOAuth({
    code: AuthorizationCode(code),
    codeVerifier: CodeVerifier(codeVerifier),
  });

  return response;
}
```

## Serve access tokens to the client

The browser SDK's `getAccessToken` calls this route. Implement it with `passageServer(response).auth.getAccessToken()` so refresh happens server-side. Map its two outcomes the same way the browser reads them: `null` means there is no session (answer 204), and a throw means the SDK could not find out (answer a 5xx, so the browser keeps the user signed in and retries later).

```ts theme={null}
// app/api/coinlist/oauth/access-token/route.ts
import { passageServer } from "@/lib/passage-server";
import { copyCookiesFromTo } from "@/lib/session-store";
import type { OAuthAccessToken } from "@passage-cl/react/universal";
import { NextResponse } from "next/server";

export async function GET() {
  const cookieSink = new NextResponse(null, { status: 204 });
  let token: OAuthAccessToken | null;
  try {
    token = await passageServer(cookieSink).auth.getAccessToken();
  } catch (error) {
    // CoinList's token endpoint or the network failed. Not a logout.
    console.error(error);
    return new NextResponse(null, { status: 503 });
  }
  if (token == null) {
    return cookieSink;
  }

  const response = NextResponse.json({
    value: token.value,
    expiresAt: token.expiresAt.toISOString(),
  });
  copyCookiesFromTo(cookieSink, response);
  return response;
}
```

> [!NOTE]
>
> When `auth.getAccessToken()` refreshes the session, the SDK may set cookies on `cookieSink`. `copyCookiesFromTo` applies those to the JSON response so the browser gets the updated session cookie.

### How the server refreshes

With a writable store, `auth.getAccessToken()` refreshes the session once the access token is within `accessTokenExpiryBufferSeconds` of its expiry (default 60 seconds). To change it, pass `accessTokenExpiryBufferSeconds: Seconds.of(120)` to `createPassageServer`, with `Seconds` from `@passage-cl/react/universal`. `Seconds.of` throws a `ValidationError` unless its argument is a non-negative integer.

* **Concurrent requests share one refresh.** All `PassageServer` instances in one process (one JavaScript module instance) that refresh the same session join a single `POST /oauth/token`, and each writes the result to its own `SessionStore`.
* **A rejected refresh token is a suspicion first.** CoinList answers a refresh that lost a race to a concurrent request the same way it answers a dead session (`400 invalid_grant`). On the first rejection the SDK writes nothing and returns `null`, or the current access token if it has not actually expired yet.
* **A second rejection is the verdict.** When the same process sees the same refresh token rejected again, 5 to 60 seconds after the first, the SDK clears the session with `setSession(null)` and then calls the server's `onSessionExpired`. A session that has no refresh token is served until it actually expires, then cleared the same way.
* **A failure to find out never clears the session.** On a 5xx, a network failure, `invalid_client` or an unreadable response, the SDK keeps serving the current access token if it has not expired yet, and logs a warning. If it has expired, `auth.getAccessToken()` throws the underlying error (`HttpError`, or the `fetch` error) and leaves the session untouched. Other `PassageServer` methods that need a session throw that same error instead of `NotAuthenticatedError`.
* **A 401 forces a refresh.** If the API refuses a token that still looks valid locally, for example a session revoked elsewhere, a writable store refreshes anyway.
* **An invalid `expiresAt`** in the session your store returns makes `auth.getAccessToken()` throw a `ValidationError`.

`onSessionExpired` on `ServerConfig` fires at most once per session per process within 60 seconds, so make it idempotent. When the browser drives renewal through your access-token route, it reaches its own verdict one second after the first rejection, so expect the browser's `onSessionExpired` rather than the server's.

## Log out

Clear the session with the server SDK from a route handler. `auth.logout()` revokes the token with `POST /oauth/revoke` and clears the session through `setSession(null)`. It does nothing when there is no session.

```ts theme={null}
// app/api/coinlist/oauth/logout/route.ts
import { passageServer } from "@/lib/passage-server";
import { NextResponse } from "next/server";

export async function POST() {
  const response = NextResponse.json({ ok: true });
  await passageServer(response).auth.logout();
  return response;
}
```

The revoke is best-effort. If it fails for any reason - an `HttpError`, a network failure, anything else - the SDK logs a warning and clears the session anyway, because the cleared session is what logs the user out. Set `strict: true` on `createPassageServer` to rethrow the revoke failure instead, leaving the session in place so you can retry. In both modes, an error thrown by your `SessionStore` propagates, and a read-only store rejects with `WritableSessionStoreRequiredError`.

Call `passage.auth.logout()` on the client to drop the in-memory token after the server clears the session. It is synchronous, it never calls `onSessionExpired`, and it wins over a `getAccessToken` answer that was already in flight, so a late answer cannot sign the user back in.

## Token management

* **Access tokens** are short-lived. The SDK attaches them as `Authorization: Bearer` on API requests.
* **Refresh tokens** are long-lived. Keep them on the server. With the server SDK and a writable store, `auth.getAccessToken()` refreshes them for you (see [how the server refreshes](#how-the-server-refreshes)).
* Never expose **`client_secret`** or long-lived refresh tokens to the browser bundle.

## Lower-level and custom integrations

Use the sections below only if you are not using the defaults above.

> **Custom sign-in control (usePassage + startOAuth)**
>
> If you build your own button or entry point, call `auth.startOAuth()` from `usePassage()`:
>
> ```tsx theme={null}
> "use client";
>
> import { usePassage } from "@passage-cl/react";
>
> export function LoginButton() {
>   const { passage } = usePassage();
>
>   return (
>     <button type="button" onClick={() => void passage.auth.startOAuth()}>
>       Continue with CoinList
>     </button>
>   );
> }
> ```

> **Manual callback handling (auth.completeOAuth + fetch)**
>
> You can call `passage.auth.completeOAuth()` yourself, then POST `code` and `codeVerifier` to `/api/coinlist/oauth/complete`, await `passage.init()`, and redirect. `completeOAuth()` returns an `OAuthClientResult`: either `{ type: "ok", code, codeVerifier }` or `{ type: "error", reason }`, where `reason` is an `OAuthClientErrorReason`. Prefer `useCompleteOAuth` when possible - it centralizes failure reasons and avoids duplicate work in React Strict Mode.
>
> ```tsx theme={null}
> "use client";
>
> import { usePassage } from "@passage-cl/react";
> import { useRouter, useSearchParams } from "next/navigation";
> import { Suspense, useEffect, useRef } from "react";
>
> function LegacyCallbackBody() {
>   const { passage } = usePassage();
>   const searchParams = useSearchParams();
>   const router = useRouter();
>   const hasStarted = useRef(false);
>
>   useEffect(() => {
>     if (hasStarted.current) return;
>
>     if (searchParams.get("error")) {
>       router.replace("/?error=coinlist_denied");
>       return;
>     }
>
>     if (!searchParams.get("code")) return;
>
>     const oauthRes = passage.auth.completeOAuth();
>     if (oauthRes.type === "error") {
>       router.replace("/?error=coinlist_oauth");
>       return;
>     }
>
>     hasStarted.current = true;
>
>     void (async () => {
>       const res = await fetch("/api/coinlist/oauth/complete", {
>         method: "POST",
>         headers: { "Content-Type": "application/json" },
>         credentials: "include",
>         body: JSON.stringify({
>           code: oauthRes.code,
>           codeVerifier: oauthRes.codeVerifier,
>         }),
>       });
>
>       if (!res.ok) {
>         hasStarted.current = false;
>         router.replace("/?error=coinlist_complete_failed");
>         return;
>       }
>
>       try {
>         await passage.init();
>       } catch {
>         hasStarted.current = false;
>         router.replace("/?error=coinlist_init_failed");
>         return;
>       }
>       router.replace("/");
>     })();
>   }, [passage, searchParams, router]);
>
>   return <p>Completing sign-in…</p>;
> }
>
> export default function LegacyCallbackPage() {
>   return (
>     <Suspense fallback={<p>Completing sign-in…</p>}>
>       <LegacyCallbackBody />
>     </Suspense>
>   );
> }
> ```

> **Imperative client (createPassageClient)**
>
> For non-React browser code, import `createPassageClient` and `ClientConfig` from `@passage-cl/react` and call the same namespaces (`passage.auth.startOAuth()`, `passage.auth.completeOAuth()`, `passage.offers.list()`, …). Without `PassageProvider`, call `await passage.init()` yourself before relying on `passage.auth.getState()`. It rejects with whatever your `getAccessToken` throws, leaving the state `'unknown'`. You still need a backend for token exchange in production.

## Next step

> **[Fetch offers](/sdk/fetch-offers)**
>
> List offers for the signed-in user with `OffersGridContainer` or hooks, then open [Display offer details](/sdk/sale-details) for one offer.

## Resources

* [OAuth 2.0 Playground](https://oauth.net/playground/)
* [PKCE authorization code flow (Auth0)](https://auth0.com/docs/get-started/authentication-and-authorization-flow/authorization-code-flow-with-pkce)


# Ondo Swap
Source: https://docs.passage.coinlist.co/sdk/ondo-swap

Buy and sell tokenized stocks with Ondo. One prop switches direction, what each side approves, and the two-call order both share.

Ondo supplies **tokenized stocks** - `AAPLon`, `TSLAon` and the rest. An Ondo offer arrives with `type: "ondo::swap"` and runs both ways: a **buy** spends USDC to receive the tokenized asset, a **sell** delivers the asset and settles the proceeds in USDC.

> [!NOTE]
>
> **Recommended:** render [`CheckoutContainer`](/sdk/checkout). It detects `ondo::swap`, reads the direction from its `side` prop, and renders the whole flow. This page covers what is specific to Ondo, and the levels below the component.

Both directions are the same offer, the same contract, and the same two-call order. `offer.type` is `ondo::swap` whichever way the trade runs, because the side is a property of your page rather than of the catalog: the same asset is buyable and sellable at once.

## What Ondo needs from you

Nothing beyond the offer, a chain, your wallets and a direction. There is no separate sell container, and no Ondo config is required - the `side` prop is what picks the flow:

```tsx theme={null}
"use client";

import {
  CheckoutContainer,
  type CheckoutWalletSelection,
} from "@passage-cl/react";
import type { OfferDetail, OrderBookSide } from "@passage-cl/react/universal";

export function OndoCheckout({
  offer,
  wallets,
  side,
}: {
  offer: OfferDetail;
  wallets: CheckoutWalletSelection;
  side: OrderBookSide;
}) {
  return (
    <CheckoutContainer
      // The side belongs in the key: the flow holds an approval granted for
      // whichever coin that side spends.
      key={`${offer.id}:ethereum_mainnet:${side}`}
      offer={offer}
      chain="ethereum_mainnet"
      side={side}
      wallets={wallets}
    />
  );
}
```

That is the whole integration. `side` defaults to `"buy"`, so a buy page can leave it out and a sell page passes `side="sell"`. A page with a buy/sell toggle passes whatever the toggle selects, and puts it in the `key`.

`side` is a prop rather than something the offer says because no offer can answer it: `offer.type` is `ondo::swap` both ways. See [`side`: buy or sell](/sdk/checkout#side-buy-or-sell).

> [!WARNING]
>
> **`side` is read once, at mount.** The flow holds a committed quote and an approval granted for one specific token, so a re-render with a different `side` is ignored rather than obeyed. Remount with a `key` covering the offer, the chain and the side, as above.

The SDK derives **Ondo's API symbol** (for example `AAPLon`) from `offer.asset.code`. That is the key of every Ondo request - the trading status, the price and both builds - and there is no setting to override it.

`config["ondo::swap"]` accepts one optional field, `onOrderConfirmed(order)`, fired once a swap has mined, either way. The confirmation dialog shows regardless; add it only if you want to navigate, refresh a portfolio, or log.

> [!NOTE]
>
> **Quotes are priced against Ondo production whatever chain you pass**, because Ondo runs no sandbox. On a testnet the price is real and the money is not.

## Placing an order takes two calls

This is the one structural thing to know about Ondo, and it is the same both ways. An order is prepare then execute, not one call, and the split is where the trader's decisions are:

1. **`prepareBuy` / `prepareSell`** approves the swap contract to move the amount, then builds the transaction that moves it. The result is a **committed quote**: firm calldata with an `expiresAt`, valid for about a minute.
2. The trader reviews firm numbers - what goes, the fee, what arrives.
3. **`executeSwap`** broadcasts that calldata verbatim and waits for it to mine. It is one method for both directions, because broadcasting reads calldata and a deadline and knows about neither.

Bundling them behind one button would burn most of the transaction's \~60-second life on the approval and hand the trader an expired quote. The approval deliberately comes **first**: building first would spend an attestation on calldata that had already expired by the time they could act on it.

> [!WARNING]
>
> The builders spend an attestation on every call. The two reads - `getTradingStatus` and `getQuote` - are free to poll while the user sizes an order. Budget one build per order placed, plus one per refresh the user asks for.

> [!NOTE]
>
> **Buy and sell caps are independent.** `getTradingStatus` takes a required `side` and reports `tradable` with size limits for that side only. A working buy does not imply a working sell, and the market can be open one way and closed the other.

## When the market is closed

Ondo assets trade only while the market is open, and Ondo pauses briefly at every US session change (04:00 and 16:00 ET). While the trading status for the page's side reports `not-tradable`, the checkout replaces the flow with a "Trading is closed right now" screen and pauses the price poll. The trading-status poll keeps running underneath, so the checkout comes back by itself once the market opens. There is no retry button, because a retry before then fails the same way.

The screen appears only while the user is still on the step the flow opened on and no order dialog is showing. A market that closes later in the flow is reported by the step it interrupts.

At L1, `passage.ondo.getQuote` rejects a quote for a closed market with an `HttpError` (status 409, API code `not_tradable`). `isOndoNotTradableError(error)` from `@passage-cl/react/universal` recognizes it, so you can tell "wait for the market" apart from a failed request.

## What the two directions do not share

Only the transport is common. Beyond it, the amounts mean different things:

| | Buy | Sell |
| - | - | - |
| `amount` you pass | The **funding coin**, USDC, in its base units | The **asset**, in its base units |
| What gets approved | USDC on `chain` | The **asset** on `chain`, not a stablecoin |
| Where the token's address and decimals come from | `TOKEN_REGISTRY` | The sell quote, and nowhere else |
| What the response commits to | An exact quantity | A range: expected, with a floor beneath it |

The same integer means a different size on each side, so a size carried across a toggle is wrong by whatever the price is.

### Buying

The quantity is attested and exact, with no floor beneath it. The fee is **taken off the deposit rather than added on top**, so the approval never has to cover more than `spendInputAmount`.

> [!NOTE]
>
> **No CoinList fee is applied to a read quote, and no read discloses one.** Ondo prices exactly the amount passed, so sizing a quote against a user's approval without subtracting the fee first overstates what they receive.

### Selling

A sale is the mirror of a purchase: it approves the **asset** and receives USDC.

That matters because the SDK ships no registry entry for a provider's asset. `TOKEN_REGISTRY` knows the stablecoins swaps are funded with and nothing else, so on a sale:

* the **contract address** the balance is read on and the approval is granted for, and
* the **decimals** the typed amount is parsed at

both come off the sell quote (`OndoQuote.assetAddress`, `OndoQuote.asset.decimals`) and nowhere else. `useOndoSellCheckoutViewModel` does that resolution for you; a host composing its own viewmodel has to read the quote before it can read a balance.

The **settlement coin is USDC**, and it is display-only: the scale of every amount on a built sale comes off the response's `receive_output_decimals`, which is the only authority on how the proceeds are counted.

A built sale carries two figures rather than one. `expected` is what the sale should return; `minimum` is the floor the calldata enforces on chain. A fill below `minimum` reverts, so that - not `expected` - is what a seller is actually guaranteed. **Show both.**

### Skipping the wallet step

A sell page is usually reached from a position, and a position already names the wallet that holds it. Set [`CheckoutWalletSelection.preselected`](/sdk/wallets#skipping-the-wallet-step) and the checkout opens on the amount, renumbering the two cards that remain:

```ts theme={null}
import type { CheckoutWalletSelection } from "@passage-cl/react";

const wallets: CheckoutWalletSelection = {
  embedded,
  external,
  externalAdapter, // your connector, or null for embedded wallets only
  preselected: walletHoldingThePosition, // an EvmWallet, or null to let the user pick
};
```

The wallet does not have to appear in `embedded` or `external` - you supply a ready `EvmWallet` either way. Like `side`, it is read once at mount, so add `wallets.preselected?.address` to the `key` if it can change on one page.

Both directions honor `preselected`, so a buy page that already knows the wallet, such as a host with a single embedded wallet, can skip the step too. After an order, the flow resets to the amount step rather than to a wallet step it never had.

> **Build your own UI with hooks (L2)**
>
> `useOndoBuyCheckoutViewModel` and `useOndoSellCheckoutViewModel` each wrap a whole flow - trading status, quotes, the wallet step, the approval, the review and the broadcast - and return `{ state, onEvent }`. They take the same options: `offer`, `chain`, `wallets`, `enabled?` and `onOrderConfirmed?`.
>
> ```tsx theme={null}
> "use client";
>
> import {
>   useOndoSellCheckoutViewModel,
>   type CheckoutWalletSelection,
> } from "@passage-cl/react";
> import type { OndoSwapOfferDetail } from "@passage-cl/react/universal";
>
> export function OndoSellCheckout({
>   offer,
>   wallets,
> }: {
>   offer: OndoSwapOfferDetail;
>   wallets: CheckoutWalletSelection;
> }) {
>   const { state, onEvent } = useOndoSellCheckoutViewModel({
>     offer,
>     chain: "ethereum_mainnet",
>     wallets,
>   });
>
>   switch (state.type) {
>     case "error":
>       // state.reason: "unsupported-chain" | "not-tradable"
>       return <MyCheckoutUnavailable reason={state.reason} />;
>     case "content":
>       // state.wallet is null when `preselected` skipped the wallet step.
>       // state.amount, state.review, state.sidebar, state.orderConfirmed
>       return <MySellFlow state={state} onEvent={onEvent} />;
>     default: {
>       const exhaustive: never = state;
>       return exhaustive;
>     }
>   }
> }
> ```
>
> `OndoBuyCheckoutUiState` and `OndoSellCheckoutUiState` are both discriminated unions with a flow-level `error` arm, whose `reason` is one of:
>
> * **`unsupported-chain`**: the offer names no CoinList swap contract on the chain you passed. The viewmodel discovers that before any step runs, so nothing is fetched and no timer starts.
> * **`not-tradable`**: the market is closed for this side, and the user is still on the step the flow opened on. The trading-status poll keeps running, so the state returns to `content` once the market opens.
>
> `switch` exhaustively and assign the `default` to `const exhaustive: never = state` so a new arm is a compile error rather than a blank screen.
>
> Inside the `content` arm of either flow, `wallet` is `null` exactly when the host preselected a wallet. That `null` is the whole skip - it is what you render nothing for, and the single fact both remaining step numbers derive from. The review step's `quote` is an `OndoQuoteStatusUi` (`valid` with a countdown label, `refreshing`, `expired`, or `refresh-failed` with a message), the same type on both sides.
>
> The step viewmodels are not exported. The data hooks the god viewmodels are built from are, so you can assemble your own viewmodel instead:
>
> | Hook | Returns | `enabled` |
> | - | - | - |
> | `useOndoTradingStatus` | Whether that side's market is open, and its caps. Takes `symbol` and `side`. Pass its state to `isNotTradable(state)` to read a closed market. | required |
> | `useOndoPrice` | A pollable read quote. Takes `symbol`, `side` and a size. | required |
> | `useOndoBuyTransaction` | The committed purchase for a request, with its expiry. Pass the transaction `prepareBuy` returned as `data` to adopt it without a second build. Never polls. | required |
> | `useOndoSellTransaction` | The committed sale for a request, with its expiry. Same `data` seed. Never polls. | required |
> | `useErc20Balance` | The seller's balance of the asset, keyed by the address off the quote. | required |
>
> Each returns a `state` union of `DISABLED`, `LOADING`, `ERROR` and `CONTENT`. `DISABLED` means the hook is switched off with no answer in hand. On the Ondo hooks, a seed or an earlier answer survives being switched off. `useErc20Balance` drops its balance and reports `DISABLED` whenever it is switched off. An Ondo `ERROR` carries an `OndoLoadErrorReason`: `not-authenticated`, `generic-error` or `not-tradable`.
>
> `useErc20Balance` is the address-keyed counterpart to `useErc20TokenBalances`: a token whose contract address arrives at runtime has no registry symbol to look up, which is exactly the sell case. A `tokenAddress` of `null` fetches nothing, which is the normal state before the first quote lands.
>
> Every hook that fetches or polls takes `enabled`, and all of them must be called unconditionally. See [SDK structure](/sdk/structure#hooks) for the conventions they share.

> **Drive it yourself with the client (L1)**
>
> `passage.ondo` is a plain namespace with no React. The reads and the two builders exist on both the browser client and `PassageServer`; the wallet-driven halves are client-only, because a backend has no wallet to sign with.
>
> | Method | Kind | Notes |
> | - | - | - |
> | `getTradingStatus(params)` | read | Free to poll. Requires `side`. Returns `tradable` with size caps, or `not-tradable`. |
> | `getQuote(params)` | read | Free to poll. Requires `side`. A sell quote carries `assetAddress` and the asset's decimals. Rejects with a 409 `HttpError` while the market is closed (`isOndoNotTradableError`). |
> | `buildBuyTransaction(params)` | write | Spends an attestation. `POST /v1/ondo/swap/buy`. |
> | `buildSellTransaction(params)` | write | Spends an attestation. `POST /v1/ondo/swap/sell`. |
> | `prepareBuy(params)` | client only | Approves the funding coin, then builds. Step-tagged result. |
> | `prepareSell(params)` | client only | Approves the asset, then builds. Step-tagged result. |
> | `executeSwap(params)` | client only | Broadcasts and confirms, either direction. Step-tagged result. |
>
> A purchase reads its token from the registry. A sale has to read the quote first, because that is the only place the asset's address and decimals are published:
>
> ```ts theme={null}
> // Selling. The quote is the only source of the asset's address and decimals,
> // so price one whole share first, then parse what the user typed.
> const quote = await passage.ondo.getQuote({
>   symbol: AssetSymbol("AAPLon"),
>   side: "sell",
>   tokenAmount: BlockchainAmount({ raw: 1n, decimals: AssetDecimals(0) }),
> });
>
> const parsed = parseBlockchainAmount(amountInput, quote.asset.decimals);
> if (!parsed.valid) return;
> const amount = parsed.amount;
>
> const prepared = await passage.ondo.prepareSell({
>   wallet,                                   // your EvmWallet
>   symbol: AssetSymbol("AAPLon"),            // Ondo's API symbol
>   chain: "ethereum_mainnet",
>   swapContracts: offer.swapContracts,       // the spender, resolved per chain
>   tokenAddress: quote.assetAddress,         // the ASSET, not a stablecoin
>   amount,                                   // BlockchainAmount, asset base units
>   onProgress: (phase) => setBusy(phase),
> });
>
> if (prepared.type === "error") {
>   // prepared.error.step: "unsupported-chain" | "allowance-check"
>   //   | "approval" | "approval-reverted" | "insufficient-allowance"
>   //   | "build-transaction"
>   return;
> }
>
> // prepared.transaction.expected  - what the sale should return
> // prepared.transaction.minimum   - the floor the calldata enforces
>
> const filled = await passage.ondo.executeSwap({
>   wallet,
>   transaction: prepared.transaction,
>   chain: "ethereum_mainnet",
>   onProgress: (phase) => setBusy(phase),
> });
>
> if (filled.type === "success") {
>   // filled.txHash, filled.transaction
> } else {
>   // filled.error.step: "quote-expired" | "swap" | "swap-unconfirmed"
>   //   | "swap-reverted"
> }
> ```
>
> `prepareBuy` is the same call with `tokenAddress` set to the funding coin and `amount` in its base units, and it needs no quote first.
>
> Both flows are **total**: every failure comes back step-tagged rather than thrown, so you map each one to your own copy. `prepareBuy` and `prepareSell` return the same `OndoSwapPreparationError` - every arm names a *remedy*, and an unsupported chain or a refused approval is fixed the same way whichever token was being approved.
>
> **Preparation phases**, in order. An allowance that already covers the order skips the approval phases:
>
> `checking-allowance` → *(`resetting-allowance` → `confirming-allowance-reset`, only for stale non-zero allowances)* → **`approving`** *(wallet popup)* → `confirming-approval` → `building-transaction`
>
> **`executeSwap` phases**: **`broadcasting-swap`** *(wallet popup)* → `confirming-swap`
>
> Three error steps are worth calling out:
>
> * **`insufficient-allowance`** is separated from the generic build failure because it has a remedy. Reaching it means the approval that just mined is not the one the backend sees, usually an RPC node a block behind. That is a **retry**, not a re-approval.
> * **`quote-expired`** is a refusal to broadcast rather than a failed broadcast. It would revert on-chain and cost the trader gas, and it is fixed by building a fresh transaction.
> * **`swap-unconfirmed`** means the swap was sent but waiting for its receipt failed. It may still mine, so placing the order again could fill it twice. The error carries the `txHash`: look it up before doing anything else. `swap`, by contrast, means the wallet never sent it, so placing again is safe. The SDK's review step disables its button after `swap-unconfirmed` until the user leaves the step, with "Your order was sent but has not confirmed yet. Check your wallet before placing another."
>
> `executeSwap` broadcasts the calldata **verbatim**. Never re-encode it: the contract verifies a signature over the exact arguments inside.

## Which contract the trader approves

The ERC-20 spender comes off the offer, not from a constant in the SDK, and it works the same way on both sides. `OndoSwapOfferDetail.swapContracts` lists every chain the offer can be swapped on with the CoinList contract each settles through, and `swapSpender` reads one out:

```ts theme={null}
import { swapSpender } from "@passage-cl/react/universal";

const spender = swapSpender(offer.swapContracts, chain); // EvmContractAddress | null
```

`null` means this offer cannot be swapped on that chain - an answer, not an error. `CheckoutContainer` and both Ondo viewmodels check it before anything runs and render a flow-level `error` state with `reason: "unsupported-chain"`, so no wallet picker, balance read or price poll happens on a chain the order could never settle on.

> [!NOTE]
>
> The address varies by **environment** as well as by chain, which is why one constant could not express it: beta and production both run `ethereum_sepolia` and deploy a different contract on each. `ondoSwapContractAddress(chain)` was removed in v0.12.0 for that reason.

## Next steps

> **[Building the Checkout flow](/sdk/checkout)**
>
> The recommended path: one container for every provider, and both directions.

> **[Wallets](/sdk/wallets)**
>
> The `EvmWallet` seam, and `preselected` for skipping the wallet step.

> **[Superstate Swap](/sdk/swap-flow)**
>
> The other swap provider, and what it needs from you.

> **[Errors and edge cases](/sdk/errors)**
>
> Every error shape the flows return, and how to handle it.


# SDK quickstart
Source: https://docs.passage.coinlist.co/sdk/quickstart

Get OAuth credentials, install the Passage React SDK, and understand client, server, and API layers.

This guide covers **credentials**, **installing the SDK**, and how it is organized. When you are ready to wire sign-in, continue with **[Set up OAuth authentication](/sdk/oauth-authentication)**, then **[Fetch offers](/sdk/fetch-offers)**, then **[Display offer details](/sdk/sale-details)**. Examples use **Next.js App Router** patterns; you can adapt the same pieces to other React frameworks as long as you have a **dedicated backend**.

> [!TIP]
>
> Clone the [Partner Demo GitHub repo](https://github.com/coinlist/partner-demo) and follow this tutorial alongside the running example integration. You see it live at [partner.coinlist.dev](https://partner.coinlist.dev/).

## Get OAuth credentials

You need values from Passage before you write code:

* **`client_id`** - public identifier for your app
* **`redirect_uri`** - exact callback URL registered with Passage (must match what you pass in the SDK)
* **`client_secret`** - **server-only**; never expose this to the browser or commit it to frontend bundles

Request access and registration through [Support](/support) or your Passage contact. Store secrets in server environment variables (for example `COINLIST_CLIENT_SECRET`), and use `NEXT_PUBLIC_` only for values that are safe in the client (typically `client_id` and `redirect_uri`).

## Install the SDK

```bash theme={null}
npm install @passage-cl/react
```

Peer dependencies: `react` and `react-dom` `^18 || ^19`, and `viem` `^2`. React 20 is outside the supported range.

The package is ESM-only. Bundlers such as Next.js, Vite and webpack consume it natively. In Node it requires `^20.19.0 || >=22.12.0`, the versions that can `require()` an ES module, so CommonJS code on those versions can still load it.

See [Package overview](/sdks) for all import paths and the full namespace map.

## How the SDK is organized

The SDK splits three ways, in this order: **environment, then level, then feature.** Learn those three and you can find anything in it.

### Level: how much you want to build

Every feature is available at several levels. Lower levels provide more control but require more implementation. **Start with L3 components and use L2 or L1 when you need more control.**

1. **L3 - React components** *(highest)*. You get **UI and behavior together, working**. You provide the input, plus an optional config object, and you are done. `<CheckoutContainer offer chain wallets />` is an entire purchase flow: wallet selection, amount entry, approval, review, confirmation. Others: `<OffersGridContainer>`, `<RequirementsChecklistContainer>`, `<ClaimContainer>`, `<CoinListSignInCardContainer>`.

2. **L2 - React hooks** *(mid)*. You get **the behavior**: data fetching, state, polling, error handling, and the on-chain sequencing. You provide the UI. `useOffers()` hands you a `LOADING / ERROR / CONTENT` state machine and you render whatever you like from it; `useOndoBuyCheckoutViewModel()` runs the whole Ondo flow behind your own markup.

3. **L1 - TypeScript clients** *(low)*. You get **the logic**: typed API calls, domain mapping, and total on-chain flows that return a step-tagged result instead of throwing. You build the state management and the UI. `PassageClient` in the browser, `PassageServer` on your backend, no React anywhere. Use it for a non-React app, a custom state layer, or full control.

Below L1 there is no SDK. If you need something the client does not model, call the [HTTP API](/api-reference) directly.

A feature may **stop** at a rung, but it never skips one: a feature with a component always has the hooks and the namespace beneath it, so you can drop a rung whenever the one above does not fit.

**What is public, per feature:** the root container (L3), the viewmodel behind it and the data hooks it is built from (L2), and the namespaces (L1). The views, steps and sub-screens a container composes are not exported. You either take the SDK's UI with its behavior, or bring your own UI over the SDK's state. The exceptions are a few presentational pieces you lay out yourself: `CoinListSignInButton`, `OfferAssetCard` and `OfferSaleCard`. `RequirementsChecklistView` is also still exported, as a loading placeholder, but is due to be removed, and `PassageStyleScope` is the styling wrapper every SDK component already puts around itself.

### Environment: where code runs

Environment comes first in the split because it is a security boundary, not a convenience: `PassageServer` holds your `client_secret`, and it must never reach a browser bundle. That boundary is exactly the three import paths you type.

| | `@passage-cl/react` browser | `@passage-cl/react/server` your backend | `@passage-cl/react/universal` both |
| - | - | - | - |
| **L3 Components** *(highest)* | `<CheckoutContainer>` `<RequirementsChecklistContainer>` `<OffersGridContainer>` | - | - |
| **L2 Hooks** *(mid)* | `useOffers()` `useRequirements()` `useOndoBuyCheckoutViewModel()` | - | - |
| **L1 Client** *(low)* | `PassageClient` `passage.ondo.executeSwap()` | `PassageServer` `passage.offers.list()` | domain models, namespace and params types |

Not every feature is available at every level. L2 and L3 exist only in the browser, because a backend renders nothing. **L1 is the only level present everywhere**, which is why `passage.offers.list()` reads the same on your server as in your React tree.

### Feature

Inside each level, the code is grouped by feature, and the same features appear at every rung: **auth**, **offers**, **requirements**, and the provider journeys **checkout** and **claim**. So `passage.requirements` (L1), `useRequirements()` (L2) and `<RequirementsChecklistContainer>` (L3) are three abstraction levels for the same feature.

Checkout and claim are grouped one level deeper, by **provider** and **product** - Superstate swap, Ondo buy and sell, Centrifuge buy and sell, CoinList token sale - because every provider's flow differs in roughly a fifth of its substance. At L1 each provider has its own namespace (`passage.superstate`, `passage.ondo`, `passage.centrifuge`, `passage.tokenSale`). `<CheckoutContainer>` and `<ClaimContainer>` are what save you from caring: they route on `offer.type` (and, for Ondo and Centrifuge checkout, on a `side` prop) so you integrate once.

> [!TIP]
>
> **Recommendation:** start with components, drop to hooks when you need custom UI, and reach for the clients when you are outside React or need full control. The [HTTP API](/api-reference) remains the contract underneath, for bespoke stacks or endpoints the SDK does not wrap yet.

## Next step

> **[SDK structure](/sdk/structure)**
>
> The patterns every part of the SDK follows: namespaces, containers, hook state, and flows that return instead of throwing. Skippable if you would rather start building.

After OAuth, follow **[Fetch offers](/sdk/fetch-offers)** to render `OffersGridContainer`, then **[Display offer details](/sdk/sale-details)** for a single offer. Then **[Requirements](/sdk/requirements)** for what a user must satisfy before participating, **[Wallets](/sdk/wallets)** to plug in your wallet stack, and **[Building the Checkout flow](/sdk/checkout)** to render the purchase itself. Use the **[API reference](/api-reference)** when you need raw request and response details.


# Requirements checklist
Source: https://docs.passage.coinlist.co/sdk/requirements

Render RequirementsChecklistContainer and the SDK handles identity verification, tax documents, and wallet connection for you.

Before a user can participate in an offer, they have to satisfy its **requirements**: identity verification, a signed tax document, a connected wallet, a jurisdiction check, a CoinList account. Which ones apply is decided per offer option, by CoinList.

`RequirementsChecklistContainer` renders the whole checklist and resolves every requirement type in-app. It is the highest rung (**L3, components**) and the one to start from.

## Prerequisites

* A completed [OAuth](/sdk/oauth-authentication) session with a working `PassageProvider`
* An offer id and an offer option id from [Display offer details](/sdk/sale-details)

## Render it

```tsx theme={null}
"use client";

import { RequirementsChecklistContainer } from "@passage-cl/react";
import type { OfferDetail, OfferOption } from "@passage-cl/react/universal";
import { useRouter } from "next/navigation";

export function Requirements({
  offer,
  option,
}: {
  offer: OfferDetail;
  option: OfferOption;
}) {
  const router = useRouter();

  return (
    <RequirementsChecklistContainer
      offerId={offer.id}
      optionId={option.id}
      title="Before you invest"
      description="Complete these steps to participate in this offer."
      onContinue={() => router.push(`/offers/${offer.id}/checkout`)}
    />
  );
}
```

That is the whole integration. The container is **self-scoped**: it renders fully styled with no style provider in the tree. When the user is not authenticated it renders its error state and fetches nothing, so mount it only for a logged-in user and render `CoinListSignInCardContainer` yourself otherwise.

## What it does for you

Clicking a requirement's action button does the right thing per type, with no wiring from you:

| Requirement type | Default behavior |
| - | - |
| Any type whose status carries a Sumsub level (`kycLevel`), in practice `kyc_approved` and `accreditation` | Opens an inline Sumsub verification flow. The backend prescribes both the level and whether the applicant must be reset first. After the user submits, the checklist checks the statuses every 5 seconds until the requirement's status changes, for up to 2 minutes, then refreshes. |
| `kyc_approved`, `accreditation` with no Sumsub level on the status | Opens the CoinList verification page in a new tab. |
| `document` | Opens the built-in tax document modal. |
| `external_wallet`, `whitelisted_wallet` | Opens the built-in connect-wallet modal if you passed a `wallet` (or `wallet={null}` with an `onRequestConnect`). Otherwise opens CoinList in a new tab. |
| `jurisdiction` | No action - there is no CoinList page to send the user to. |
| `coinlist_account` | No action - the user satisfies it by signing in with CoinList, and your app signs the user in before the checklist can load. The row's default label is **CoinList Account**. |

The fallback for everything is `passage.requirements.handle`, which opens the corresponding CoinList page in a new tab where the type has one.

> [!TIP]
>
> **Omit `onRequirementActionOverride` and rely on the defaults.** Pass your own handler only if you need custom navigation, or `null` to disable the action button entirely. The same applies to `onContactSupportOverride`, which defaults to `passage.support.contact`.

## Resolving wallet requirements in-app

Pass a `wallet` and the checklist resolves `external_wallet` and `whitelisted_wallet` requirements without leaving your app. It only needs signing capability, so a `ConnectWallet` (an [`EvmSigner`](/sdk/wallets#two-shapes-one-seam) plus the `chain` it signs on) is enough - no gas, no transaction.

```tsx theme={null}
<RequirementsChecklistContainer
  offerId={offer.id}
  optionId={option.id}
  title="Before you invest"
  description="Complete these steps to participate in this offer."
  wallet={connectedWallet}          // ConnectWallet, or null while none is connected
  onRequestConnect={openConnectModal}
/>
```

When `wallet` is omitted entirely - or is `null` with no `onRequestConnect` to act on - wallet requirements fall back to opening CoinList in a new tab.

### Props

| Prop | Type | Description |
| - | - | - |
| `offerId` | `OfferId` | Required. |
| `optionId` | `OfferOptionId` | Required. Requirements are per option. |
| `title`, `description` | `string` | Required. Heading copy. |
| `onContinue` | `() => void` | Renders a **Continue** button, enabled once every requirement is satisfied, and is called when the user clicks it. |
| `wallet` | `ConnectWallet \| null` | A connected signer, for in-app wallet requirements. Import the type from `@passage-cl/react/universal`. |
| `onRequestConnect` | `() => void` | Called when the user asks to connect and none is connected. |
| `onRequirementActionOverride` | `((r: Requirement) => void) \| null` | Override the action button for all types, or `null` to disable it. |
| `onContactSupportOverride` | `((r: Requirement) => void) \| null` | Override the contact-support button, or `null` to disable it. |
| `getLabel` | `(r: Requirement) => string` | Override the default label per requirement type. |
| `getDescription` | `(r: Requirement) => string \| null` | Override the default description per requirement type. |
| `identityVerificationOptions` | `{ levelName?, locale? }` | Override the backend-prescribed Sumsub level, or set the Sumsub UI language. |
| `data` | `RequirementsData` | Pre-fetched server-side. Skips the initial client fetch. |
| `loading`, `error` | `ReactNode` | Slots. `error` replaces the error banner under the title; the title still renders. |
| `enabled` | `boolean` | Default `true`. `false` fetches nothing, for a checklist that is mounted but not needed yet. |
| `className` | `string` | |

> [!NOTE]
>
> `data` skips the requirements fetch, but connected-wallet addresses are not part of `RequirementsData` and are always fetched client-side.

`RequirementsData` is `{ requirements, statuses }`: the results of `passage.requirements.forOffer(offerId)` and `passage.requirements.statuses(offerId)` on `PassageServer`. `statuses` is per user, so the server needs the user's session for it.

## The screens the checklist opens

The identity verification flow, the tax document modal and the connect-wallet modal are internal to `RequirementsChecklistContainer`, and the SDK does not export them. To build your own checklist, use the data hooks below: `useKycToken` for a Sumsub token, `useTaxDocument` for the tax document, and `useConnectWallet` for the wallet ownership proof and binding.

> **Build your own UI with hooks (L2)**
>
> `useRequirementsChecklistViewModel` backs the container and returns `{ state, onEvent }`. Below it are the data hooks it composes, each usable on its own:
>
> ```tsx theme={null}
> import { useRequirements } from "@passage-cl/react";
> import type { OfferId } from "@passage-cl/react/universal";
>
> export function Checklist({ offerId }: { offerId: OfferId }) {
>   const { requirementsState, refetch } = useRequirements(offerId);
>
>   switch (requirementsState.type) {
>     // Also the state while `enabled` is false with no `data`: there is no DISABLED state.
>     case "LOADING":  return <Spinner />;
>     // reason: "not-authenticated" | "generic-error"
>     case "ERROR":    return <ErrorState reason={requirementsState.reason} onRetry={refetch} />;
>     case "CONTENT":  return <MyChecklist requirements={requirementsState.requirements} statuses={requirementsState.statuses} />;
>   }
> }
> ```
>
> `useRequirements` reports `not-authenticated` straight away, with no request, when the user is signed out. `refetch()` still fetches after a `data` seed, and does nothing while `enabled` is `false`.
>
> | Hook | What it does | Options |
> | - | - | - |
> | `useRequirements(offerId, options?)` | Fetches requirements and their statuses together. Returns `requirementsState` and `refetch`. | `data`, `enabled` |
> | `useOptionAddresses(offerId, optionId, options?)` | Lists the wallets bound to an offer option. Returns `addressesState`, `refetch` and `disconnect`. With `enabled: false` it sends no request and reports an empty `CONTENT`, or the `data` seed if you passed one. | `data`, `enabled` |
> | `useKycToken(levelName?, reset?)` | Mints a Sumsub token for the prescribed level. Starts `IDLE`; call `fetchToken()`. | |
> | `useTaxDocument({ isOpen })` | Loads the user's PII and submits the tax document. | `isOpen` |
> | `useConnectWallet(options)` | Runs the ownership-proof and binding flow over `passage.wallets.connect`. | `isOpen`, `offerId`, `offerOptionId`, `wallet`, `challengeType`, `statement` |
>
> See [SDK structure](/sdk/structure#hooks) for the conventions they share.

> **Drive it yourself with the client (L1)**
>
> `passage.requirements` is a plain namespace with no React. It is available on both the browser client and `PassageServer`, except `handle`, which needs a browser.
>
> | Method | Returns |
> | - | - |
> | `forOffer(offerId)` | `Record<OfferOptionId, Requirement[]>` - which requirements apply to each option. On `PassageServer` it also takes an optional app-level token from `passage.auth.clientCredentials()`, so it can run with no user session. |
> | `statuses(offerId)` | `RequirementStatusInfo[]` - the user's progress, with the Sumsub level that resolves each one. |
> | `createKycToken(params?)` | A Sumsub token. Takes `{ levelName, reset }`. |
> | `getPii()` | The user's personal information on file. |
> | `submitDocument(params)` | Submits a document. Takes `{ documentType, fields }`. |
> | `handle(requirement)` | Client only. Opens the corresponding CoinList page in a new tab. Does nothing for `jurisdiction`, `document` and `coinlist_account`, which have no CoinList page. |
>
> ```ts theme={null}
> const [requirements, statuses] = await Promise.all([
>   passage.requirements.forOffer(offerId),
>   passage.requirements.statuses(offerId),
> ]);
> ```
>
> A requirement `type` (`RequirementType`, from `@passage-cl/react/universal`) is one of `kyc_approved`, `external_wallet`, `whitelisted_wallet`, `jurisdiction`, `accreditation`, `document`, `coinlist_account`. `coinlist_account` is new in v0.14.0, so an exhaustive `switch` on `RequirementType` in your code, for example in a `getLabel`, needs a case for it. A status is `not_started`, `in_progress`, `action_needed`, `completed`, or `rejected`.
>
> Every method requires a logged-in user and throws `NotAuthenticatedError` otherwise, except `handle`, which only opens a CoinList page, and `forOffer` on the server when you pass an app-level token.
>
> Wallet ownership proof lives on `passage.wallets` rather than here, because it is provider-agnostic. See [Wallets](/sdk/wallets#proving-wallet-ownership).

## Next step

> **[Building the Checkout flow](/sdk/checkout)**
>
> Once requirements are satisfied, render `CheckoutContainer` and let it pick the provider.


# Display offer details
Source: https://docs.passage.coinlist.co/sdk/sale-details

Load full offer details with the React SDK or the API.

Fetch full offer details - pricing options, legal terms, milestones, the tokens the offer settles in, and more - for a single offer the user can access.

> [!NOTE]
>
> `OfferDetail.type` tells you which checkout the offer needs: `'coinlist::token_sale'`, `'superstate::swap'`, `'ondo::swap'`, or `'centrifuge::vault'`. Switch on it exhaustively, or hand the offer to [`CheckoutContainer`](/sdk/checkout) and let the SDK dispatch. v0.13.0 added `'centrifuge::vault'`, so an exhaustive `switch` written for an earlier version needs a new case - see the [changelog](/changelogs/react).

## Prerequisites

* Completed [OAuth](/sdk/oauth-authentication) and a working `PassageProvider`
* An **offer id** from [Fetch offers](/sdk/fetch-offers) (for example `offer.id` from `OffersGridContainer` `onOfferClick`)

## Recommended: useOfferDetails

The hook mirrors the SDK client method `passage.offers.get`: it waits until the provider is ready, then loads details and exposes `offerDetailsState`:

* **`LOADING`** - provider not ready or request in flight. With `enabled: false` and no `data`, the hook also stays `LOADING`: it has no `DISABLED` state.
* **`ERROR`** - `reason` is `not-authenticated` when no user is signed in (`NotAuthenticatedError`), and `generic-error` for any other failure
* **`CONTENT`** - `offerDetail` is the `OfferDetail`

Pass `data` with an `OfferDetail` your server fetched with `passage.offers.get(id)` on `PassageServer`, and the hook uses it as-is and sends no request. The hook has no `refetch()`.

When the user picks an offer from the grid, keep that `offer` in React state and pass `offer.id` - TypeScript then matches the branded id type the hook expects.

```tsx theme={null}
"use client";

import { useState } from "react";
import { OffersGridContainer, useOfferDetails } from "@passage-cl/react";
import type { Offer } from "@passage-cl/react/universal";

function OfferDetailPanel({ offer }: { offer: Offer }) {
  const { offerDetailsState } = useOfferDetails(offer.id);

  if (offerDetailsState.type === "LOADING") return <p>Loading details…</p>;
  if (offerDetailsState.type === "ERROR") return <p>Unable to load this offer.</p>;

  const detail = offerDetailsState.offerDetail;
  return (
    <section>
      <h1>{detail.name}</h1>
      {/* Render options, terms, milestones from detail - see API reference for fields */}
    </section>
  );
}

export function OfferBrowseAndDetail() {
  const [selected, setSelected] = useState<Offer | null>(null);

  return (
    <>
      <OffersGridContainer onOfferClick={(offer) => setSelected(offer)} />
      {selected ? <OfferDetailPanel offer={selected} /> : null}
    </>
  );
}
```

## REST: GET /v1/offers/

Use the API directly when you are not in React or you need a one-off server fetch with a token you already hold.

> **Example: fetch with Bearer token**
>
> ```ts theme={null}
> // lib/coinlist-api.ts
> export async function getOfferDetails(offerId: string, accessToken: string) {
>   const res = await fetch(
>     `https://api.coinlist.co/v1/offers/${encodeURIComponent(offerId)}`,
>     {
>       headers: { Authorization: `Bearer ${accessToken}` },
>     },
>   );
>
>   if (!res.ok) {
>     const error = await res.json();
>     throw new Error(error.message ?? "Failed to fetch offer");
>   }
>
>   return res.json();
> }
> ```
>
> See the [API reference](/api-reference) for the exact response schema.

Example response shape (values are illustrative - always rely on the live API and legal URLs from Passage):

```json theme={null}
{
  "object": "offer_details",
  "id": "{offer_id}",
  "type": "coinlist::token_sale",
  "slug": "example-offer",
  "name": "Example Token Sale",
  "tagline": "An example token sale",
  "starts_at": "2026-01-01T00:00:00.000000Z",
  "ends_at": "2026-01-31T00:00:00.000000Z",
  "options": [
    {
      "id": "{option_id}",
      "slug": "standard",
      "price_usd": "0.10",
      "floor_price_usd": "0.08",
      "bid_increment": null,
      "minimum_purchase_usd": "100",
      "total_token_supply": 1000000,
      "sale_agreement_url": "https://coinlist.co/agreements/example"
    }
  ],
  "funding_contracts": [
    { "chain": "ethereum_mainnet", "address": "0x0000000000000000000000000000000000000000" }
  ],
  "terms": [
    { "key": "Vesting", "value": "12 months linear" },
    { "key": "Lockup", "value": "6 months cliff" }
  ],
  "milestones": [
    { "name": "Registration", "schedule": "Jan 1", "status": "completed" },
    { "name": "Sale Open", "schedule": "Jan 15", "status": "active" },
    { "name": "Distribution", "schedule": "Feb 1", "status": "upcoming" }
  ],
  "faqs": [],
  "links": []
}
```

> [!NOTE]
>
> Display the full terms and link to the sale agreement URL as provided - do not summarize or paraphrase legal terms.

## Lower-level client

> **passage.offers.get in React**
>
> Equivalent to the hook, without the built-in state machine. Pass the same `offer.id` you get from `OffersGridContainer`:
>
> ```tsx theme={null}
> "use client";
>
> import { usePassage } from "@passage-cl/react";
> import type { Offer, OfferDetail } from "@passage-cl/react/universal";
> import { useEffect, useState } from "react";
>
> export function OfferDetailManual({ offer }: { offer: Offer }) {
>   const { passage, isReady } = usePassage();
>   const [detail, setDetail] = useState<OfferDetail | null>(null);
>
>   useEffect(() => {
>     if (!isReady) return;
>     void passage.offers
>       .get(offer.id)
>       .then(setDetail)
>       .catch(() => setDetail(null));
>   }, [passage, isReady, offer.id]);
>
>   if (!isReady) return <p>Loading…</p>;
>   return <pre>{JSON.stringify(detail, null, 2)}</pre>;
> }
> ```
>
> Prefer `useOfferDetails` unless you need custom control flow.

## Next step

> **[Requirements](/sdk/requirements)**
>
> Show the user what they must satisfy before they can participate.


# SDK structure
Source: https://docs.passage.coinlist.co/sdk/structure

The handful of patterns every part of the SDK follows: the ladder, namespaces, containers, hook state, and flows that return instead of throwing.

> [!TIP]
>
> **In a hurry?** Skip straight to [Set up OAuth authentication](/sdk/oauth-authentication) and come back when something surprises you. Nothing here is a prerequisite - this page is optional background.

The SDK follows a small set of consistent patterns. The five patterns below apply across the SDK.

## The same feature at three levels

Every feature is available at several levels. Here is one feature - listing offers - at all three:

```tsx theme={null}
// L3  Components. UI and behavior, working.
<OffersGridContainer onOfferClick={(offer) => router.push(`/offers/${offer.id}`)} />

// L2  Hooks. The behavior; you write the UI.
const { offersState } = useOffers();

// L1  Client. The logic; you write the state and the UI.
const offers = await passage.offers.list();

// Below L1 there is no SDK - call the HTTP API directly.
```

All three do the same work. They differ only in how much of it you take over. **Start at L3** and drop a rung when the one above cannot give you what you need.

Three things follow from this that are easy to miss:

* **You pick a rung per feature, not per application.** Rendering `<CheckoutContainer>` while driving `passage.offers.list()` yourself is normal, not a compromise. The rungs are built from each other, so mixing them cannot desynchronize anything.
* **A feature may stop at a rung, but never skips one.** A feature with a component always has the hooks and the namespace beneath it, so dropping a rung never leaves you without a way forward.
* **Each rung exposes its entry points, not its parts.** Per feature, the public surface is the root container (L3), the viewmodel behind it and the data hooks it is built from (L2), and the namespaces (L1). The views, steps and sub-screens a container composes are internal, so there is no supported way to render the SDK's markup over your own logic: take the container, or build your UI on the viewmodel and hooks.

> [!NOTE]
>
> L2 and L3 are browser-only, because a backend renders nothing. **L1 is the only level present everywhere**, which is why `passage.offers.list()` reads identically on your server and in your React tree. See [the grid in the quickstart](/sdk/quickstart#environment-where-code-runs).

## Namespaces

**The entire L1 surface is namespaces.** `passage.init()` is the only top-level member on the browser client, because it is lifecycle rather than domain; `PassageServer` has none at all. So every operation you will ever want is `passage.{something}.{verb}()`, and finding it means picking the right noun.

Two naming rules tell you which noun:

* **CoinList's own capabilities are named after what they do**: `auth`, `offers`, `requirements`, `wallets`, `erc20`, `tokenSale`, `tokens`, and the browser-only `support`.
* **A third party's namespace is named after the provider**: `superstate`, `ondo`, `centrifuge`. Not after what it does. A second provider ships its own swap, so `passage.swap` could only ever have meant one of them - which is exactly why it was renamed in v0.11.0.

Methods share one vocabulary, with the namespace's own noun dropped, so `offers.list()` rather than `offers.listOffers()`:

| Method | Meaning |
| - | - |
| `list()` | Every item, paginating for you |
| `listPage(params)` | One page, when you paginate yourself |
| `get(id)` | One item by id |
| `create*` / `submit*` / `remove*` | Writes |
| A real domain verb | Where one exists: `connect`, `connectExternal`, `allowWallet`, `execute` |

**Any method taking more than one argument takes a single params object.** Single-argument methods take the value directly. You never have to remember an argument order.

**API-backed methods throw `NotAuthenticatedError` when there is no session.** The one exception is `passage.tokens`, which is public: it reads a CDN, needs no login, and works with a read-only server session store. On-chain reads (`passage.erc20`, the `passage.superstate` reads, and `passage.centrifuge.readDepositPosition` and `readRedeemPosition`) are not API-backed: they go through CoinList's JSON-RPC proxy by default, which fails a logged-out read with a viem-wrapped `401`, or through your own node via `Config.rpc`, which needs no session. On `PassageServer`, when the SDK cannot find out whether a session exists (the token refresh hit a 5xx or a network failure after the access token expired), these methods throw that underlying error instead of `NotAuthenticatedError`.

> **[Package overview](/sdks#namespaces)**
>
> The full table of namespaces and their methods, for looking one up.

## Components

Every feature's component is a **container**: `CheckoutContainer`, `ClaimContainer`, `OffersGridContainer`, `RequirementsChecklistContainer`, `CoinListSignInCardContainer`. You hand it input and config, and it owns everything else. The only other components are a few presentational pieces you lay out yourself: `CoinListSignInButton`, `OfferAssetCard` and `OfferSaleCard`. `RequirementsChecklistView` is also still exported, as a loading placeholder, but is due to be removed, and `PassageStyleScope` is the styling wrapper every SDK component already puts around itself.

Three habits will keep you out of trouble:

* **Let the container decide for you.** `<CheckoutContainer>` routes on `offer.type` (and on its `side` prop for Ondo and Centrifuge), so a new provider is a version bump rather than your problem. The per-provider checkout containers are not exported. When you need your own UI for one provider, drop to L2 and render that product's viewmodel, such as `useOndoBuyCheckoutViewModel()`.
* **Optional `onX` callbacks are overrides, not wiring.** They default to something sensible - `RequirementsChecklistContainer`'s action button already calls `passage.requirements.handle`. Omit them until a default is wrong for you.
* **You never need a style provider.** Every exported component wraps its own output in a style scope, so it renders fully styled wherever you put it.

## Hooks

**State is a machine, not a pair of booleans.** Loading, error and content are one discriminated union with machine-readable `reason` codes:

```ts theme={null}
type LoadOffersState =
  | { type: "LOADING" }
  | { type: "ERROR"; reason: "not-authenticated" | "generic-error" }
  | { type: "CONTENT"; offers: Offer[] };
```

Switch on it exhaustively and assign the `default` branch to `const exhaustive: never = state`. A state added in a future release then becomes a compile error rather than a blank screen your users find first. The catalog hooks name the field after what it holds - `offersState`, `requirementsState`. Newer data hooks (`useErc20Balance`, `useSwapQuote`, the Ondo and Centrifuge hooks) return a plain `state`, and viewmodels return `{ state, onEvent }`.

Two options recur, and both exist because of how React works rather than as conveniences:

* **`data` is how server rendering works.** Pass data your backend already fetched with `PassageServer` and the hook uses it as-is, skipping the initial client fetch. Where a `refetch()` exists it still goes to the network: the seed answers the first render only. [Worked example](/sdk/fetch-offers#server-side-pre-fetch).
* **`enabled` is how you turn a hook off.** React forbids calling a hook conditionally, so a hook you cannot skip must instead go quiet: `enabled: false` means no requests and no timers. Most hooks then report a `DISABLED` state, since no answer is coming. The catalog reads (`useOffers`, `useOfferDetails`, `useRequirements`) have no `DISABLED` arm and stay in `LOADING` unless they already hold data. `useOptionAddresses` reports an empty `CONTENT` (or its `data` seed) while disabled. `CheckoutContainer` takes `enabled` too and forwards it to the checkout it mounts, to pause one that is mounted but not on screen yet.

## Flows return, they don't throw

Anything that drives a wallet - `passage.superstate.execute`, `passage.ondo.prepareBuy`, `passage.tokenSale.execute`, `passage.centrifuge.buy`, `passage.centrifuge.sell`, `passage.wallets.connect` - is a **flow**, and a flow is **total**. It does not throw. It returns a result tagged with the step that failed:

```ts theme={null}
const result = await passage.tokenSale.execute(tokenSaleParams);

if (result.type === "success") {
  // result carries what the flow produced
} else {
  // result.error.step names exactly what went wrong,
  // and carries a typed WalletError cause where a wallet was involved
}
```

That is the difference to internalize: **wrap namespace calls in try/catch, and branch on a flow's result.** Every step is documented per provider, so you can write real copy for a rejected signature instead of one generic message. Most flows also report progress through `onProgress`, a callback of named phases, so you can tell a user which wallet popup they are looking at.

Let your wallet library's own errors propagate out of your `EvmWallet` implementation. The SDK catches and classifies them into a typed `WalletError`, so you never parse a wallet error string. See [Wallets](/sdk/wallets).

## Next step

> **[Set up OAuth authentication](/sdk/oauth-authentication)**
>
> Add `PassageProvider`, a sign-in surface, callback handling, and server routes.


# Superstate Swap
Source: https://docs.passage.coinlist.co/sdk/swap-flow

Superstate swap offers: allowlisting a wallet, live on-chain quotes, and passage.superstate.execute.

Superstate supplies **tokenized equities**. A Superstate offer arrives with `type: "superstate::swap"` and settles **directly onchain**: the user pays with a stablecoin and receives the tokenized equity, an ERC-20, in the same flow.

> [!NOTE]
>
> **Recommended:** render [`CheckoutContainer`](/sdk/checkout). It detects `superstate::swap` and renders this entire flow - wallet step, amount, review, confirmation - for you. This page covers what is specific to Superstate, and the rungs below the component.

> [!NOTE]
>
> `passage.superstate` was the `swap` namespace before v0.11.0, and `executeSwap` is now `execute`. It is named after the provider now, because Ondo ships its own swap and `swap` could only ever mean one of them. See the [changelog](/changelogs/react) for the migration table.

## What Superstate needs from you

**Nothing.** The SDK looks up the swap contract for the chain you pass, and the funding assets and issuer are the provider's own constants. Every `CheckoutConfig` key is optional, and so is `config` itself. The `"superstate::swap"` entry takes one optional listener, `onOrderConfirmed`, which fires once the swap has mined. The confirmation dialog shows either way:

```tsx theme={null}
import { type CheckoutConfig, CheckoutContainer } from "@passage-cl/react";

const config: CheckoutConfig = {
  "superstate::swap": {
    onOrderConfirmed: (order) => console.log("Swap mined", order.swapTxHash),
  },
};

export function SwapCheckout() {
  return (
    <CheckoutContainer
      offer={offer}
      chain="ethereum_sepolia"
      wallets={wallets}
      config={config}
    />
  );
}
```

The SDK ships the Superstate swap contract for **Ethereum Sepolia only** today. On a chain with no contract, the checkout renders its flow-level error instead of quoting.

Three things distinguish Superstate from the other providers:

* **The wallet must be allowlisted.** Superstate only settles to addresses the issuer has approved. The user signs an ownership challenge and the SDK allowlists the address on the swap contract, once per wallet per offer. The same allowlists are what make permissioned DeFi pools and RWA lending markets reachable. That is also why the Superstate checkout never skips its wallet step: a `wallets.preselected` wallet opens the step with its row already selected, rather than skipping it (see [Wallets](/sdk/wallets#skipping-the-wallet-step)).
* **The fee is charged on top.** The wallet is debited `inputTokenAmount + fee`, so always show that sum as the total cost. (Ondo takes its fee off the deposit instead.)
* **Quotes are read quotes, polled every 15 seconds.** Nothing is committed until the swap itself, and slippage protection guards the on-chain minimum output. There is no expiring committed quote to race, as there is with Ondo.

## Prerequisites

* Completed [OAuth](/sdk/oauth-authentication) with a working `PassageProvider`
* A **swap-enabled offer**. CoinList provides the offer ID during onboarding - keep it in a constant (`SWAP_OFFER_ID`).
  > [!NOTE]
  >
  > Offers expose a `type` field, so you can detect Superstate swap offers from [fetch offers](/sdk/fetch-offers) data via `offer.type === "superstate::swap"` instead of hard-coding IDs. Ondo swap offers are `'ondo::swap'` and take a different flow.
* A wallet integration. The partner demo uses [wagmi](https://wagmi.sh/) + [Reown AppKit](https://reown.com/appkit); any stack that can sign messages and send transactions works. See [Wallets](/sdk/wallets).

```bash theme={null}
npm install @passage-cl/react wagmi @wagmi/core viem @reown/appkit @reown/appkit-adapter-wagmi @tanstack/react-query
```

> **Build your own UI with hooks (L2)**
>
> `useSuperstateSwapCheckoutViewModel` wraps the whole flow and returns `{ state, onEvent }`. Call it behind your own markup when you want the SDK's logic, state and error handling but not its UI.
>
> ```tsx theme={null}
> import { useSuperstateSwapCheckoutViewModel } from "@passage-cl/react";
>
> export function MySwapCheckout() {
>   const { state, onEvent } = useSuperstateSwapCheckoutViewModel({
>     offer,
>     chain: "ethereum_sepolia",
>     wallets,
>     // Optional: `enabled` (default true) and `onOrderConfirmed`.
>   });
>
>   if (state.type === "error") {
>     return <p role="alert">Swaps are unavailable ({state.reason}).</p>;
>   }
>   // Render state.wallet, state.amount, state.review, state.sidebar and
>   // state.orderConfirmed with your own markup, and send the user's actions
>   // to onEvent.
>   return <MySwapSteps state={state} onEvent={onEvent} />;
> }
> ```
>
> `state` is either `{ type: "error", reason }`, when the swap could not be loaded at all (no contract on the chain, or the output token read failed), or `{ type: "content" }` with one slice per region: `wallet`, `amount`, `review`, `sidebar`, and `orderConfirmed`. Each slice is a discriminated union of its own. `switch` on each exhaustively and assign the `default` to `const exhaustive: never`, so a new arm is a compile error rather than a blank screen.
>
> The data hooks it is built from are exported too, so you can assemble your own viewmodel instead:
>
> | Hook | What it does |
> | - | - |
> | `useSwapOutputToken` | Reads the tokenized equity's decimals and symbol from the contract, once. Returns `{ state, refetch }`; call `refetch()` to retry after an `ERROR`. |
> | `useSwapQuote` | Polls a live quote every 15s. Returns `{ state }`. |
> | `useErc20TokenBalances` | Per-asset wallet balances, for a Max button. Returns `{ state }`. |
>
> Each returns its result as a `state` union with `DISABLED`, `LOADING`, `ERROR` (with a `reason` of `"not-authenticated"` or `"generic-error"`), and `CONTENT` arms, and each takes a required `enabled` flag. Switched off with no answer in hand, a hook reports `DISABLED`. `useSwapQuote` keeps a quote it already has; `useErc20TokenBalances` drops its balances and reports `DISABLED` whenever it is switched off or has no `address`. Like all React hooks they must be called unconditionally. See [SDK structure](/sdk/structure#hooks) for the conventions they share.
>
> The step viewmodels (`useSuperstateAmountViewModel`, `useSuperstateWalletViewModel`, `useSuperstateReviewViewModel`, `useSuperstateSidebarViewModel`) and the `SlippagePicker` component are no longer exported since v0.13.0. Use the god viewmodel above, or build the steps yourself from the data hooks and the L1 namespace below.

> **Drive it yourself with the client (L1)**
>
> `passage.superstate` is a plain namespace with no React. The walkthrough below builds the flow from scratch and mirrors [partner-demo's `useSwapViewModel.tsx`](https://github.com/coinlist/partner-demo/blob/main/src/features/swap/useSwapViewModel.tsx), trimmed to the minimum that still compiles and runs.
>
> ### Flow at a glance
>
> ```mermaid theme={null}
> flowchart LR
>   connect[connect_wallet]
>   authorize[authorizing]
>   quote[quoting]
>   swapping[swapping]
>   success[success]
>   error[error]
>
>   connect -->|wallet connected| authorize
>   authorize -->|sign challenge + allow-list tx| quote
>   authorize -->|rejected / not authorized| error
>   quote -->|user confirms amount| swapping
>   swapping -->|approve + swap mined| success
>   swapping -->|rejected / reverted| error
>   error -->|retry| connect
> ```
>
> 1. **connect\_wallet** - your wallet UI; the SDK only needs the connected account.
>
> 2. **authorizing** - `passage.superstate.authorizeWallet` proves the user owns the wallet (a message signature) and allow-lists it for the offer, broadcasting an allow-list transaction if the contract requires one. One-time per wallet per offer.
>
> 3. **quoting** - `useSwapOutputToken` + `useSwapQuote` show a live quote (input, fee, output), refreshed every 15s.
>
> 4. **swapping** - `passage.superstate.execute` runs the ERC-20 approval and then the swap, reporting progress phases.
>
> 5. **success / error** - show the confirmed output amount and an explorer link, or a readable error.
>
> > [!NOTE]
> >
> > The flow involves **two identities**: the **CoinList session** (from OAuth) identifies *who* is buying, and the **external wallet** is *where* the shares are delivered. `authorizeWallet` is what links them - which is why the user signs a message before ever swapping.
>
> ### Step 1: Pin the swap parameters
>
> Keep the offer, chain, contract, and input token in one place. `superstateSwapContractAddress(chain)` returns the swap contract the SDK knows for a chain, or `null` where none is deployed. `TOKEN_REGISTRY` knows the ERC-20 metadata and per-chain address for USDC and USDT.
>
> ```ts constants.ts theme={null}
> import {
>   type EthereumChain,
>   type EvmContractAddress,
>   OfferId,
>   superstateSwapContractAddress,
>   TOKEN_REGISTRY,
>   USDC_SYMBOL,
> } from "@passage-cl/react/universal";
>
> // Provided by CoinList during onboarding.
> export const SWAP_OFFER_ID = OfferId("YOUR_SWAP_OFFER_ID");
>
> export const SWAP_CHAIN: EthereumChain = "ethereum_sepolia";
> export const SWAP_CONTRACT_ADDRESS = requireSwapContract(SWAP_CHAIN);
>
> function requireSwapContract(chain: EthereumChain): EvmContractAddress {
>   const address = superstateSwapContractAddress(chain);
>   if (address === null) {
>     throw new Error(`No Superstate swap contract on ${chain}`);
>   }
>   return address;
> }
>
> // The stablecoin the user pays with (USDC, 6 decimals).
> export const INPUT_TOKEN = TOKEN_REGISTRY.erc20(USDC_SYMBOL);
> export const INPUT_TOKEN_ADDRESS = TOKEN_REGISTRY.usdcAddress(SWAP_CHAIN);
>
> // BCP-47 locale used for amount formatting.
> export const LOCALE = "en-US";
> ```
>
> > [!NOTE]
> >
> > This page runs on **Sepolia** throughout. The SDK knows the Sepolia swap contract only, so `superstateSwapContractAddress("ethereum_mainnet")` returns `null` today. CoinList provides the production mainnet address when swaps go live. To move to mainnet, set `SWAP_CHAIN` to `"ethereum_mainnet"` and point `SWAP_CONTRACT_ADDRESS` at that address - `TOKEN_REGISTRY` already knows the mainnet USDC/USDT addresses.
>
> ### Step 2: Bring your wallet
>
> The swap flows never import wagmi. They drive **any** wallet through the `EvmWallet` interface, which you implement once for every flow in the SDK.
>
> > **[Wallets: the EvmWallet seam](/sdk/wallets)**
> >
> > The five members, the wagmi + AppKit adapter, and how wallet errors are classified.
>
> ```ts theme={null}
> import { buildEvmWallet } from "./wagmiEvmWallet";
> ```
>
> ### Step 3: Allowlist the wallet
>
> Superstate only settles to wallets the issuer has allowlisted. `passage.superstate.authorizeWallet` does both halves in one call: it proves the user controls the wallet by having them sign a challenge, then registers the address against the offer, broadcasting an allowlist transaction if the contract requires one.
>
> ```tsx theme={null}
> const wallet = buildEvmWallet({
>   address: EvmWalletAddress(address),
>   walletClient,
>   config,
> });
>
> const result = await passage.superstate.authorizeWallet({
>   wallet,
>   offerId: SWAP_OFFER_ID,
>   contractAddress: SWAP_CONTRACT_ADDRESS,
>   chain: SWAP_CHAIN,
>   onProgress: (phase) => setBusy({ kind: "authorize", phase }),
> });
>
> if (result.type === "success") {
>   setAuthorized(true);
> } else {
>   setError(result.error.step);
> }
> ```
>
> It is **idempotent**: if the wallet is already authorized it returns `success` immediately without prompting, so it is safe to call at the start of every session. Failures come back as `{ type: "error" }` rather than throwing.
>
> #### Parameters
>
> | Parameter | Type | Description |
> | - | - | - |
> | `wallet` | `EvmWallet` | An already-connected wallet that can sign messages and send transactions. |
> | `offerId` | `OfferId` | The offer to allowlist the wallet against. |
> | `contractAddress` | `EvmContractAddress` | The swap contract for the offer. |
> | `chain` | `EthereumChain` | The EVM chain to authorize on, for example `ethereum_mainnet`. |
> | `onProgress` | `(phase: WalletAuthorizationPhase) => void` | Optional. Called as the flow advances, for rendering loading states. |
>
> #### Progress phases
>
> Emitted in order. Two of them open a wallet popup. A wallet that is already authorized stops after `checking-authorization`:
>
> `checking-authorization` → `requesting-challenge` → **`signing-message`** *(wallet popup)* → `submitting-signature` → *(**`broadcasting-transaction`** (wallet popup) → `awaiting-confirmation`, only when the contract needs an allowlist transaction)* → `verifying-authorization`
>
> #### Error steps
>
> `WalletAuthorizationError` is tagged by the step that failed, so you can tell a user rejection apart from an infrastructure problem.
>
> | `step` | What happened |
> | - | - |
> | `authorization-check` | Reading the wallet's authorization failed: either the initial check, or the final on-chain re-check after the user signed (and possibly after the allowlist transaction was broadcast). |
> | `challenge-request` | Requesting the ownership challenge failed. |
> | `signing` | The user did not sign the challenge. Carries a `cause` of type `WalletError`. |
> | `allow-wallet` | Submitting the signature to allowlist the wallet failed. |
> | `broadcast` | The wallet never sent the allowlist transaction. Carries a `cause` of type `WalletError`. Authorizing again is safe. |
> | `broadcast-unconfirmed` | The allowlist transaction was sent, but waiting for its receipt failed. It may still mine, so authorizing again would send a second one. Carries the `txHash` to look up first, and a `cause` of type `WalletError`. |
> | `not-authorized` | The flow completed but the on-chain re-check still reports the wallet as unauthorized. |
>
> An allowlist transaction that reverts is not an error of its own: the flow goes on to the on-chain re-check, and reports `not-authorized` only if the contract still says no.
>
> `authorizeWallet` reads `authorized(address)` on the swap contract over JSON-RPC (through CoinList's authenticated RPC proxy unless you set `Config.rpc`), and calls two Frontline endpoints. The first is also `passage.wallets.createOwnershipChallenge`, which the [requirements checklist](/sdk/requirements) uses to bind a wallet to an offer option. For non-SDK integrations, Frontline also serves the authorization read as `GET /v1/wallet/authorized`.
>
> | Endpoint | Purpose |
> | - | - |
> | `POST /v1/wallet-ownership` | Requests a `plain` challenge for the user to sign. |
> | `POST /v1/offers/{offer_id}/allow-wallet` | Submits the signature and allowlists the address. |
>
> ### Step 4: Show a live quote
>
> Read the output token to learn its decimals, parse the user's input, then poll a quote. `useSwapQuote` waits while `outputTokenDecimals` is `null`; gate it on a valid amount yourself, through `enabled`.
>
> ```tsx theme={null}
> const { state: outputTokenState } = useSwapOutputToken({
>   contractAddress: SWAP_CONTRACT_ADDRESS,
>   chain: SWAP_CHAIN,
>   enabled: true,
> });
> const outputToken =
>   outputTokenState.type === "CONTENT" ? outputTokenState.outputToken : null;
>
> const parsed = parseBlockchainAmount(amountInput, INPUT_TOKEN.decimals);
> const hasAmount = parsed.valid && parsed.amount.raw > 0n;
> const inputAmount =
>   parsed.valid && parsed.amount.raw > 0n
>     ? parsed.amount
>     : BlockchainAmount({ raw: 0n, decimals: INPUT_TOKEN.decimals });
>
> const { state: quoteState } = useSwapQuote({
>   contractAddress: SWAP_CONTRACT_ADDRESS,
>   chain: SWAP_CHAIN,
>   inputAmount,
>   inputTokenAddress: INPUT_TOKEN_ADDRESS,
>   outputTokenDecimals: outputToken?.decimals ?? null,
>   enabled: authorized && hasAmount,
> });
>
> // A quote outlives a change of amount and being switched off. Input plus fee
> // is what the swap pulls. While a refresh is in flight, a quote that does not
> // price the amount on screen is the previous amount's. A settled quote may ask
> // for less (a partial fill: the rest stays in the wallet), never for more.
> const quote =
>   hasAmount && quoteState.type === "CONTENT" && quoteFits(quoteState)
>     ? quoteState.quote
>     : null;
>
> function quoteFits(state: { quote: SwapQuote; isRefreshing: boolean }): boolean {
>   const total = BlockchainAmount.add(state.quote.inputTokenAmount, state.quote.fee).raw;
>   return state.isRefreshing ? total === inputAmount.raw : total <= inputAmount.raw;
> }
> ```
>
> `quoteState` is `DISABLED` while switched off with no quote in hand, `LOADING` until the first quote lands (or while the output token's decimals are unknown), `ERROR` with a `reason` when no quote could be read at all, and `CONTENT` with `quote` and `isRefreshing` otherwise.
>
> A `SwapQuote` has `inputTokenAmount`, `fee`, and `outputTokenAmount`, all `BlockchainAmount`s. Render them with `formatAmount(amount, LOCALE)`, and derive the total and the slippage-protected minimum:
>
> ```tsx theme={null}
> const total = BlockchainAmount.add(quote.inputTokenAmount, quote.fee);
> const minReceived = computeSlip(quote.outputTokenAmount, DEFAULT_SLIPPAGE_BPS);
> ```
>
> > [!NOTE]
> >
> > The **fee is charged on top** of the amount that buys shares. The wallet is debited `inputTokenAmount + fee`, so always show that sum as the total cost.
>
> The quote refreshes every 15s; pass `pollIntervalMs` to change that. `isRefreshing` flags a newer quote on the way. A failed poll behind a quote in hand keeps the last quote, stays `CONTENT`, and retries on the next tick, so `ERROR` means the hook never got a quote. A quote also stays in `CONTENT` after you switch the hook off, and after the amount changes until the new quote lands, which is why the sample checks it against the amount before using it, the way the SDK's own review step does.
>
> ### Step 5: Execute the swap
>
> `passage.superstate.execute` runs the whole on-chain sequence and returns a discriminated result. It never throws.
>
> ```tsx theme={null}
> const result = await passage.superstate.execute({
>   wallet,
>   contractAddress: SWAP_CONTRACT_ADDRESS,
>   chain: SWAP_CHAIN,
>   inputTokenAddress: INPUT_TOKEN_ADDRESS,
>   quote,
>   slippageBps: DEFAULT_SLIPPAGE_BPS,
>   onProgress: (phase) => setBusy({ kind: "swap", phase }),
> });
>
> if (result.type === "success") {
>   // result: swapTxHash, inputAmount, fee, outputAmount, outputAmountConfirmed,
>   //   pricePerShare, recipientAddress
>   const amount = `${formatAmount(result.outputAmount, LOCALE)} ${outputToken.symbol}`;
>   const received = result.outputAmountConfirmed ? amount : `${amount} (estimated)`;
>   const explorerUrl = txExplorerUrl(SWAP_CHAIN, result.swapTxHash);
> } else {
>   // result.error.step: "status-check" | "swap-paused" | "swap-stopped" | "allowance-check"
>   //   | "approval" | "approval-reverted" | "swap" | "swap-unconfirmed" | "swap-reverted"
>   setError("The swap did not go through.");
> }
> ```
>
> Two of those steps need care before you offer a retry:
>
> * **`swap-unconfirmed`**: the wallet sent the swap, but waiting for its receipt failed. It may still mine, so swapping again can fill the order twice. It carries the `txHash` to look up first, and a `cause` of type `WalletError`. The SDK's own review step disables its button until the user leaves the step, with "Your swap was sent but has not confirmed yet. Check your wallet before placing another."
> * **`swap`** means the wallet never sent the swap (`cause` says why), so swapping again is safe.
>
> `swap-paused` means the contract has suspended swaps and may resume, so "try again shortly" fits. `swap-stopped` is permanent.
>
> > [!WARNING]
> >
> > **Read `outputAmountConfirmed` before you show `outputAmount` to a user.** It is `true` when the amount is decoded from the on-chain `Swapped` event, and `false` when that event would not decode and the quote's estimate stands in. The swap mined either way, so the order is settled - but an estimate labeled as a confirmed fill is the one way this flow can misreport what happened. `pricePerShare` derives from the same number and carries the same caveat.
>
> Phases (wallet popups marked):
>
> `checking-status` → `checking-allowance` → *(`resetting-allowance` → `confirming-allowance-reset`, only for stale non-zero allowances)* → **`approving`** *(wallet popup)* → `confirming-approval` → **`swapping`** *(wallet popup)* → `confirming-swap`
>
> When the standing allowance already covers `input + fee`, the approval phases are skipped.
>
> > [!NOTE]
> >
> > The user signs up to **two transactions** - an ERC-20 `approve` for `input + fee` when the allowance does not already cover it, then the swap itself. USDT-style tokens with a stale non-zero allowance need one extra reset transaction first. All read-only checks run *before* the first popup, so the user never signs a transaction that would revert.
>
> `slippageBps` sets the on-chain minimum-output guard. `DEFAULT_SLIPPAGE_BPS` is 0.5% and is fine for a minimal integration; see [Going further](#going-further) for a picker.
>
> ### Putting it together
>
> A complete, minimal swap component. It compiles against the current SDK release and reuses `constants.ts` (Step 1) and `buildEvmWallet` (Step 2).
>
> ```tsx MinimalSwap.tsx theme={null}
> "use client";
>
> import {
>   type SwapExecutionPhase,
>   usePassage,
>   useSwapOutputToken,
>   useSwapQuote,
>   type WalletAuthorizationPhase,
> } from "@passage-cl/react";
> import {
>   BlockchainAmount,
>   computeSlip,
>   DEFAULT_SLIPPAGE_BPS,
>   EvmWalletAddress,
>   formatAmount,
>   parseBlockchainAmount,
>   type SwapQuote,
>   txExplorerUrl,
> } from "@passage-cl/react/universal";
> import { useAppKit, useAppKitAccount } from "@reown/appkit/react";
> import { useEffect, useState } from "react";
> import { useConfig, useWalletClient } from "wagmi";
> import {
>   INPUT_TOKEN,
>   INPUT_TOKEN_ADDRESS,
>   LOCALE,
>   SWAP_CHAIN,
>   SWAP_CONTRACT_ADDRESS,
>   SWAP_OFFER_ID,
> } from "./constants";
> import { buildEvmWallet } from "./wagmiEvmWallet";
>
> type Busy =
>   | { kind: "authorize"; phase: WalletAuthorizationPhase }
>   | { kind: "swap"; phase: SwapExecutionPhase };
>
> const GENERIC_ERROR = "Something went wrong. Please try again.";
>
> export function MinimalSwap() {
>   const { passage, isReady } = usePassage();
>   const { open } = useAppKit();
>   const { address, isConnected } = useAppKitAccount();
>   const { data: walletClient } = useWalletClient();
>   const config = useConfig();
>
>   const [authorized, setAuthorized] = useState(false);
>   const [amountInput, setAmountInput] = useState("");
>   const [busy, setBusy] = useState<Busy | null>(null);
>   const [error, setError] = useState<string | null>(null);
>   const [confirmed, setConfirmed] = useState<{
>     received: string;
>     explorerUrl: string;
>   } | null>(null);
>
>   // The output token (the tokenized equity) tells us the decimals needed to quote.
>   const { state: outputTokenState, refetch: refetchOutputToken } =
>     useSwapOutputToken({
>       contractAddress: SWAP_CONTRACT_ADDRESS,
>       chain: SWAP_CHAIN,
>       enabled: true,
>     });
>   const outputToken =
>     outputTokenState.type === "CONTENT" ? outputTokenState.outputToken : null;
>
>   // Quoting stays disabled until the wallet is authorized, the output token is
>   // known, and the amount is a valid non-zero value.
>   const parsed = parseBlockchainAmount(amountInput, INPUT_TOKEN.decimals);
>   const hasAmount = parsed.valid && parsed.amount.raw > 0n;
>   const inputAmount =
>     parsed.valid && parsed.amount.raw > 0n
>       ? parsed.amount
>       : BlockchainAmount({ raw: 0n, decimals: INPUT_TOKEN.decimals });
>
>   const { state: quoteState } = useSwapQuote({
>     contractAddress: SWAP_CONTRACT_ADDRESS,
>     chain: SWAP_CHAIN,
>     inputAmount,
>     inputTokenAddress: INPUT_TOKEN_ADDRESS,
>     outputTokenDecimals: outputToken?.decimals ?? null,
>     enabled: authorized && hasAmount,
>   });
>   // A quote outlives a change of amount and being switched off. Input plus fee
>   // is what the swap pulls. While a refresh is in flight, a quote that does not
>   // price the amount on screen is the previous amount's. A settled quote may
>   // ask for less (a partial fill: the rest stays in the wallet), never for more.
>   const quoteFits = (fit: { quote: SwapQuote; isRefreshing: boolean }) => {
>     const total = BlockchainAmount.add(fit.quote.inputTokenAmount, fit.quote.fee).raw;
>     return fit.isRefreshing ? total === inputAmount.raw : total <= inputAmount.raw;
>   };
>   const quote =
>     hasAmount && quoteState.type === "CONTENT" && quoteFits(quoteState)
>       ? quoteState.quote
>       : null;
>   const isRefreshing = quoteState.type === "CONTENT" && quoteState.isRefreshing;
>
>   // If the connected account changes, the prior authorization no longer applies.
>   useEffect(() => {
>     setAuthorized(false);
>   }, [address]);
>
>   const buildWallet = () => {
>     if (!walletClient || !address) return null;
>     return buildEvmWallet({
>       address: EvmWalletAddress(address),
>       walletClient,
>       config,
>     });
>   };
>
>   const handleAuthorize = async () => {
>     const wallet = buildWallet();
>     if (!isReady || !wallet) return;
>     setError(null);
>     setBusy({ kind: "authorize", phase: "checking-authorization" });
>     try {
>       const result = await passage.superstate.authorizeWallet({
>         wallet,
>         offerId: SWAP_OFFER_ID,
>         contractAddress: SWAP_CONTRACT_ADDRESS,
>         chain: SWAP_CHAIN,
>         onProgress: (phase) => setBusy({ kind: "authorize", phase }),
>       });
>       if (result.type === "success") setAuthorized(true);
>       else setError(GENERIC_ERROR);
>     } catch {
>       setError(GENERIC_ERROR);
>     } finally {
>       setBusy(null);
>     }
>   };
>
>   const handleSwap = async () => {
>     const wallet = buildWallet();
>     if (!isReady || !wallet || !quote) return;
>     setError(null);
>     setBusy({ kind: "swap", phase: "checking-status" });
>     try {
>       const result = await passage.superstate.execute({
>         wallet,
>         contractAddress: SWAP_CONTRACT_ADDRESS,
>         chain: SWAP_CHAIN,
>         inputTokenAddress: INPUT_TOKEN_ADDRESS,
>         quote,
>         slippageBps: DEFAULT_SLIPPAGE_BPS,
>         onProgress: (phase) => setBusy({ kind: "swap", phase }),
>       });
>       if (result.type === "success" && outputToken) {
>         const amount = `${formatAmount(result.outputAmount, LOCALE)} ${outputToken.symbol}`;
>         setConfirmed({
>           received: result.outputAmountConfirmed ? amount : `${amount} (estimated)`,
>           explorerUrl: txExplorerUrl(SWAP_CHAIN, result.swapTxHash),
>         });
>       } else {
>         setError(GENERIC_ERROR);
>       }
>     } catch {
>       setError(GENERIC_ERROR);
>     } finally {
>       setBusy(null);
>     }
>   };
>
>   if (outputTokenState.type === "ERROR") {
>     return (
>       <div>
>         <p>Swaps are unavailable right now.</p>
>         <button onClick={refetchOutputToken}>Try again</button>
>       </div>
>     );
>   }
>
>   if (confirmed) {
>     return (
>       <div>
>         <h3>Swap complete</h3>
>         <p>You received {confirmed.received}.</p>
>         <a href={confirmed.explorerUrl} target="_blank" rel="noreferrer">
>           View transaction
>         </a>
>       </div>
>     );
>   }
>
>   if (!isConnected || !address) {
>     return <button onClick={() => open()}>Connect wallet</button>;
>   }
>
>   if (!authorized) {
>     return (
>       <div>
>         <button onClick={handleAuthorize} disabled={busy !== null || !walletClient}>
>           Authorize wallet
>         </button>
>         {busy?.kind === "authorize" && <p>{authorizePhaseLabel(busy.phase)}</p>}
>         {error && <p role="alert">{error}</p>}
>       </div>
>     );
>   }
>
>   const total = quote
>     ? BlockchainAmount.add(quote.inputTokenAmount, quote.fee)
>     : null;
>
>   return (
>     <div>
>       <input
>         inputMode="decimal"
>         placeholder={`Amount in ${INPUT_TOKEN.symbol}`}
>         value={amountInput}
>         onChange={(e) => {
>           if (e.target.value === "" || /^\d*\.?\d*$/.test(e.target.value)) {
>             setAmountInput(e.target.value);
>           }
>         }}
>       />
>
>       {quote && total && outputToken ? (
>         <dl>
>           <dt>You pay</dt>
>           <dd>
>             {formatAmount(quote.inputTokenAmount, LOCALE)} {INPUT_TOKEN.symbol}
>           </dd>
>           <dt>CoinList fee</dt>
>           <dd>
>             {formatAmount(quote.fee, LOCALE)} {INPUT_TOKEN.symbol}
>           </dd>
>           <dt>Total (charged to your wallet)</dt>
>           <dd>
>             {formatAmount(total, LOCALE)} {INPUT_TOKEN.symbol}
>           </dd>
>           <dt>You receive</dt>
>           <dd>
>             {formatAmount(quote.outputTokenAmount, LOCALE)} {outputToken.symbol}
>           </dd>
>           <dt>Minimum received</dt>
>           <dd>
>             {formatAmount(
>               computeSlip(quote.outputTokenAmount, DEFAULT_SLIPPAGE_BPS),
>               LOCALE,
>             )}{" "}
>             {outputToken.symbol}
>           </dd>
>         </dl>
>       ) : quoteState.type === "ERROR" ? (
>         <p role="alert">Could not fetch a quote. Retrying…</p>
>       ) : hasAmount ? (
>         <p>Fetching quote…</p>
>       ) : null}
>
>       <button
>         onClick={handleSwap}
>         disabled={!isReady || !quote || !walletClient || busy !== null}
>       >
>         Swap
>       </button>
>
>       {isRefreshing && <span> Refreshing quote…</span>}
>       {busy?.kind === "swap" && <p>{swapPhaseLabel(busy.phase)}</p>}
>       {error && <p role="alert">{error}</p>}
>     </div>
>   );
> }
>
> function authorizePhaseLabel(phase: WalletAuthorizationPhase): string {
>   switch (phase) {
>     case "signing-message":
>       return "Sign the message in your wallet…";
>     case "broadcasting-transaction":
>       return "Confirm the transaction in your wallet…";
>     default:
>       return "Authorizing…";
>   }
> }
>
> function swapPhaseLabel(phase: SwapExecutionPhase): string {
>   switch (phase) {
>     case "approving":
>       return `Approve ${INPUT_TOKEN.symbol} in your wallet…`;
>     case "swapping":
>       return "Confirm the swap in your wallet…";
>     default:
>       return "Working…";
>   }
> }
> ```
>
> The production-grade version - with balances, a slippage picker, per-step error copy, and a review screen - lives in [`useSwapViewModel.tsx`](https://github.com/coinlist/partner-demo/blob/main/src/features/swap/useSwapViewModel.tsx) in the partner demo.
>
> ### Going further
>
> * **Balances and a Max button** - `useErc20TokenBalances({ address, chain, assets: [USDC_SYMBOL], enabled })` returns `{ state }`. Its `CONTENT` arm carries `balances`, a `Map` of raw per-asset balances (`null` for a read that failed), so you can show the user's USDC and prefill the max amount. Balances refresh every 15s. It was `useSwapTokenBalances` before v0.11.0.
> * **A slippage picker** - `SLIPPAGE_OPTIONS_BPS` (0.25%-5%) with `formatBpsAsPercent(bps, LOCALE)` for labels; pass the selected `Bps` to `passage.superstate.execute`.
> * **A quote without React** - `passage.superstate.getQuote({ contractAddress, chain, inputToken, amount, outputTokenDecimals })` returns the same `SwapQuote` the hook polls, and `passage.superstate.getOutputToken({ contractAddress, chain })` the output token.
> * **More formatting helpers** in `@passage-cl/react/universal`: `shortenAddress`, `formattedPricePerShare`.

## Common questions

> **Why does the user sign a message before swapping?**
>
> The flow has two identities: the OAuth **CoinList session** is *who* is buying, and the **external wallet** is *where* shares are delivered. `authorizeWallet` links them - the user signs an ownership challenge, and the SDK allow-lists that address on the swap contract. It's one-time per wallet per offer, and returns success immediately on later calls if the wallet is already authorized.

> **Why does my wallet ask for two transactions?**
>
> A swap needs an ERC-20 `approve` (for `input + fee`) before the swap itself, so the contract can pull the stablecoin. USDT-style tokens that already have a stale non-zero allowance need one extra reset-to-zero transaction first. Every read-only check (status, allowance) runs before the first popup, so the user never signs a transaction that would revert.

> **How fresh is the quote, and what if the price moves?**
>
> `useSwapQuote` polls every 15s. On execution, `passage.superstate.execute` passes a slippage-derived minimum output to the contract, so if the price moves beyond your `slippageBps` the swap reverts rather than over-charging. The result's `outputAmount` is decoded from the on-chain `Swapped` event when the receipt yields one, and falls back to the quote's estimate when it does not - `outputAmountConfirmed` tells you which one you got.

> **Do I need wagmi / Reown AppKit specifically?**
>
> No. Anything implementing the five-member `EvmWallet` interface works - viem directly, Privy, ethers with a thin adapter. The SDK only calls `signMessage`, `writeContract`, `broadcastRawTx`, and `awaitTx`; it never sees your wallet library.

> **How do I go to mainnet?**
>
> This page uses Sepolia everywhere, and the SDK knows the Sepolia swap contract only. CoinList provides the production swap contract address and swap offer ID during onboarding. Set `SWAP_CHAIN` to `"ethereum_mainnet"`, point `SWAP_CONTRACT_ADDRESS` at the mainnet contract, and the wallet adapter's `CHAINS` map handles the network switch. `CheckoutContainer` runs on mainnet once the SDK ships that contract.

## Next step

> **[See the full swap implementation](https://github.com/coinlist/partner-demo/tree/main/src/features/swap)**
>
> The partner demo's swap feature adds balances, slippage selection, a review screen, and typed error handling on top of this flow.


# Wallets: the EvmWallet seam
Source: https://docs.passage.coinlist.co/sdk/wallets

Implement EvmWallet once and every Passage on-chain flow works with your wallet stack. Prove ownership, allowlist addresses, and hand wallets to CheckoutContainer.

The SDK ships **no wallet stack**. It is not coupled to Privy, Turnkey, AppKit, wagmi, or anything else, and it never asks a user to connect. Wallet discovery, connection, and disconnection are your app's job.

That is deliberate. A partner may be a wallet provider themselves, and every partner already has a wallet story before they reach Passage. So the SDK inverts it: you implement one small interface, `EvmWallet`, and the SDK drives it. Do that once and every on-chain flow works - Superstate swaps, Ondo buys and sells, Centrifuge investments, redemptions and claims, token-sale approvals, ownership proofs.

Using an embedded wallet provider? See [Wallet partners](/wallet-partners) for providers with a documented Passage integration.

> [!NOTE]
>
> The SDK uses and ships [viem](https://viem.sh/) types, the de-facto TypeScript standard for Ethereum, so the interface lines up with whatever you are already using. A `SolanaWallet` seam will follow the same shape when Solana lands.

## Two shapes, one seam

There are two interfaces, and the smaller one is a subset of the larger.

| Interface | Members | Needed for |
| - | - | - |
| `EvmSigner` | `address`, `signMessage` | Proving wallet ownership. No gas, no transaction. |
| `EvmWallet` | the two above, plus `writeContract`, `broadcastRawTx`, `awaitTx` | Everything on-chain: approvals, swaps, allowlist transactions. |

`EvmWallet extends EvmSigner`, so implementing the full interface satisfies both. If all you need is the requirements checklist binding a wallet to an offer option, a signer is enough and your users never see a gas prompt. Those entry points take a `ConnectWallet`, which is an `EvmSigner` plus the `chain` the signature is proven on (`EvmSigner & { readonly chain: EthereumChain }`).

All of these types come from `@passage-cl/react/universal`. Since v0.13.0 the root entry point no longer re-exports them.

## Implement EvmWallet

```ts theme={null}
import type { EvmWallet } from "@passage-cl/react/universal";
```

| Member | Signature | What the SDK does with it |
| - | - | - |
| `address` | `EvmWalletAddress` | Reads balances and allowances, and names the sender. |
| `signMessage` | `(message: string) => Promise<Hex>` | Ownership challenges and allowlist authorization. |
| `writeContract` | `(params: WriteContractParams) => Promise<Hash>` | ERC-20 `approve`, and any contract call the SDK encodes itself. |
| `broadcastRawTx` | `(params: BroadcastTxParams) => Promise<Hash>` | Sends backend-encoded calldata **verbatim**. Never re-encode it: the contract verifies a signature over the exact arguments inside. |
| `awaitTx` | `(hash: Hash, chain: EthereumChain) => Promise<TransactionReceipt>` | Waits for confirmation before advancing a flow. |

Every method that takes a chain gets it as an explicit parameter. Switch the wallet to that chain before acting - the SDK does not assume your wallet is already pointed at the right one.

## Adapter: wagmi and AppKit

This is the canonical adapter, and it is the one the [partner demo](https://github.com/coinlist/partner-demo) runs. Any stack that can sign a message and send a transaction works the same way.

```ts wagmiEvmWallet.ts theme={null}
import type {
  EthereumChain,
  EvmWallet,
  EvmWalletAddress,
} from "@passage-cl/react/universal";
import {
  type Config,
  getChainId,
  switchChain,
  waitForTransactionReceipt,
} from "@wagmi/core";
import { type Chain, encodeFunctionData, type WalletClient } from "viem";
import { base, baseSepolia, mainnet, sepolia } from "viem/chains";

// `Record<EthereumChain, Chain>` is total on purpose: the day the SDK models a
// new chain, this table fails to compile until you decide what it maps to.
const CHAINS: Record<EthereumChain, Chain> = {
  ethereum_mainnet: mainnet,
  ethereum_sepolia: sepolia,
  base_mainnet: base,
  base_sepolia: baseSepolia,
};

export function buildEvmWallet({
  address,
  walletClient,
  config,
}: {
  address: EvmWalletAddress;
  walletClient: WalletClient;
  config: Config;
}): EvmWallet {
  const account = address as `0x${string}`;

  // Each call passes the target chain; switch the wallet there first.
  const ensureChain = async (chain: EthereumChain): Promise<Chain> => {
    const target = CHAINS[chain];
    if (getChainId(config) !== target.id) {
      await switchChain(config, { chainId: target.id });
    }
    return target;
  };

  return {
    address,
    signMessage: (message) => walletClient.signMessage({ account, message }),
    async writeContract({ abi, address: to, functionName, args, value, chain }) {
      const targetChain = await ensureChain(chain);
      const data = encodeFunctionData({ abi, functionName, args });
      return walletClient.sendTransaction({
        account,
        chain: targetChain,
        to,
        data,
        value,
      });
    },
    async broadcastRawTx({ to, data, chain }) {
      const targetChain = await ensureChain(chain);
      return walletClient.sendTransaction({ account, chain: targetChain, to, data });
    },
    awaitTx: (hash, chain) =>
      waitForTransactionReceipt(config, { hash, chainId: CHAINS[chain].id }),
  };
}
```

```bash theme={null}
npm install @passage-cl/react wagmi @wagmi/core viem @reown/appkit @reown/appkit-adapter-wagmi @tanstack/react-query
```

## Let wallet errors propagate

**Do not catch and translate your wallet library's errors.** Let them throw. The SDK catches them and classifies them into a typed `WalletError`, so you never parse a wallet error string yourself. It walks viem's error `cause` chain, so a rejection wrapped two levels deep still classifies:

| `WalletError` `type` | Cause |
| - | - |
| `user_rejected` | The user dismissed the wallet prompt. |
| `insufficient_funds` | The account's native token cannot pay the gas plus the transaction's `value`. |
| `contract_reverted` | The transaction reverted. Carries `reason`: the contract's revert string, error name, or selector, or `null` when the revert carried no data. |
| `timeout` | Confirmation did not arrive in time. Carries the transaction `hash`. |
| `unknown` | Anything the SDK could not classify. Carries the raw `cause`. |

Flows surface it as the `cause` on the step that failed, so you can tell a user rejection apart from an infrastructure problem. See [Errors and edge cases](/sdk/errors) for the full breakdown.

## Proving wallet ownership

Two identities are involved in every Passage purchase, and they are not the same thing:

* The **CoinList session** (from [OAuth](/sdk/oauth-authentication)) identifies *who* is investing.
* The **wallet** is *where* the assets are delivered.

An ownership proof is what links them, which is why the user signs a message before they can transact. Some offers go further: the issuer only settles to wallets they have allowlisted. Superstate assets work this way, and the same allowlists are what make permissioned DeFi pools and RWA lending markets reachable.

Ownership proof is provider-agnostic, so it lives on the platform namespace rather than being duplicated per provider:

```ts theme={null}
const challenge = await passage.wallets.createOwnershipChallenge({
  challengeType: "siwe",          // or "plain"
  walletAddress: wallet.address,
  chain: "ethereum_mainnet",
  domain: window.location.host,
  uri: window.location.origin,
  statement: "Sign to prove you own this wallet.",
});

const signature = await wallet.signMessage(challenge.message);

const binding = await passage.wallets.connectExternal({
  offerId,
  offerOptionId,
  walletAddress: wallet.address,
  chain: "ethereum_mainnet",
  signature,
});
```

Every `passage.wallets` method requires a signed-in user. All of them except `connect` throw `NotAuthenticatedError` otherwise; `connect` returns a `not_authenticated` error instead.

In the browser, `passage.wallets.connect` runs the same three steps in one call: it requests a challenge (SIWE by default, with `domain` and `uri` taken from the current page), has the wallet sign it, and submits the signature. Its `wallet` is a `ConnectWallet`, and it never throws. It resolves `{ type: "success", binding }`, `{ type: "cancelled" }` (only when your optional `isCancelled` callback returns `true` before the signing or binding step), or `{ type: "error", error: { code, retryable } }`, where `code` is `not_authenticated`, `user_rejected`, `wallet_not_whitelisted`, `max_wallets_reached`, or `unknown`:

```ts theme={null}
const result = await passage.wallets.connect({
  wallet: {
    address: wallet.address,
    signMessage: (message) => wallet.signMessage(message),
    chain: "ethereum_mainnet",
  },
  offerId,
  offerOptionId,
});

if (result.type === "error" && !result.error.retryable) {
  // A terminal failure: signing again with this wallet cannot succeed.
}
```

`passage.wallets` also reads and removes those bindings: `list({ offerId, offerOptionId })` returns the wallets bound to an option, and `remove({ offerId, addressId })` unbinds one.

> [!TIP]
>
> You rarely need to write the sequence above. [`RequirementsChecklistContainer`](/sdk/requirements) runs it for you when an offer has an `external_wallet` or `whitelisted_wallet` requirement, and the [Superstate Swap](/sdk/swap-flow) allowlist flow wraps it in one idempotent call.

## CheckoutWalletSelection: what checkout takes

`EvmWallet` is what the SDK *drives*. `CheckoutWalletSelection` is what you *hand* [`CheckoutContainer`](/sdk/checkout): the wallets the buyer may spend from, your connector for an external one, and optionally the wallet you have already settled on.

It is the shared `WalletSelection` (from `@passage-cl/react/universal`, the same shape every SDK screen reads its wallets from) plus one checkout-only field, `preselected`:

```ts theme={null}
import type { CheckoutWalletSelection } from "@passage-cl/react";

const wallets: CheckoutWalletSelection = {
  // The user's embedded (custodial) wallets, in display order.
  // Empty is a normal state, not an error.
  embedded: embeddedWallets,
  // The connected external wallet, or null while none is connected.
  external: externalWallet,
  // Your external-wallet connector, or null to offer none. With null and no
  // connected `external` wallet, the external-wallet row is hidden (for an
  // app with embedded wallets only).
  externalAdapter: {
    // Opens your wallet connector. The SDK reads the outcome from `external`
    // on the next render, not from a return value, so a redirect-based
    // connector works. Reject to report a declined or failed connection.
    connect: () => openConnectModal(),
    // Resolves once the external wallet is gone.
    disconnect: () => disconnect(),
  },
  // A wallet you have already settled on, or null to let the user pick.
  preselected: null,
};
```

`externalAdapter` is one object rather than two optional lambdas, because a screen that can connect a wallet must also be able to let it go. You can still pass a connected `external` with a `null` adapter, to show a wallet the user cannot change from the checkout. If your `disconnect` rejects, the SDK logs it and keeps the current selection.

### Skipping the wallet step

Set `preselected` to a ready `EvmWallet` when the page already knows the answer: a sell page reached from a position knows which wallet holds it, and an app with a single embedded wallet has only one answer on a buy too. Asking again would be a question with one possible answer. Every checkout honors it, in one of two ways:

* **Ondo buy, Ondo sell, Centrifuge buy, Centrifuge sell (redeem), and the CoinList token sale skip the wallet step.** The checkout opens on the amount and renumbers the cards that remain. The wallet does not have to appear in `embedded` or `external`: you supply a ready `EvmWallet`, and these flows never resolve it back to a row.
* **Superstate never skips its wallet step**, because that step allowlists the wallet on-chain and no preselection can stand in for it. The step opens with the preselected wallet's row already selected, so the user confirms it rather than finding it. That needs a row: a preselected wallet that matches neither an `embedded` wallet nor the connected `external` one by address selects nothing.

It is read **once, at mount**. Changing it mid-flow is ignored: the approval that follows the amount step is granted by one specific wallet, and moving the flow onto another under it would strand that approval. If your preselection can change on one page, add `wallets.preselected?.address` to the checkout's remount `key`. After an order, the flow resets to the step it opened on, so a skipped wallet step stays skipped.

The rest of `wallets` stays live: a newly connected external wallet appears as a row without a remount.

There is deliberately no separate wallet model here: `EvmWallet` already carries the `address`, so an `{ address, signer }` pair would be a second wallet type to keep in sync with the first. Everything a wallet row displays beyond the address - the network name - comes from the checkout's execution chain rather than from the wallet, because that is the chain the transaction goes to whatever the wallet is currently pointed at.

## Next step

> **[Building the Checkout flow](/sdk/checkout)**
>
> Hand your wallets to `CheckoutContainer` and let it render whichever provider the offer belongs to.


# Package overview
Source: https://docs.passage.coinlist.co/sdks

Install @passage-cl/react - React UI, hooks, client, and server utilities for Passage.

The **`@passage-cl/react`** package is the recommended way to integrate Passage in React and Next.js apps with a backend. It gives you OAuth with PKCE on the client, token exchange and sessions on the server, and ready-made UI for common flows.

For a linear walkthrough, start with [SDK quickstart](/sdk/quickstart).

## Requirements

* **React** and **React DOM** 18 or 19 (`^18.0.0 || ^19.0.0`), and **viem** 2 (`^2.0.0`), as peer dependencies
* **Node.js** `^20.19.0 || >=22.12.0` (the package's `engines` field)
* An **ES module** toolchain. The package is ESM-only. Bundlers such as Next.js, Vite and webpack consume it natively, and `require()` works only through Node's built-in `require(esm)` support in the Node versions above
* A **backend** you control to store `client_secret`, exchange authorization codes, and keep refresh tokens out of the browser

## Install

```bash theme={null}
npm install @passage-cl/react
```

```bash theme={null}
pnpm add @passage-cl/react
```

```bash theme={null}
yarn add @passage-cl/react
```

[NPM](https://www.npmjs.com/package/@passage-cl/react)

## Entry points

The package exposes three canonical entry points:

| Path | Use for |
| - | - |
| `@passage-cl/react` | React client - `PassageProvider`, root components (`CheckoutContainer`, `ClaimContainer`, `CoinListSignInCardContainer`, `OffersGridContainer`, `RequirementsChecklistContainer`, plus the `CoinListSignInButton`, `OfferSaleCard` and `OfferAssetCard` primitives, `PassageStyleScope`, and `RequirementsChecklistView`, which is due to be removed), hooks (`usePassage`, `useOffers`, `useOfferDetails`, `useCoinListTokenSaleParticipations`, `useRequirements`, `useCompleteOAuth`, `useTokenMetadata`, and each checkout's viewmodel), `PassageClientInitializationError`, `pinoClientLogger`, and `PassageClient` / `createPassageClient` for non-React or advanced wiring |
| `@passage-cl/react/server` | Node / SSR - `PassageServer`, `createPassageServer`, `pinoServerLogger`, and the `SessionStore` contract with `emptySessionStore` and `WritableSessionStoreRequiredError`, for Next.js route handlers and Server Components |
| `@passage-cl/react/universal` | Isomorphic domain types - `Offer`, `OfferDetail`, `Participation`, `Requirement`, `TokenMetadata`, `ClientId`, `RedirectUri`, the `EvmWallet` port and `WalletError`, the `Logger` port, pagination types, error classes (`HttpError`, `NotAuthenticatedError`, `ValidationError`, `InvariantError`, `MathError`, `NotImplementedError`) with `apiErrorCode`, formatters, and swap/KYC/PII types |

Every name has exactly one entry point, the one whose environment declares it. The client entry point does not re-export universal names, so import domain types, the `EvmWallet` and `Logger` ports and the error classes from `@passage-cl/react/universal` even in a React app. Reach for `/server` only inside server-side code. The package is ESM-only, so all three entry points share one copy of each class, and `instanceof HttpError` holds whichever entry point an error came from.

The public surface is root containers, the viewmodels and data hooks behind them, and the namespaces. Views, step components and step viewmodels are internal. To build your own UI, use a product's checkout viewmodel, such as `useOndoBuyCheckoutViewModel`, and render your own markup.

Sub-path imports like `/client/components` and `/client/hooks` were removed in v0.5.0, and `/shared` was renamed to `/universal` in v0.12.0 - see the [React SDK changelog](/changelogs/react). v0.13.0 renamed the package from `@coinlist-co/react` to `@passage-cl/react`, with no deprecated aliases.

## Namespaces

The whole public surface is namespaces. On the client, `init()` is the only top-level member, because it is lifecycle rather than domain; `PassageServer` has none at all.

CoinList's own namespaces are named after what they do. A third-party provider's namespace is named after the **provider**, because a second provider ships its own swap and `passage.swap` could only ever mean one of them.

| Namespace | Contains | Client | Server |
| - | - | - | - |
| `passage.auth` | Auth state and the OAuth flow. Browser: `getState`, `startOAuth`, `completeOAuth`, `logout`. Backend: `completeOAuth`, `getAccessToken`, `clientCredentials`, `logout` | ✓ | ✓ |
| `passage.offers` | The offer catalog: `list`, `listPage`, `get` | ✓ | ✓ |
| `passage.requirements` | What a user must satisfy before participating: `forOffer`, `statuses`, `createKycToken`, `getPii`, `submitDocument`, plus client-only `handle` | ✓ | ✓ |
| `passage.wallets` | External wallets: `createOwnershipChallenge`, `connectExternal`, `list`, `remove`, plus client-only `connect`, which proves ownership and binds a wallet to an offer option in one call | ✓ | ✓ |
| `passage.erc20` | Generic ERC-20 reads shared by every on-chain flow: `getAllowance`, `getBalance` | ✓ | ✓ |
| `passage.tokenSale` | CoinList token sales: `list`, `listPage`, `get`, `createParticipation`, plus client-only `execute` | ✓ | ✓ |
| `passage.superstate` | Superstate swaps: `getPreview`, `getQuote`, `getAuthorization`, `getStatus`, `getOutputToken`, `allowWallet`, plus client-only `execute` and `authorizeWallet` | ✓ | ✓ |
| `passage.ondo` | Ondo swaps, both directions: `getTradingStatus`, `getQuote`, `buildBuyTransaction`, `buildSellTransaction`, plus client-only `prepareBuy`, `prepareSell` and `executeSwap` | ✓ | ✓ |
| `passage.centrifuge` | Centrifuge vaults (`@alpha`): `getVaultStatus`, `readDepositPosition`, `readRedeemPosition`, `buildBuyTransaction`, `buildRedeemTransaction`, plus client-only `buy`, `sell`, `prepareBuy`, `prepareSell`, `placeRequest` and `claim` | ✓ | ✓ |
| `passage.tokens` | Token display metadata from CoinList's public registry: `get`, `list`. Unauthenticated | ✓ | ✓ |
| `passage.support` | `contact()` | ✓ | |

Methods follow one vocabulary, with the namespace's own noun dropped: `list()` (every item, auto-paginating), `listPage(params)`, `get(id)`, and `create*` / `submit*` / `remove*` for writes, plus a real domain verb where one exists (`connectExternal`, `allowWallet`, `execute`). Any method taking more than one argument takes a single params object. [SDK structure](/sdk/structure#namespaces) explains why the namespaces are named as they are, and the patterns the hooks and components above follow.

Unless a namespace says otherwise, its API-backed methods require a logged-in user and throw `NotAuthenticatedError`. `passage.tokens` is the exception: it is public, so it works with no session and with a read-only server session store.

On-chain reads - `passage.erc20`, the `passage.superstate` reads and the Centrifuge position reads - call the contract directly. By default they go through CoinList's authenticated JSON-RPC proxy, so a logged-out read fails with the proxy's `401` as a viem error rather than `NotAuthenticatedError`. A chain you point at your own node with `Config.rpc` needs no CoinList session.

v0.11.0 moved the last flat methods into namespaces and renamed `swap` to `superstate`. v0.12.0 forked `ondo`'s order builders by direction. v0.13.0 added `centrifuge`, `wallets.connect` and `superstate.getQuote`, and `usePassage()` returns the client as `passage` where `useCoinList()` returned `coinlist`. v0.14.0 added the Centrifuge redemption (`centrifuge.buildRedeemTransaction`, `prepareSell` and `sell`), and removed `centrifuge.createClaim` and `createClaimProceeds`, because `centrifuge.claim` now encodes the claim itself. See the [changelog](/changelogs/react) for the full migration tables.

## Next steps

> **[SDK structure](/sdk/structure)**
>
> The ladder, namespaces, hook state, and flows that return instead of throwing.

> **[Set up OAuth authentication](/sdk/oauth-authentication)**
>
> End-to-end sign-in with backend session.

> **[Building the Checkout flow](/sdk/checkout)**
>
> One container that renders whichever provider an offer belongs to.

> **[Errors and edge cases](/sdk/errors)**
>
> Every error shape the flows return, and how to handle them.


# Support
Source: https://docs.passage.coinlist.co/support

Get help with Passage.

## Get help

> **[Submit a ticket](https://support.coinlist.co/en/support/tickets/new)**
>
> Open a support ticket with the CoinList support team.

> **[Contact sales](https://airtable.com/appAjHhqZC9FIPEuR/pagRl25Yb4UNpremc/form?prefill_utm_source=docs\&hide_utm_source=true\&prefill_utm_medium=web\&hide_utm_medium=true\&prefill_utm_campaign=passage_site_cta_2026_08\&hide_utm_campaign=true\&prefill_utm_content=support_contact_sales\&hide_utm_content=true)**
>
> Questions about integrating Passage, or about your setup and licensing.

## Platform status

Check real-time platform and service status at [status.coinlist.co](https://status.coinlist.co/).

## See the integration running

> **[Partner demo repo](https://github.com/coinlist/partner-demo)**
>
> Clone the Partner Demo repo to see the SDK integration end to end.

> **[Live partner demo](https://partner.coinlist.dev/)**
>
> Open the hosted Partner Demo site to see it running.


# Lending pools and vaults
Source: https://docs.passage.coinlist.co/use-cases/lending-pools-vaults

Let your users borrow stablecoins against their RWA holdings or deposit into a vault to access enhanced yield.

DeFi lending platforms run dedicated lending pools and vaults for RWA assets. Allowlisted assets require your users to be registered first, and Passage handles that registration as part of the flow.

## Build it

> **[Allowlist a wallet](/sdk/wallets#proving-wallet-ownership)**
>
> Prove wallet ownership and register it against an offer with `authorizeWallet`.


# Permissioned DeFi pools
Source: https://docs.passage.coinlist.co/use-cases/permissioned-defi-pools

Register your users' wallets onto the allowlists for permissioned assets that unlock DeFi pools for tokenized assets, to support trading in Uniswap and other onchain AMMs.

Tokenization platforms including Superstate and Securitize are launching permissioned pools with Uniswap where only allowlisted wallets can interact. You can register your user wallets via Passage to their allowlists. Passage handles the entire onboarding flow end to end, with no management required from you.

This allows eligible users to trade supported assets through permissioned DeFi pools.

## Platforms and assets supported

| Platform | Status |
| - | - |
| Superstate | Available |
| Securitize | Coming soon |
| WisdomTree | Coming soon |

Learn more in [Rails Without Riders: How Passage Qualifies Users for Uniswap's Permissioned Pools](https://blog.coinlist.co/rails-without-riders-how-passage-qualifies-users-for-uniswaps-permissioned-pools/).

## Build it

> **[Allowlist a wallet](/sdk/wallets#proving-wallet-ownership)**
>
> Prove wallet ownership and register it against an offer with `authorizeWallet`.


# Run your raise
Source: https://docs.passage.coinlist.co/use-cases/run-your-raise

Raise on CoinList, host the sale on your own platform, or do both, with Passage handling compliance and settlement either way.

**Who it's for:** projects and platforms raising capital for their own token, rather than surfacing someone else's sale.

> [!NOTE]
>
> This is the issuer side of a token sale. If you want to offer your users access to sales that CoinList already runs, see [Token sales](/use-cases/token-sales) instead.

## Two ways to run it

These distribution models are not mutually exclusive. The same offering can be distributed both ways at once, and the compliance, payment, and distribution rails underneath are the same.

| | Raise on CoinList | Host it yourself |
| - | - | - |
| **Where the sale lives** | The CoinList platform | Your own app, built on the Passage SDK |
| **Who owns the front end** | CoinList | You |
| **Who brings the participants** | CoinList's audience, plus your community | Your users, plus any distribution partners you add |
| **What you control** | Sale terms, token economics, marketing | All of the above, plus the entire user experience |
| **Best when** | You want reach and want the sale run for you | You already have an audience and want them to stay in your product |

### Raise on CoinList

CoinList runs the sale end to end. You define the offering, and CoinList provides the sale page, the participant base, and the operational lift on sale day.

You are responsible for token economics and sale terms, marketing and community communications, post-sale reporting to your investors, and long-term token operations. Everything else sits on the Passage side.

### Host the sale on your own platform

You build the sale experience into your own product using the SDK, and Passage runs the same compliance and settlement underneath. Your users sign in, qualify, and contribute without leaving your app.

This is the right shape when you already own the user relationship and don't want to send people elsewhere to participate in your own raise.

## What Passage handles either way

* KYC, AML screening, and identity verification
* Jurisdiction and eligibility checks, configured per sale round
* Payment collection and settlement
* Smart contract deployment for the offering
* Token distributions, vesting, and lockups
* Investor disclosures and document signing

## What you configure

Sale terms are set per offering and per round, and typically cover:

* **Schedule** - when the sale opens and closes
* **Pricing and caps** - price per token, total raise cap, per-round caps
* **Sale rounds** - separate pricing and eligibility per round
* **Accepted currencies** - which assets participants can pay with
* **Vesting and lockups** - cliff, duration, and unlock schedule per round
* **Eligibility** - jurisdictions, KYC level, and accreditation requirements

Work with your Passage account manager to define these and to submit the documentation for compliance review.

## Build it

> **[CoinList Token Sale](/sdk/invest-flow)**
>
> Approve funds and record a participation with `passage.tokenSale.execute`.

> **[Participations](/sdk/invest-flow#track-participations)**
>
> Read and create participations, and track their status over time.

> **[Fetch offers](/sdk/fetch-offers)**
>
> Surface your offering and its rounds in your own UI.

> **[Talk to us](mailto:sales@coinlist.co)**
>
> Scope your raise and start the compliance review.


# Embed token sales
Source: https://docs.passage.coinlist.co/use-cases/token-sales

Offer your users access to CoinList token sales, embedded in your app.

**Who it's for:** platforms whose users want early access to new token offerings, with compliance and settlement handled by Passage.

**The flow:** sign in, qualify for the specific offering (eligibility varies per sale), contribute through the invest flow, and receive distributions on the configured schedule, including any vesting or lockups.

> [!NOTE]
>
> This is for surfacing sales that CoinList already runs. If you are raising for your own token, see [Run your raise](/use-cases/run-your-raise).

## Build it

> **[CoinList Token Sale](/sdk/invest-flow)**
>
> Approve funds and record a participation with `passage.tokenSale.execute`.

> **[Participations](/sdk/invest-flow#track-participations)**
>
> Read and create participations for a sale.


# Embed tokenized stocks and funds
Source: https://docs.passage.coinlist.co/use-cases/tokenized-assets

Let your users buy, hold, and sell tokenized stocks and funds natively inside your app.

**Who it's for:** fintechs, neobanks, and wallets with a global user base.

**The flow:** the user signs in with Passage via OAuth, completes KYC and eligibility, buys through the Passage purchase flow inside your app, and receives tokens to their self-custody wallet.

## What a stock is

A stock is an ownership share in a company. Owning a share entitles the holder to the economic upside of the company, to dividends where the company pays them, and to other rights such as voting. A tokenized stock is a blockchain token that represents that share, held in the user's own wallet rather than a brokerage account, and it settles like any other digital asset. Not every tokenized stock carries the same rights: some are direct ownership of the underlying share, others are wrapped exposure that tracks the price. See [Asset catalog](/assets/catalog) for the full primer.

## What a fund is

A fund represents a basket of assets managed by an asset manager. Funds can be actively managed, where the manager makes discretionary decisions, or passively managed, where the fund follows an index or a set allocation strategy. See [Asset catalog](/assets/catalog) for the full primer.

## Who issues the assets

Superstate issues tokenized US equities through Opening Bell, where the token is direct ownership of the underlying share. Ondo issues a broad catalog of tokenized stocks and funds as wrapped exposure. WisdomTree is coming soon with tokenized funds where the token is a direct fund interest held in the investor's name. The difference matters to your users, so see [Asset issuers](/assets/partners) before you pick what to surface.

## Build it

> **[Ondo Swap](/sdk/ondo-swap)**
>
> The buy and sell paths for Ondo assets.

> **[Superstate Swap](/sdk/swap-flow)**
>
> The purchase path for Superstate assets.

> **[Fetch offers](/sdk/fetch-offers)**
>
> List the offers available to your users and render them in your own UI.


# Wallet partners
Source: https://docs.passage.coinlist.co/wallet-partners

Passage ships no wallet stack. Any provider that can satisfy the EvmWallet interface can support it, provider by provider.

Passage is wallet-agnostic. The SDK ships **no wallet stack**, is not coupled to any provider, and never asks a user to connect. Wallet discovery, connection, and signing stay with your app and whatever wallet infrastructure it already uses.

That inversion is what makes a wallet partner possible. Instead of adopting someone else's wallet, you implement one small interface, [`EvmWallet`](/sdk/wallets), and the SDK drives it. Do that once and every on-chain flow works: Ondo buys and sells, Superstate swaps, token-sale approvals, and wallet ownership proofs.

The pages in this section cover providers whose customers can plug Passage in, including what their wallets are, how keys are held, and what the integration takes on each side.

## Partner profiles at a glance

| Partner | What they provide | Key model | Networks |
| - | - | - | - |
| [Para](/wallet-partners/para) | Embedded wallets created at sign-up from email, phone, social login, or a passkey | MPC. Keys are split between the user's device and Para, so neither Para nor your app holds a complete key | EVM: Ethereum and Base, mainnet and Sepolia |

> **[Para](/wallet-partners/para)**
>
> Embedded wallets, MPC keys

## What a wallet partner has to satisfy

One interface, five members. `EvmSigner` covers `address` and `signMessage`, which is enough to prove wallet ownership. `EvmWallet` adds `writeContract`, `broadcastRawTx`, and `awaitTx`, which covers everything on-chain: approvals, swaps, and allowlist transactions.

The SDK ships [viem](https://viem.sh/) types, so a provider that already exposes a viem account or wallet client is most of the way there. See [Wallets](/sdk/wallets) for the full interface, the adapter pattern, and how wallet errors are classified.

> [!NOTE]
>
> Users keep custody throughout. Passage has no ability to access, recover, freeze, or otherwise control assets in a user's wallet, whoever provides it. See [Wallets and chains](/wallets-chains).

## Become a wallet partner

If you provide wallets, embedded wallets, or wallet-as-a-service infrastructure and want your customers to reach Passage assets without leaving your stack, we can scope the integration with you.

> **[Talk to us](mailto:sales@coinlist.co)**
>
> Scope a wallet integration with the Passage team.


# Para
Source: https://docs.passage.coinlist.co/wallet-partners/para

An embedded wallet provider. Users get a self-custodial wallet at sign-up, and one adapter hook connects it to every Passage flow.

Para maintains its own [Passage integration walkthrough](https://docs.getpara.com/v3/walkthroughs/passage), with the adapter written out in full. Treat it as the source of truth for the Para side of the integration, and this page as the Passage side of it.

## What it is

Para is an embedded wallet and authentication provider, launched as Capsule and renamed to Para in 2025. Its npm packages still carry the old name in places.

Users sign up with email, phone, social login, or a passkey, and get a wallet in the process. There are no seed phrases and no browser extension, so the wallet is part of signing up for your app rather than a separate step your users have to understand first.

## Key model

MPC. Private keys are split between the user's device and Para's infrastructure, and neither Para nor your application ever holds a complete key.

That keeps the wallet self-custodial, which is what Passage flows assume: the user signs their own transactions and pays their own gas, and nothing in Passage can move funds on their behalf.

## What the integration looks like

The Para-specific work is one hook. Para exposes a viem account through `useParaViemAccount()`, and you write an adapter, called `useParaEvmWallet` in Para's walkthrough, that presents it as Passage's [`EvmWallet`](/sdk/wallets): `address`, `signMessage`, `writeContract`, `broadcastRawTx`, and `awaitTx`.

Everything after that is the same code any Passage partner writes. Offers, eligibility and requirements, KYC, wallet screening, disclosures, document signing, and the checkout flows for Ondo, Superstate, Centrifuge and CoinList token sales all run unchanged, because none of them know which wallet stack is underneath.

The adapter is also asset-agnostic. It is written against the wallet interface rather than against any particular provider's flow, so assets added to Passage later become available to your users without further Para-side work.

> [!NOTE]
>
> Because Para signs locally, there is no chain for the user to switch. The SDK passes the target chain on every transaction call (`writeContract`, `broadcastRawTx` and `awaitTx`), which is the same contract any `EvmWallet` implementation satisfies.

## Supported networks

EVM only for now: Ethereum and Base, on both mainnet and Sepolia. Para supports more chains than this, but the Passage integration is limited to the four the SDK's `EthereumChain` type covers.

Which of those a given order can actually settle on comes off the offer rather than from this list. An Ondo offer's `swapContracts`, a token sale's `fundingContracts` and a Centrifuge vault's `vaultContracts` name the chains the offer supports, and for Ondo, [`swapSpender`](/sdk/ondo-swap#which-contract-the-trader-approves) returns `null` for a chain it does not. See [Wallets and chains](/wallets-chains) for what is live today.

## What you still need from Passage

Para handles the wallet. Passage credentials are separate, and you register for your own: a `client_id`, a registered `redirect_uri`, and a `client_secret`. OAuth runs through your backend so the secret never reaches the browser.

See [Set up OAuth authentication](/sdk/oauth-authentication) for the flow, and [contact us](mailto:support@coinlist.co) if you need credentials.

## FAQ

> **Does Para hold my users' keys?**
>
> No, and neither does your app. Keys are split with MPC between the user's device and Para's infrastructure, so a complete key exists in neither place. Passage never has access to a key at all.

> **Do my users need a seed phrase or a browser extension?**
>
> No. A Para wallet is created from the sign-up method your user already chose, whether that is email, phone, social login, or a passkey.

> **How much Para-specific code is there?**
>
> One adapter hook, which Para's walkthrough gives in full. It maps Para's viem account onto the five members of `EvmWallet`. Nothing else in a Passage integration is provider-specific.

> **Do my users still have to pass KYC and eligibility?**
>
> Yes. The wallet provider does not change what an offer requires. Passage reads the requirements for the offer your user is interested in and walks them through exactly those steps. See [Requirements](/sdk/requirements).

> **Does wallet ownership still have to be proved?**
>
> Yes, and the SDK runs it. The user signs a message to prove they control the address, and for Superstate the issuer also allowlists that address on-chain before it can settle. A Para wallet satisfies both through the members the adapter already supplies: `signMessage` for the proof, and `broadcastRawTx` and `awaitTx` when the allowlisting returns a transaction for the wallet to send.

> **Who pays gas?**
>
> The user, from their own wallet, as on any Passage integration. A Para wallet needs the native token of whichever chain the order settles on. See [Wallets and chains](/wallets-chains).

> **Can I support Para alongside external wallets?**
>
> Yes. `CheckoutWalletSelection` takes your embedded wallets and one external wallet together, so Para can be the default while a user who prefers their own wallet connects it instead. Pass `externalAdapter: null` to hide the external-wallet option entirely. See [Wallets](/sdk/wallets).

## Build it

> **[Para's Passage walkthrough](https://docs.getpara.com/v3/walkthroughs/passage)**
>
> The adapter in full, step by step, from Para's own docs.

> **[Wallets](/sdk/wallets)**
>
> The `EvmWallet` seam the adapter satisfies, and how wallet errors are classified.

> **[Set up OAuth authentication](/sdk/oauth-authentication)**
>
> Register your credentials and run the flow through your backend.

> **[Building the Checkout flow](/sdk/checkout)**
>
> Hand the adapted wallet to a container that renders any offer type.


# Wallets and chains
Source: https://docs.passage.coinlist.co/wallets-chains

Users keep custody of their own keys. Support embedded wallets, external wallets, or both.

## Who controls the keys?

Your users do. Users connect their own wallet and sign their own transactions, keeping custody of their keys and funds the entire time. Passage has no ability to access, recover, freeze, or otherwise control assets in a user's wallet.

## Can I support both embedded and external wallets?

Yes. You can support embedded wallets, externally connected wallets, or both, and you configure your own signing process around whatever your product already does.

Wallet selection and connection are your app's responsibility. Once a wallet is connected, the SDK takes it from there: see [Wallets](/sdk/wallets) for the `EvmWallet` seam, proving ownership, and registering a wallet against an offer.

Using an embedded wallet provider? See [Wallet partners](/wallet-partners).

## Which chains are supported?

Superstate and Ondo assets are supported on Ethereum today, and purchases are Ethereum-only for now. Additional chains will follow as our issuing partners expand across chains.

## Who pays gas?

The user pays gas on their own transactions.

> **[Next: Asset catalog](/assets/catalog)**
>
> What is in the catalog today, and a primer on each asset class.


# What is Passage?
Source: https://docs.passage.coinlist.co/what-is-passage

The three parties in an offer, what your users experience, and who holds the money.

## The parties in an offer

Every offer on Passage involves three parties.

* **Your platform (distribution partner).** You own the user relationship and the front-end experience. Your users discover and access assets inside your app.

* **Passage.** Passage sits between you and the asset issuers, and handles authentication, KYC and eligibility, allowlists, compliance, purchase rails, and settlement.

* **Asset issuers.** Issuers create the underlying assets and set the requirements attached to each one. Some are tokenization platforms such as Superstate and Ondo; others issue directly, such as WisdomTree and CoinList.

## What the end user experiences

Sign in, qualify, invest, receive. The user authenticates through Passage via OAuth inside your app, completes eligibility checks, invests in the offer, and receives assets to a wallet they control. Users always stay inside your product.

## What you build vs. what Passage handles

| You build | Passage handles |
| - | - |
| Your app's UI and user experience | Compliance: KYC, AML screening, and identity verification |
| User discovery, marketing, and community | Jurisdiction and eligibility checks for every offering |
| Wallet connection in your product | Allowlist registration with issuers and pools |
| Post-sale communications with your users | Purchase flows, funds settlement, payments and distributions |
| | Ongoing wallet screening where an issuer requires it |
| | Disclosures, tax documents, and offer-specific reporting requirements |

## Who holds the money?

The user. Passage is not a custodian and not a broker. We never take custody of your users' funds or assets, and we have no ability to move, freeze, or recover them.

What Passage is, is a secure and audited transaction layer. We verify that a user is eligible, then coordinate the transaction between the user and the asset issuer through a funding smart contract that belongs to that specific offering.

For a tokenized stock purchase, that looks like this. The user authorizes the payment amount from their own wallet. Passage confirms they are eligible for that asset. The funds settle through the offering's funding contract to the issuer. The issuer delivers the tokens to the wallet the user controls. At no point do the funds or the assets pass through a Passage account.

The smart contracts involved in money movement have been audited by Oak Security and are publicly available at [https://github.com/coinlist/on-chain](https://github.com/coinlist/on-chain).

## Do my users need a separate account with each issuer?

Your users verify once through Passage, and that verified identity carries across issuers and offerings. In some cases, accounts may be created directly with the issuer or tokenization platform on their behalf. When this is true, all of this information is fully disclosed to the user prior to investing, and Passage handles the entire process without redirecting the user to a third-party platform.

Individual offerings may have unique requirements, a tax form for example, and when that happens Passage collects it inside the same flow rather than sending your user somewhere else.

## Do I have to build my own UI?

You control the user experience in your app, and that is the point. You know what your users like and how they want to invest, so the front end is yours to design. Passage provides the APIs and rails underneath, along with some ready-made SDK components if you want a head start. We do the heavy lifting on the back end. Hooking it up is quick.

## See it running

The partner demo is a working integration you can read and run, covering OAuth, offers, eligibility, and both purchase flows end to end.

> **[Live partner demo](https://partner.coinlist.dev/)**
>
> Open the hosted demo and click through the flows your users would see.

> **[Partner demo repo](https://github.com/coinlist/partner-demo)**
>
> Clone the source to see how each flow is wired up.

> **[Next: Eligibility and compliance](/eligibility-compliance)**
>
> Who runs KYC, how requirements vary by offering, and what licensing means for you.