Corporate Actions API

The Corporate Actions API gives your venue a machine-readable view of two things about the Convertible Entitlement Tokens (CETs) you list: every corporate action on their underlying shares (dividends, splits, mergers, tender offers and the rest, with their terms, key dates, options and settlement), and the trading status of each token (halts, suspensions, pauses and wind-downs, each with an explicit start and end). Securitize pushes every change to your webhook endpoint the moment it is published, keeps the same events for 90 days so you can read them back, and answers the current state of any token or corporate action on request.

What you work with

A corporate action is registered once per asset and published on every token stream of that asset you hold. You only ever see the tokens and chains linked to your account. See Identifiers.

Push and pull

Webhooks and the event list expose exactly the same events, with the same sourceEventId.

The whole picture

1. Get a bearer token with your client credentials. Sandbox and authentication.
2. List your tokens with GET /tokens: one per chain deployment, with its asset.
3. Receive webhooks at the endpoint you gave Securitize: verify the signature, acknowledge with a 2xx within 10 seconds (Webhooks), then apply each event as in Receive webhooks.
4. Apply each event: deduplicate on sourceEventId, keep the highest version per object, order by sequence per token. data is the whole object every time, never a delta.
5. Recover after downtime: resend the failed deliveries, or page through the event list. Replay and recover.
6. Query state when you need it: a token’s effective market status, a corporate action’s latest version. Track a corporate action, Track token status.

Sandbox lets you trigger every scenario on demand, so the whole loop is testable before any real corporate action exists. Test in sandbox.

Before you start

• An agreement with Securitize. Your Securitize contact issues your client id and secret, links the CET tokens you list to your account, registers your webhook endpoint and hands you its signing secret.
• A public HTTPS endpoint that answers 2xx within 10 seconds and can verify a signature.
• An idempotent handler. Delivery is at least once and can be out of order. Your consumer must be correct when the same event arrives twice, or a later version arrives first.

What makes this API different

• The payload is the whole object. Every event carries the full current state in data, with changedFields saying what moved. Apply it by replacing what you hold, never by accumulating.
• Nothing ends silently. A corporate action is terminal only on ca.action.completed or ca.action.cancelled. A restriction ends only with ca.restriction.removed; its expectedEnd is informational.
• Corrections keep the id. A corrected, postponed or cancelled corporate action keeps its sourceCaId and gets a new version. A re-announced one is a new corporate action linked with supersedesCaId.
• Unknown values are normal. New caType, reasonCode and event types arrive in minor versions. Treat a value you do not know as informational and keep going.
• You only see your tokens. Every list, event and stream is cut to the tokens and chains linked to your account, which is why sequence can have gaps.

Sources of truth

On-chain state is authoritative for balances, multipliers, pauses, mints and burns. This API is authoritative for corporate-action terms and for restrictions Securitize originates. Halts and suspensions of the underlying stock are a complementary signal: your obligation to stop trading alongside the listing exchange stays with you and your own market data.

Not available

No holder-level entitlements, elections or payments: holders see those through Securitize, and individual payments are read on chain. No market data. No self-service subscription management: Securitize configures your endpoint and its event filter at onboarding. Every operation, field, event and error is in the API reference in the sidebar, where you can also try each call against sandbox with a token from Get an access token.