> ## Documentation Index > Fetch the complete documentation index at: https://developers.securitize.io/llms.txt > Use this file to discover all available pages before exploring further. > ## Agent Instructions > SecId API: use the sandbox base URL https://partners-api.sandbox.securitize.io/investors/v1/onboarding-reliance unless the user explicitly provides production access. Authenticate with OAuth 2.0 client credentials: POST https://partners-api.sandbox.securitize.io/oauth2/token (form fields grant_type=client_credentials, client_id, client_secret, read from environment variables), cache the bearer token for its expires_in (7200 s) and send it as Authorization: Bearer on every call; never print or log the secret or the token. > Nothing is verified until POST /investors/{investorId}/verification/submit. An individual: create, upload one identity document, submit. A company: create, add its people as key parties (at least one with isBeneficialOwner: true), upload their documents, submit. > Branch on the HTTP status and the error `code`, never on `message`. A body without `code` comes from the gateway: on a 401 get a new token and send the request again; a 403 means the account is not enabled for this API. > SecId API addresses: send address.state only when that address's countryCode is US, as the 2-letter state code (NY); omit it for any other country, also when the user has a province or region. Otherwise the call answers 400 validation_error on address.state. > SecId API individuals in the US: taxId is the person's Social Security number, and it is checked against the name and residential address sent; send them as registered. A mismatch can move the investor to manual-review instead of verified. Sandbox does not run the check. > Creates are safe to repeat with the same body: after a timeout or a 502, send the identical create again. Document uploads are not: each call stores a new document, so only re-send a document after a 502. > Poll GET /investors/{investorId} about every 30 seconds, then back off; treat any status you do not recognise as not verified. In sandbox, the webhook investor.kyc.updated also announces every status change, and investor.suitability.updated / investor.dlt_test.updated every change of the suitability and DLT test verificationStatus: verify the signature, deduplicate on sourceEventId and confirm with the matching GET before acting. Token whitelisting is asynchronous too: poll GET /investors/{investorId}/wallets/whitelist until the status leaves processing. > SecId API tax forms: POST /investors/{investorId}/tax-forms takes multipart/form-data (parts file, formType, signatureDate); never base64 or JSON. Let the HTTP client set content-type with the boundary. At any point of the verification, before or after the investor is verified, only for investors you created (201), one PDF up to 10 MB per call; each upload replaces the form on file, so after a 502 send the same request again. A W-9 can instead go as JSON fields to POST /investors/{investorId}/tax-forms/w9 (TIN as 9 digits, SSN or EIN): it does not replace a form on file (409 tax_form_already_active, details.activeTaxForm), and it requires a certification object (certifiedAt, signatureName, subjectToBackupWithholding false, isUSPerson true, certificationTextVersion w9-sm-2026-10): the investor certifies in your flow on the text published at /secid-api/tax-forms#the-certification, shown without changes; subjectToBackupWithholding true answers 422 business_rule_violation (details.reason backup_withholding_not_supported). Unlike creates, a repeat after success answers 409 tax_form_already_active, not 201: when details.activeTaxForm.formType is W-9, treat it as on file. > Use synthetic test data in sandbox (@test.invalid emails, fresh ids each run). Never send more than one DLT test attempt per test investor unless the user asks: three failed attempts lock the test permanently. > The complete contract, with every field, response and error, is the OpenAPI file of the API reference; the Errors page says what to do for each code. > CET Underlying API: a WebSocket at wss://partners-rt-gw.sandbox.securitize.io/v1/market-maker/stream (TLS only; ws:// hangs with no answer). Sign hello, place_order, cancel_order and submit_crypto_funding with the user's Ed25519 key, read from an environment variable or secrets store; never print or log it. Sign timestamp + "." + type + "." + the exact payload string you send: serialise the payload once and embed that same string in the frame. > CET Underlying API: send a unique requestId of at most 32 characters (a UUID without hyphens) on every message and match replies on it; frames without a requestId are pushes. Every amount is a decimal string, never a JSON number; compare amounts as decimals. Branch on the error code, never on message. > CET Underlying API: an ack to place_order means taken, not filled. externalRef is the idempotency key; after an ack with status UNKNOWN or an UPSTREAM_UNAVAILABLE error, call get_order by externalRef before resending. Updates are delivered at most once: after any reconnect, read working orders back with get_order. Every order is placed by quantity. A buy must be a LIMIT order: quantity × limitPrice plus fees is held against your own available cash (get_cash_balance_v2), and a buy it does not cover, a MARKET buy or a notional order is refused (INVALID_ORDER). A sell must be placed by quantity, after its CETs reach the redemption wallet, or it is refused. mint_updated and burn_updated push mints and burns once they are on chain; after a gap, read them with get_mints and get_burns. The complete contract is the AsyncAPI file of the API reference. > Stocks API (Beta): documented ahead of its release through the partner gateway; paths, fields and errors can change. Base URL https://partners-api.sandbox.securitize.io/stocks/v1. Send x-api-key on every call and investorId on every call about an investor. Read the key from an environment variable; never print or log it, and never call the API from frontend code. > Stocks API: an investor can trade only once the SecId API shows them verified, with verified suitability (and a passed DLT test in the EEA), and once their wallet on the stock's chain is linked with their signature of the agreement message, signed verbatim. There is no whitelisting call: the first trade whitelists the wallet. > Stocks API: orders are fill or kill. GET /stocks/realtime-price, prepare within about 20 seconds (signedPrice), have the investor's wallet sign the returned transaction unchanged and sign-only (never send it), then submit it once with POST /stocks/execute-signed-transaction within 120 seconds. Amounts are raw base units as strings; USDC has 6 decimals. The outcome is on chain: follow transactionHash. > Stocks API: production access requires a UI audit by Securitize Compliance of the live screens: the disclosures and the market data shown, the NBBO included. > Corporate Actions API (Beta, 0.x): in development and subject to change; paths, fields, enumerations and event names can change before 1.0.0. Base URL https://partners-api.sandbox.securitize.io/corporate-actions/v1. Get a bearer token with OAuth 2.0 client credentials at POST https://partners-api.sandbox.securitize.io/oauth2/token (no scope, 2 hours), cache it, and send Authorization: Bearer on every call. Read the client id, secret and the webhook signing secret from environment variables; never print or log them, and never call the API from frontend code. > Corporate Actions API: webhooks arrive signed with the Standard Webhooks scheme under the svix-id, svix-timestamp and svix-signature headers (HMAC-SHA256 over id.timestamp.raw body, base64, v1 prefix; the secret is base64 after whsec_). Verify before parsing, reject a timestamp more than 5 minutes off, answer 2xx within 10 seconds. Delivery is at least once and can be out of order: deduplicate on sourceEventId, keep the highest version per object (objectId), order by sequence per stream.id, and replace the object with data (never merge). > Corporate Actions API: treat an unknown caType, reasonCode, eventType or enum value as informational, never as an error. A restriction ends only with ca.restriction.removed; expectedEnd is informational. marketStatus UNAVAILABLE means do not trade; the reason field carries a restriction reasonCode or a market reason such as PRE_MARKET. GET /tokens?status= filters by marketStatus (OPEN, CLOSED, UNAVAILABLE), not by the token's ACTIVE status. > Corporate Actions API: the event routes are at https://partners-api.sandbox.securitize.io/webhooks/v1 (not under /corporate-actions/v1) and cover every webhook family sent to the partner; filter with eventTypes=ca.* for corporate actions only. After an outage call POST /events/recover with since at the start of the outage (resends failed deliveries only), or page GET /events?since= (newest first, iterator paging, 90 days), then read state with GET /tokens/{tokenId}/status and GET /corporate-actions/{sourceCaId}. In sandbox, POST /sandbox/events with a scenario and one of your tokenIds publishes a scripted sequence at once; order the events by sequence, not by arrival. > Investor Activity API: base URL https://partners-api.sandbox.securitize.io/v1. Authentication is OAuth 2.0 client credentials only (no API key): POST https://partners-api.sandbox.securitize.io/oauth2/token (no scope, 2 hours), cache the token, and send Authorization: Bearer on every call. The token identifies the investor account; there is no investor id to pass. Read the client id, secret and the webhook signing secret from environment variables; never print or log them, and never call the API from frontend code. > Investor Activity API: every amount is an integer string in base units with a sibling decimals (human = amount / 10^decimals); parse with BigInt or a decimal type, never a float. Cash amounts (deposits, confirmations, payouts) are in the minor units of currencyId (1 = USD, decimals 2); token amounts (transactions, mintings, holdings) in the token's base units. Never add cash to tokens. > Investor Activity API: reconcile a subscription by grouping GET /deposits?tokenId= on tokenIssuanceId and matching the transaction in GET /transactions?tokenId= with the same tokenIssuanceId (null on a deposit means not issued yet; null on a transaction means not an issuance). Each issuance has a deposit movement (cash in) and a liquidation movement (that cash applied to the tokens) for the same amount: count the cash once, by direction=deposit, never by adding every movement. Page with offset and limit (max 100) until offset + meta.length reaches meta.total; there is no tokenIssuanceId filter. Reconcile a redemption by txHash (transfer, investor.redemption.pending, payout sourceTransaction) and by the redemption's data.id across pending, confirmed, payout.initiated and payout.completed. > Investor Activity API: webhooks arrive signed with the Standard Webhooks scheme under the svix-id, svix-timestamp and svix-signature headers (HMAC-SHA256 over id.timestamp.raw body, base64, v1 prefix; the secret is base64 after whsec_). Verify before parsing, reject a timestamp more than 5 minutes off, answer 2xx within 15 seconds. The body is {eventType, eventId, timestamp, data}: deduplicate on eventId (not svix-id), upsert by data.id, never move a record back to an earlier step, and treat an unknown eventType, processType or paymentMethod as informational. In webhooks a field with no value is absent; in endpoint answers it is null. After an outage page GET /webhook-events (newest first, iterator paging, optional eventType) back to the start of the outage. > SecId hosted onboarding: instead of the API, a partner can send an investor to https://stocks.securitize.io/partners?tokenId=&partnerUrl= (tokenAddress may replace tokenId; partnerUrl must be an absolute https URL, URL-encoded). Securitize runs identity verification, the investment profile and the wallet there. Nothing is appended to partnerUrl on return: check the wallet on chain before trading (Beta on Solana). # Get one version of a corporate action > The corporate action as it stood at `version`: the same object the event of that version carried in `data`, without the stream's `tokenId`. Versions start at 1 and never change once published. ## OpenAPI ````yaml /corporate-actions-api/openapi.yaml get /corporate-actions/{sourceCaId}/versions/{version} openapi: 3.1.0 info: title: Corporate Actions API version: 0.3.0 description: > **Beta.** The Corporate Actions API and its webhooks are in development and subject to change. Paths, fields, enumerations and event names can change before 1.0.0; every change is recorded in the changelog. Corporate actions on Securitize Convertible Entitlement Tokens (CETs) and the trading status of each token, for the venues and wallet providers that list them. Securitize pushes every change to your webhook endpoint and keeps the same events available for replay; the endpoints here return the current state of your tokens, their restrictions and every corporate action on them. Every call carries a bearer token obtained with your client credentials, and every answer is scoped to the tokens and chains linked to your account. The three event routes (replay and recover) are served at `https://partners-api.sandbox.securitize.io/webhooks/v1`, because they cover every webhook family sent to your endpoint, not only this API; the other routes are at the server below. Amounts are decimal strings. Market dates are `YYYY-MM-DD`; instants are ISO 8601 UTC. The guides on the developer portal explain the event model, webhook verification and recovery in depth. servers: - url: https://partners-api.sandbox.securitize.io/corporate-actions/v1 description: Sandbox (Beta, subject to change) security: - OAuth2: [] tags: - name: Authentication description: > Exchange your client id and secret for the bearer token every other operation takes. - name: Assets description: > A CET as one asset: one underlying share class, deployed as one token per chain. Lists and reads only ever show the deployments linked to your account. - name: Tokens description: > Your CET tokens, one per chain deployment: reference data, effective market status with the restrictions in force, and the corporate actions on each one. - name: Corporate actions description: > A corporate action by its `sourceCaId`: the latest version, or any version exactly as it was published. - name: Events description: > The webhooks sent to your endpoint in the last 90 days, read back one page at a time or one by one, and a way to resend the deliveries that failed. Served at `https://partners-api.sandbox.securitize.io/webhooks/v1`: they cover every webhook family your endpoint receives, not only this API; `eventTypes` keeps only the `ca.*` ones. - name: Webhooks description: > What Securitize POSTs to your endpoint: one event per request, the envelope as the body, signed with your endpoint's secret. Every event is also readable afterwards through the Events endpoints. - name: Sandbox description: > Sandbox only. Triggers a scripted sequence of synthetic events on one of your tokens so you can exercise your webhook handler and the replay end to end. paths: /corporate-actions/{sourceCaId}/versions/{version}: get: tags: - Corporate actions summary: Get one version of a corporate action description: > The corporate action as it stood at `version`: the same object the event of that version carried in `data`, without the stream's `tokenId`. Versions start at 1 and never change once published. operationId: getCorporateActionVersion parameters: - $ref: '#/components/parameters/SourceCaId' - name: version in: path required: true description: The version, from 1. schema: type: integer minimum: 1 example: 1 responses: '200': description: That version. content: application/json: schema: $ref: '#/components/schemas/CorporateAction' examples: preliminary: $ref: '#/components/examples/CashDividendPreliminary' '401': $ref: '#/components/responses/Unauthorized' '404': description: No such corporate action, or no such version of it. content: application/json: schema: $ref: '#/components/schemas/Error' examples: version: value: error: CA_VERSION_NOT_FOUND message: >- Corporate action 'ca_01K7Q3ZVB8M2N4P6R8T0V2X4Z6' has no version 7 statusCode: 404 action: value: error: CA_NOT_FOUND message: >- No corporate action with id 'ca_01K7Q3ZVB8M2N4P6R8T0V2X4Z6' statusCode: 404 '429': $ref: '#/components/responses/TooManyRequests' components: parameters: SourceCaId: name: sourceCaId in: path required: true description: The corporate action's id. Stable for its whole lifecycle. schema: type: string pattern: ^ca_[0-9A-HJKMNP-TV-Z]{26}$ example: ca_01K7Q3ZVB8M2N4P6R8T0V2X4Z6 schemas: CorporateAction: type: object description: >- A corporate action as the endpoints return it. The same object travels in the `data` of its events, plus the stream's `tokenId` there. required: - sourceCaId - version - assetId - caType - caCategory - status - dataCompleteness - dates - terms - options - venueActions - relatedCaIds - documents properties: sourceCaId: type: string description: >- Stable for the whole lifecycle, through corrections, postponements and cancellation. example: ca_01K7Q3ZVB8M2N4P6R8T0V2X4Z6 version: type: integer minimum: 1 description: From 1; one more on every change. assetId: type: string example: c0a8e2f4-1b3d-4e5f-8a9b-0c1d2e3f4a5b caType: type: string description: >- The kind of corporate action. Treat a value you do not know as informational. enum: - CASH_DIVIDEND - SPECIAL_DIVIDEND - RETURN_OF_CAPITAL - STOCK_SPLIT - REVERSE_SPLIT - STOCK_DIVIDEND - SPIN_OFF - MERGER - LIQUIDATION - DELISTING - NAME_OR_IDENTIFIER_CHANGE - DIVIDEND_OPTION - TENDER_OFFER - EXCHANGE_OFFER - RIGHTS_ISSUE - WARRANT_EXERCISE - APPRAISAL - MEETING - CONSENT - IST_CONVERSION caCategory: type: string enum: - MANDATORY - MANDATORY_WITH_OPTIONS - VOLUNTARY isoEventCode: type: - string - 'null' description: Indicative ISO 15022 event code. example: DVCA status: type: string enum: - ANNOUNCED - CONFIRMED - ELECTION_OPEN - ENTITLEMENTS_FIXED - SETTLING - COMPLETED - POSTPONED - CANCELLED dataCompleteness: type: string enum: - PRELIMINARY - COMPLETE description: '`PRELIMINARY`: some terms are not known yet and are `null`.' dates: $ref: '#/components/schemas/CorporateActionDates' terms: type: object description: >- Type-specific terms. Amounts are decimal strings. For cash distributions and splits every key is present, `null` when not known. additionalProperties: true example: grossAmountPerShare: '0.26' currency: USD paymentAsset: chainId: eip155:196 tokenAddress: '0x74b7f16337b8972027f6196a17a631ac6de26d22' symbol: USDC withholdingApplies: true frankingOrTaxNotes: null options: type: array description: Holder options. Empty for mandatory corporate actions. items: $ref: '#/components/schemas/CorporateActionOption' venueActions: $ref: '#/components/schemas/VenueActions' relatedCaIds: type: array description: >- Linked corporate actions, for example a merger and its appraisal option. items: type: string supersedesCaId: type: - string - 'null' description: The corporate action this one replaces. supersededByCaId: type: - string - 'null' description: The corporate action that replaced this one. correctionReason: type: - string - 'null' description: On a `ca.action.corrected` version. cancellationReason: type: - string - 'null' description: On a `ca.action.cancelled` version. description: type: - string - 'null' example: Quarterly cash dividend of USD 0.26 per share documents: type: array description: The holder notice and issuer materials. items: type: object required: - url properties: title: type: string example: Press release url: type: string format: uri settlement: oneOf: - $ref: '#/components/schemas/Settlement' - type: 'null' Error: type: object description: >- The shape of every refused request. Branch on `error`, never on `message`. required: - error - statusCode properties: error: type: string description: The error code, or the HTTP reason for a validation error. example: TOKEN_NOT_FOUND message: description: >- What went wrong, for a human. A validation error carries one message per field. oneOf: - type: string - type: array items: type: string example: No token with id '7f3b2c10-5d4e-4a6b-9c8d-1e2f3a4b5c6d' statusCode: type: integer example: 404 CorporateActionDates: type: object description: >- Every key is always present; `null` when not applicable or not known yet. Market dates are `YYYY-MM-DD` on the New York calendar; instants are ISO 8601 UTC. properties: announcementDate: type: - string - 'null' format: date example: '2026-10-20' exDate: type: - string - 'null' format: date example: '2026-11-10' recordDate: type: - string - 'null' format: date example: '2026-11-10' snapshotTime: type: - string - 'null' format: date-time description: >- The CET entitlement cut-off. CETs trade around the clock, so it is a fixed instant, 8:00 pm New York time on the business day before the ex-date or record date, and can differ from the underlying's record date. example: '2026-11-10T01:00:00.000Z' effectiveTime: type: - string - 'null' format: date-time payDate: type: - string - 'null' format: date example: '2026-11-13' electionStart: type: - string - 'null' format: date-time responseDeadline: type: - string - 'null' format: date-time description: Securitize's deadline for elections, earlier than the market's. marketExpiration: type: - string - 'null' format: date-time votingCutoff: type: - string - 'null' format: date-time meetingDate: type: - string - 'null' format: date-time CorporateActionOption: type: object description: One holder option of a corporate action with options or a voluntary one. properties: optionNumber: type: integer description: Stable within the corporate action, from 1. optionType: type: string enum: - CASH - SECURITIES - CASH_AND_SECURITIES - NO_ACTION - APPRAISAL - VOTE isDefault: type: boolean description: The option applied when a holder takes no action. electionMethod: type: string enum: - NONE - SECURITIZE_PAGE - TOKEN_TRANSFER description: >- `TOKEN_TRANSFER`: transferring CETs to a delivery address is the instruction. deliveryAddresses: type: array description: >- For `TOKEN_TRANSFER`, the addresses Securitize publishes for this option. A transfer to any other address is not an instruction. items: type: object properties: chainId: type: string example: eip155:196 address: type: string requiresLpWithdrawal: type: boolean description: CETs must be in the holder's wallet, not in a pool, to participate. responseDeadline: type: - string - 'null' format: date-time withdrawalMethod: type: string enum: - NONE - INVESTOR_SUPPORT outcome: type: object description: >- What the holder receives, for example `cashPerShare`, the resulting token and `ratio`, or `returnsUnacceptedTokens`. A resulting token is `resultingTokenId`, `resultingChainId` (CAIP-2) and `resultingContractAddress`, all `null` when there is no CET yet. The chain and address are present even when the token is not linked to your account and `GET /tokens/{tokenId}` answers `404`. additionalProperties: true example: resultingTokenId: 9e1d4c7a-2b6f-4a3e-8d5c-0f1a2b3c4d5e resultingChainId: eip155:196 resultingContractAddress: '0x2b4d6f8a0c2e4a6c8e0b2d4f6a8c0e2b4d6f8a0c' ratio: numerator: 1 denominator: 2 VenueActions: type: object description: >- What the venue needs to do, so you never infer it from the type. Keys appear when relevant. properties: tradingStop: type: object description: >- When the venue should stop trading the token. The venue still follows the underlying's halts directly. properties: required: type: boolean at: type: - string - 'null' format: date-time reasonCode: type: - string - 'null' poolMode: type: string enum: - NORMAL - REMOVALS_ONLY - CLOSE lpExitDeadline: type: - string - 'null' format: date-time description: Deadline for voluntary liquidity withdrawal before a forced one. displayToHolders: type: boolean description: Whether to surface the event in your interface. transferFlowRequired: type: boolean description: >- Holders need your transfer flow to the delivery addresses of an option. Settlement: type: object description: >- On a `COMPLETED` corporate action. Aggregate figures for the asset only; individual payments are read on chain. required: - completedAt - distributionContracts - transactions - totals properties: completedAt: type: string format: date-time distributionContracts: type: array items: type: object properties: chainId: type: string example: eip155:196 address: type: string transactions: type: array items: type: object properties: chainId: type: string example: eip155:196 txHash: type: string totals: type: array items: type: object properties: description: type: string example: Total distributed amount: type: string description: Decimal string. example: '125000.5' symbol: type: string example: USDC examples: CashDividendPreliminary: summary: Version 1, preliminary value: sourceCaId: ca_01K7Q3ZVB8M2N4P6R8T0V2X4Z6 version: 1 assetId: c0a8e2f4-1b3d-4e5f-8a9b-0c1d2e3f4a5b caType: CASH_DIVIDEND caCategory: MANDATORY isoEventCode: DVCA status: ANNOUNCED dataCompleteness: PRELIMINARY dates: announcementDate: '2026-10-20' exDate: '2026-11-10' recordDate: '2026-11-10' snapshotTime: '2026-11-10T01:00:00.000Z' effectiveTime: null payDate: '2026-11-13' electionStart: null responseDeadline: null marketExpiration: null votingCutoff: null meetingDate: null terms: grossAmountPerShare: null currency: USD paymentAsset: null withholdingApplies: true frankingOrTaxNotes: null options: [] venueActions: tradingStop: required: false poolMode: NORMAL displayToHolders: true relatedCaIds: [] supersedesCaId: null supersededByCaId: null description: Quarterly cash dividend documents: [] settlement: null responses: Unauthorized: description: > No bearer token, an expired or unknown one, or an account the API does not know. The gateway answers `{"error_description": "...", "error": "invalid_request"}` or `"invalid_token"`; the API itself answers `{"error": "UNAUTHORIZED", ...}`. Get a new token and retry. content: application/json: schema: $ref: '#/components/schemas/Error' examples: api: value: error: UNAUTHORIZED message: Missing or unknown partner identity statusCode: 401 TooManyRequests: description: >- Over the limit, 20 requests a second and 1,000 a minute per account. Wait for `Retry-After` seconds; the `RateLimit-*` headers say how much of the limit is left. securitySchemes: OAuth2: type: oauth2 description: > OAuth 2.0 client credentials. Exchange the client id and secret Securitize issued you for a bearer token at the token URL, with `grant_type=client_credentials`; the token lasts 2 hours and goes in the `Authorization: Bearer` header of every request. No scope is needed. flows: clientCredentials: tokenUrl: https://partners-api.sandbox.securitize.io/oauth2/token scopes: {} ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.