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

# Upcoming API changes

> Advance notice of changes to the Ondo Stocks API so you can prepare your integration before they ship.

<Note>
  This page gives advance notice of changes to the API contract before they ship, so you can update your integration ahead of time. Changes are listed here before they are generally available.
</Note>

## Market responses: `underlyingMarket` can be null, new `constituentTokens` field

We are extending the market response returned by [Get market data for an asset](/api-reference/assets/get-market-data-for-an-asset) and [Get market data for all supported assets](/api-reference/assets/get-market-data-for-all-supported-assets) to support tokens that represent several underlying assets rather than a single stock.

### What is changing

* **`constituentTokens` (new)** — an array of GM token symbols, present on every market response. For a token that represents several underlying assets, it lists the GM symbols of those assets, and you can look each one up individually via the market endpoints. For a token backed by a single stock, it is an empty array (`[]`).
* **`underlyingMarket` (updated)** — can now be `null`. For a token backed by a single stock it stays populated as it is today. For a token that represents several underlying assets there is no single underlying stock, so this field is `null`.

### Example responses

Both [Get market data for an asset](/api-reference/assets/get-market-data-for-an-asset) and [Get market data for all supported assets](/api-reference/assets/get-market-data-for-all-supported-assets) return this object — the all-assets endpoint returns an array of them. Numeric values below are illustrative.

#### Today

The current response: `underlyingMarket` is always populated and there is no `constituentTokens` field.

```json theme={null}
{
  "primaryMarket": {
    "symbol": "AAPLon",
    "price": "195.34",
    "priceChange24h": "0.123",
    "priceChangePct24h": "5.45",
    "priceHistory24h": [
      { "timestamp": 1746655938000, "price": "195.22" },
      "..."
    ],
    "totalHolders": 1234,
    "sharesMultiplier": "1",
    "tradableSessions": ["premarket", "regular", "postmarket", "overnight"]
  },
  "underlyingMarket": {
    "ticker": "AAPL",
    "name": "Apple Inc",
    "price": "195.34",
    "priceHigh52w": "259.47",
    "priceLow52w": "168.99",
    "volume": "43020691",
    "averageVolume": "38390632",
    "sharesOutstanding": "14935800000",
    "marketCap": "2934137946000"
  },
  "timestamp": 1746655938000
}
```

#### A token backed by a single stock (after the change)

Identical to today, with one addition: `constituentTokens` is present as an empty array (`[]`). `underlyingMarket` is unchanged, so integrations that ignore the new field keep working.

```json theme={null}
{
  "primaryMarket": {
    "symbol": "AAPLon",
    "price": "195.34",
    "priceChange24h": "0.123",
    "priceChangePct24h": "5.45",
    "priceHistory24h": [
      { "timestamp": 1746655938000, "price": "195.22" },
      "..."
    ],
    "totalHolders": 1234,
    "sharesMultiplier": "1",
    "tradableSessions": ["premarket", "regular", "postmarket", "overnight"]
  },
  "underlyingMarket": {
    "ticker": "AAPL",
    "name": "Apple Inc",
    "price": "195.34",
    "priceHigh52w": "259.47",
    "priceLow52w": "168.99",
    "volume": "43020691",
    "averageVolume": "38390632",
    "sharesOutstanding": "14935800000",
    "marketCap": "2934137946000"
  },
  "constituentTokens": [],
  "timestamp": 1746655938000
}
```

#### A token that represents several underlying assets (after the change)

`underlyingMarket` is `null` — there is no single backing stock — and `constituentTokens` lists the GM symbols that make up the token. Each can be looked up individually via the market endpoints.

```json theme={null}
{
  "primaryMarket": {
    "symbol": "EXMPLon",
    "price": "148.72",
    "priceChange24h": "1.94",
    "priceChangePct24h": "1.32",
    "priceHistory24h": [
      { "timestamp": 1746655938000, "price": "146.78" },
      "..."
    ],
    "totalHolders": 312,
    "sharesMultiplier": "1",
    "tradableSessions": ["premarket", "regular", "postmarket", "overnight"]
  },
  "underlyingMarket": null,
  "constituentTokens": ["AAPLon", "MSFTon", "NVDAon"],
  "timestamp": 1746655938000
}
```

### What you should do

* Treat `underlyingMarket` as optional, and handle a `null` value without erroring.
* Accept the new `constituentTokens` array. You can ignore it if you do not need it, but your parser should not reject responses that include it.

### Rollout

* `constituentTokens` appears first. For every token available today it is an empty array (`[]`), and `underlyingMarket` stays populated — so no existing value changes, you only receive an added field.
* `underlyingMarket: null` only occurs once tokens that represent several underlying assets are available. Until then, `underlyingMarket` remains populated on every response.

<Note>
  These changes are additive and backward-compatible for tokens backed by a single stock. No existing field is removed or renamed.
</Note>