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

# Stock data

> Read a tokenized stock's market cap, ticker, exchange, earnings, shares outstanding, and dividends.

> [!WARNING]
>
> This feature is in private alpha and the details are subject to change!

`GET /v1/tokens/{address}` returns one token. When the token is linked to a stock, the response includes a `stock` object with the stock's ticker, currency, and exchange. When stock data is on for your API key, it also includes the market cap and fundamentals. Use it to show your users what the token tracks.

## Enable stock data on your API key

Stock data is off by default on an API key. Without it, the `stock` object has only `ticker`, `currency`, and `exchange`. To turn it on for your key, contact [contact@sunrise.xyz](mailto:contact@sunrise.xyz?subject=Sunrise%20API%20stock%20data).

When stock data is on, the response includes `marketCap`, `earnings`, `shares`, and `dividends`. You don't need to change your request.

## Read a stock's details

Call `GET /v1/tokens/{address}` with the token's mint address. Find stock tokens with `GET /v1/tokens?issuer=backpack_securities`.

```typescript theme={null}
// A stock token's mint, from GET /v1/tokens?issuer=backpack_securities.
const stockMint = "<stock token mint address>";

const response = await fetch(
  `https://api.sunrise.xyz/v1/tokens/${stockMint}`,
  { headers },
);

const result = await response.json();

if (!response.ok || !result.success) {
  throw new Error(result.error?.message ?? "Could not load the token");
}

const { stock } = result.data.token;
```

```json theme={null}
"stock": {
  "ticker": "HOOD",
  "currency": "USD",
  "exchange": { "marketIdentifierCode": "XNAS", "name": "Nasdaq Stock Market" },
  "earnings": [
    {
      "fiscalPeriodEndDate": "2025-12-31",
      "reportDate": "2026-02-10",
      "reportSession": "post-market",
      "eps": { "reported": 0.66, "estimated": 0.5874, "surpriseAmount": 0.0726, "surprisePercent": 12.3596 }
    },
    {
      "fiscalPeriodEndDate": "2026-03-31",
      "reportDate": "2026-04-28",
      "reportSession": "post-market",
      "eps": { "reported": 0.47, "estimated": 0.43, "surpriseAmount": 0.04, "surprisePercent": 9.3023 }
    },
    {
      "fiscalPeriodEndDate": "2026-06-30",
      "reportDate": "2026-07-29",
      "reportSession": "post-market",
      "eps": { "reported": 0.62, "estimated": 0.44, "surpriseAmount": 0.18, "surprisePercent": 40.9091 }
    },
    {
      "fiscalPeriodEndDate": "2026-09-30",
      "reportDate": "2026-10-27",
      "reportSession": "post-market",
      "eps": { "reported": 0.6, "estimated": 0.56, "surpriseAmount": 0.04, "surprisePercent": 7.1429 }
    }
  ],
  "dividends": [],
  "shares": {
    "outstanding": { "date": "2026-06-30", "basic": 913000000, "diluted": 913000000 }
  },
  "marketCap": 85017223000
}
```

This is HOOD's response on October 29, 2026. Its next report isn't scheduled yet, so all four `earnings` entries are reported quarters. When the next report is scheduled, it's added as a fifth entry with `eps.reported` set to `null`.

| Field | Contents |
| - | - |
| `marketCap` | The company's market capitalization at the previous market close. It refreshes about once a day. Missing for funds |
| `ticker` | The stock's ticker |
| `currency` | The stock's trading currency, or `null` when it isn't available |
| `exchange` | The exchange's Market Identifier Code and name, or `null` when it isn't available |
| `earnings` | Up to the four most recently reported quarters, oldest first, then the next scheduled report when one is known |
| `shares` | The latest reported shares outstanding |
| `dividends` | Dividends with an ex-dividend date in the last 12 months, including announced ones, newest first |

`stock` is `null` for a token that isn't linked to a stock. Dates are ISO 8601 dates. In `shares.outstanding`, `basic` and `diluted` can be `null` when the data isn't available.

`marketCap`, `earnings`, `shares`, and `dividends` can be missing when that data can't be loaded. Treat a missing field as "not available right now", not as an error.

## Read earnings

Each entry in `earnings` is one quarter. `fiscalPeriodEndDate` is the last day of the quarter, and `reportDate` is the day the company reports it. `reportSession` is `pre-market`, `post-market`, `during-market`, or `unknown`.

Only the last entry can have `eps.reported` set to `null`. That quarter hasn't been reported yet, so `surpriseAmount` and `surprisePercent` are `null` too. If its `reportDate` is today or earlier, the company is reporting and the results aren't in yet.

In the other entries, `eps.reported` is always a number. `eps.estimated` is the consensus estimate, or `null` when there isn't one. `surpriseAmount` is the reported EPS minus the estimate, or `null` without an estimate. `surprisePercent` is `null` without an estimate, or when the estimate is within 0.05 of zero.

## Errors

| HTTP status | `error.code` | What to do |
| - | - | - |
| 400 | `invalid_request` | The address isn't a valid Solana address, or a query parameter isn't valid. `error.details.fields` names it. |
| 403 | `forbidden` | This API key can't make this request. For example, you set an `include` parameter to `true`, but stock data isn't on for your key. Contact Sunrise about your key's access. |
| 404 | `not_found` | Sunrise doesn't list this token. |

See [Errors](https://docs.sunrise.xyz/api-reference/errors.md) for every code. For the full request and response schemas, see the [API specification](https://api.sunrise.xyz/openapi).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.