Corporate Actions

Corporate actions are events that affect an asset's price or identity, including dividends, splits, ticker changes and delistings. The Pyth Intelligence API provides corporate action records for the assets behind Pyth price feeds.

Each feed references an asset through base_asset. The /assets/{id}/corporate_actions endpoint returns the events that belong to that asset.

Configure requestsCopy Anchor Link

Send the Pyth-Version header on every request. The current version is 2026-09-29. Each request also requires an API key as a bearer credential. In a browser, use an access token from POST /auth/token instead.

BASE=https://pyth.dourolabs.app/v3/intelligence

curl -H "Authorization: Bearer $TOKEN" \
     -H "Pyth-Version: 2026-09-29" \
     "$BASE/feeds/922?expand=base_asset"

The header pins the response structure. A request without it receives the server's default version, which can change on a release, so set the header in the client's shared request configuration. An unsupported version returns 400 with code version_unsupported, and the message lists the supported versions.

Retrieve a feed's corporate actionsCopy Anchor Link

Start from the feed, then read the events for its base_asset.

1. Find the asset behind the feedCopy Anchor Link

Request GET /feeds/922?expand=base_asset using the command above. The feed path accepts a numeric Lazer feed ID, the feed's id or a spine such as equity.aapl.usd.57sc.

With expand=base_asset, the response includes the asset inline. The following excerpt shows the asset ID and spine for the next request:

{
  "type": "feed",
  "id": "feed-01m14btkssejctyrzpnxzga945",
  "pyth_lazer_id": 922,
  "spine": "equity.aapl.usd.57sc",
  "symbol": "Equity.US.AAPL/USD",
  "base_asset": {
    "type": "asset",
    "id": "asset-01m0a6sd8me54bsx692f90ws91",
    "slug": "equity.aapl",
    "spine": "equity.aapl.1ccs",
    "ticker": "AAPL",
    "full_name": "APPLE INC",
    "class": "equity",
    "status": "active"
  }
}

Without expand, base_asset contains only the asset ID. A feed without a linked asset, such as Crypto.BTC/USD, has no base_asset.

The symbol filter resolves a Lazer symbol to its feed:

curl -G -H "Authorization: Bearer $TOKEN" \
     -H "Pyth-Version: 2026-09-29" \
     "$BASE/feeds" \
     --data-urlencode "symbol=Equity.US.AAPL/USD"

This returns a list containing the matching feed.

2. Request the asset's eventsCopy Anchor Link

Pass the base_asset ID to the asset's corporate actions endpoint:

curl -H "Authorization: Bearer $TOKEN" \
     -H "Pyth-Version: 2026-09-29" \
     "$BASE/assets/asset-01m0a6sd8me54bsx692f90ws91/corporate_actions?limit=2"

The endpoint also accepts an asset spine. A request to /assets/equity.aapl.1ccs/corporate_actions retrieves Apple's events without a feed lookup.

The API returns events newest first:

{
  "type": "list",
  "data": [
    {
      "type": "corporate_action",
      "id": "ca-01m14cxqtkenq8n0qvdc3rxx2m",
      "event_type": "cash_dividend",
      "ex_date": "2026-08-10",
      "record_date": "2026-08-10",
      "pay_date": "2026-08-13",
      "declaration_date": "2026-07-30",
      "gross_amount": "0.270000",
      "status": "applied",
      "applies_to": "asset-01m0a6sd8me54bsx692f90ws91",
      "paid_in": "asset-01m14btkhresy9fe9afcf95sht",
      "meta": { "recorded_at": "2026-08-28T14:39:01.654Z" }
    },
    {
      "type": "corporate_action",
      "id": "ca-01m14cxqv2er7v6ggstgbva6n3",
      "event_type": "cash_dividend",
      "ex_date": "2026-05-11",
      "record_date": "2026-05-11",
      "pay_date": "2026-05-14",
      "declaration_date": "2026-04-30",
      "gross_amount": "0.270000",
      "status": "applied",
      "applies_to": "asset-01m0a6sd8me54bsx692f90ws91",
      "paid_in": "asset-01m14btkhresy9fe9afcf95sht",
      "meta": { "recorded_at": "2026-08-28T14:39:01.654Z" }
    }
  ],
  "continues": true,
  "next": "MjAyNi0wNS0xMXxjYS0wMW0xNGN4cXYyZXI3djZnZ3N0Z2J2YTZuMw",
  "meta": { "recorded_at": "2026-10-05T13:47:11.817Z" }
}

To retrieve one event directly, request /corporate_actions/{id}.

3. Resolve asset referencesCopy Anchor Link

Each event's applies_to identifies the asset it affects. A dividend's paid_in identifies its currency asset.

Add expand=paid_in to inline the currency, or fetch it separately with GET /assets/{id}. The expand=applies_to parameter inlines the affected asset.

In the response above, paid_in refers to the US dollar asset, whose spine is fx.usd.6w8c. Currencies use the same asset model as equities, with class: "fx".

Filter and paginate eventsCopy Anchor Link

Both /corporate_actions and /assets/{id}/corporate_actions support the same event and date filters. The first searches across assets. The second limits results to one asset.

Event types and statuses are case-insensitive. Unknown filter values return 400.

For dates, a bare YYYY-MM-DD selects that day. Prefix a date with gte:, gt:, lte:, lt: or eq: to set a bound. Filters combine, so this request selects splits with an ex-date in November or December 2025:

curl -G -H "Authorization: Bearer $TOKEN" \
     -H "Pyth-Version: 2026-09-29" \
     "$BASE/corporate_actions" \
     --data-urlencode "event_type=split" \
     --data-urlencode "ex_date=gte:2025-11-01,lt:2026-01-01"

The filter status=confirmed,announced selects events with either status.

List responses contain type, data, continues, next and meta. When continues is true, pass the next value unchanged as the after query parameter to fetch the following page. Repeat the original filters, limit, expand and effective on every page request. Do not parse or construct cursors.

The default limit is 50 and the maximum is 100. The API sorts corporate actions newest first by ex_date, or by effective_date when there is no ex-date.

Read historical stateCopy Anchor Link

Every read accepts effective, an RFC 3339 instant. The response is the state at that moment, from what the API knows today. Omit effective to get the current state.

curl -G -H "Authorization: Bearer $TOKEN" \
     -H "Pyth-Version: 2026-09-29" \
     "$BASE/assets/equity.aapl.1ccs/corporate_actions" \
     --data-urlencode "effective=2026-06-01T00:00:00Z"

This lists Apple's events as of June 1, 2026. The newest event is the dividend with ex-date 2026-05-11. The list's meta.effective_at echoes the requested instant.

URL-encode timestamps that contain a + offset. The command above uses --data-urlencode to encode the parameter.

Interpret assets and eventsCopy Anchor Link

Asset records identify the instruments behind price feeds. Corporate action records describe the events that affect those instruments.

Asset identifiersCopy Anchor Link

An asset's id and spine are stable identifiers suitable for persistent keys. A spine provides a readable handle that works wherever an ID does. The API never reuses spines. The slug, such as equity.aapl, can change.

Assets also carry descriptive fields such as ticker and full_name, a class such as equity or fx, and a status such as active, delisted, merged or retired. The identifiers array holds external identifiers, such as a Nasdaq symbol. visibility describes access to the asset. Responses contain only assets visible to the authenticated caller.

meta.recorded_at indicates when the API recorded the data in the response.

Event fieldsCopy Anchor Link

Each corporate action represents one event for an asset. The API omits fields that do not apply or have no known value.

Amounts and ratios are decimal strings, such as "0.270000" or "10.0000000000". Parse them with a decimal type rather than a floating-point type.

Cash dividendsCopy Anchor Link

The reference dividend amount is gross_amount. Some dividends, mostly on ADRs, also include net_amount. A dividend without gross_amount has net_amount as its only amount. Published net amounts can reflect fees as well as withholding tax.

The API includes a dividend once its issuer publishes an amount. The API does not return payment dates alone when an issuer announces them before the amount. Each dividend therefore has an amount and a paid_in currency. Most also have a declaration_date.

If an issuer cancels a published dividend, the API retains its record with status: "cancelled".

Splits and reverse splitsCopy Anchor Link

split_from old shares become split_to new shares. The following excerpt shows the fields for Netflix's 2025 ten-for-one split:

{
  "event_type": "split",
  "ex_date": "2025-11-17",
  "record_date": "2025-11-10",
  "pay_date": "2025-11-14",
  "split_from": "1.0000000000",
  "split_to": "10.0000000000",
  "status": "applied"
}

To compare prices before and after the ex-date, divide the earlier prices by split_to / split_from. For this split, divide by 10.

A reverse_split uses the same fields. A one-for-eight reverse split has split_from: "8.0000000000" and split_to: "1.0000000000".

Ticker changes and delistingsCopy Anchor Link

A ticker_change includes effective_date, previous_ticker and new_ticker. A delisting includes effective_date. These identity events have no ex-date.

Handle errors and schema changesCopy Anchor Link

Errors use a consistent response structure:

{
  "error": {
    "category": "auth",
    "code": "credential_missing",
    "message": "authentication required: pass a Pyth Lazer access token as a bearer credential (`Authorization: Bearer <token>`)"
  }
}

Branch on code. Error messages may change.

Generate client types from the versioned OpenAPI spec:

curl -H "Authorization: Bearer $TOKEN" \
     -H "Pyth-Version: 2026-09-29" \
     "$BASE/openapi/2026-09-29.json"

The spec requires the same authentication as the data endpoints and defines their paths, parameters and response schemas.

Enumerations such as class, status and event_type include unknown and can gain values. Treat an unrecognized value as unknown.

Coverage in October 2026Copy Anchor Link

Pyth sources corporate actions from EDI and updates them daily. Coverage includes the assets behind Pyth Lazer's US equity and ETF feeds, about 100 securities, with history from September 2025 onward. All dividends in the covered history specify US dollars as their payment currency.