Skip to main content
This guide summarizes the key design, data, and testing requirements for integrating Ondo Stocks and Ondo Intelligent Portfolios into a self-custodial wallet’s swap functionality.

​
I. Core architecture & design

​
0. Token data sourcing

All official token names, contract addresses, and metadata are available in the token registry. Token data and metadata can be sourced from CoinGecko, CoinMarketCap, Birdeye, swap routers as well as Ondo Stocks APIs.

​
1. Swap router selection

Determine which intent-based swap router you will integrate, keeping in mind each network has a specific stablecoin pair: Implementation notes
  • Ondo Stocks and Ondo Intelligent Portfolios are most efficiently traded against the supported stablecoin on each chain. Note that Ondo Intelligent Portfolio tokens are available on Ethereum and BNB Chain only.
  • Arbitrary-token swaps (e.g., ETH → AAPLon) increase swap legs and slippage due to solver routing.
  • Ensure Ondo Stocks and Ondo Intelligent Portfolios are allow-listed in the router’s token registry.
  • When calling swap endpoints, encode slippage tolerance properly — too low and the intent won’t fill.
  • Once you choose an intent-based swap router, it’s important to establish direct contact with that team and ensure your contracts are allow-listed to avoid rate limiting.

​
2. Intent-based swap prioritization

Ondo Stocks and Ondo Intelligent Portfolios swaps function most effectively when executed through intent-based routing rather than user-created DEX liquidity pools. While user-deployed DEX pools can exist permissionlessly, they are more susceptible to slippage. Therefore, you should establish a clear prioritization strategy that favors intent-based swaps over DEX pools to ensure better price execution, particularly for Ondo Stocks. Developer requirements
  • Prioritize intent-based platforms for all swaps.
  • Encode slippage into the limit price of the intent to ensure accurate on-chain execution.
  • Use dynamic quotes from Ondo Stocks’ pricing system, not static or canonical token prices.
  • Ondo Stocks provides directional (buy/sell) indicative quotes that incorporate real-world bid–ask spreads from the underlying stock markets.
  • Display quote direction clearly in your UI (e.g., “Buying AAPLon” vs. “Selling AAPLon”). Showing only the canonical token price can result in unfilled limit orders or intents.
Rationale Ondo Stocks mirrors live US equity markets, meaning that every stock token has a real and dynamic bid-ask spread. To achieve reliable execution, the intent’s encoded price and direction must match the actual quote provided by the Ondo Stocks system.

​
3. Purchaser eligibility

Integrations must enforce eligibility restrictions for potential purchasers:
  • Restrict access to eligible purchasers only. US persons, as well as persons of sanctioned countries, are ineligible. Reference the latest jurisdiction list via Ondo Stocks’ compliance notices. Ondo Intelligent Portfolios carry the same restrictions.
  • Enforce appropriate regulatory screening measures during onboarding to ensure compliance.
  • Display disclaimers for geographic restrictions to all users, and appropriately restrict ineligible purchasers.

​
4. Market hours logic

For most tokens, Ondo Stocks supports mint and redeem operations 24 hours a day, five days a week (24/5). Ondo Intelligent Portfolios are narrower: mint and redeem run only during the regular US session, 9:30:00 AM ET → 3:45:00 PM ET, and pause whenever any constituent asset is closed. Some tokens have restricted trading periods (e.g., they cannot be traded in the US overnight trading session). There are several conditions under which Ondo mint and redeem operations will be unavailable:
  • Market closure. No Ondo Stocks can be traded outside of the active trading window, which is Sunday 8:00 PM ET → Friday 7:59 PM ET.
  • Brief session transition pauses. Because the stock market has low liquidity around session transitions, we pause trading for 2-6 minutes, four times per day, as outlined in the table below.
  • Session tradability. Some tokens are not available for mint and redeem operations outside of the regular US trading session. For these tokens, mint and redeem operations are restricted by time of day.
  • Dividends and earnings. Some tokens experience temporary pauses due to earnings announcements and dividend events. These pauses are typically for 20 minutes or less.
How to check market status using the Ondo API:
  • Use our Get Market Status API to get overall market status and next market closure/pause.
  • Use our Get Asset Pauses API to view current and upcoming pauses at a per-asset level.
  • Use our Get Market Data API to view session tradability at a per-asset level.
Implementation guidance
  • Queue swaps or display a “Market Closed” state during off-hours.
  • Reference status.ondo.finance for live system availability and halts.
  • Subscribe to operational updates or join the official Telegram channel for unexpected outages or announcements.
  • Ensure your market-hours logic interacts cleanly with intent handling — off-hour intents may need to be held until markets reopen.

​
5. Token naming & display

Follow standardized token naming and display conventions. Display guidance
  • Clarify that Ondo Stocks and Ondo Intelligent Portfolios represent total-return economic exposure, not direct ownership.
  • Logos, descriptions, and contract metadata should match the canonical token registry.
  • Maintain consistent branding across chains to prevent confusion.

​
6. Corporate actions

Ondo tokenized stocks are designed to be total-return trackers of their underlying securities. This means they reflect both price movements and reinvested dividends and/or interest, giving users exposure to the economic performance of the real stock over time — not just the price appreciation. When you hold an Ondo tokenized stock, you receive similar economic exposure to what you would get if you owned the actual underlying stock and invested its dividends (net of any applicable withholding taxes) into the stock. This ensures that the tokenized asset tracks the total return of the real-world asset.
  • Dividends are reinvested, causing token prices to drift upward from the underlying share price.
    • Over time, one token will equal more than one share due to reinvested value.
  • Stock splits or reverse splits may result in short trading pauses but do not affect token economic value.
    • After a 1:10 split, the token simply represents 10 underlying shares and is priced accordingly.
  • Your wallet should not display “dividend payouts.” The yield is captured automatically in price updates.
  • Holders do not receive shareholder voting rights, statutory information rights or other shareholder rights from the issuer of those securities. Learn more.

​
II. Testing & operational readiness

​
7. End-to-end QA checklist

Additional tips
  • Run swap simulations during active and inactive market windows.
  • Validate intent expiration logic and re-quote behavior for long-lived intents.
  • Confirm that quote latency from your chosen router is acceptable (<10s recommended).
  • Consider enabling user-led order cancellations in the UX to improve flexibility and reduce support overhead.

​
III. Developer resources