API reference

Every endpoint in API version 0.1.0, generated from the published OpenAPI 3.1 document at /v1/openapi.json.

All endpoints except /v1/health and /v1/openapi.json need an API key with the listed scope. Fields marked * are required. The same schemas generate server validation and the TypeScript client.

Service

Service and database health

GET/v1/healthNo key required

Response field (200)	Type	Description
`ok`	`true`
`dataset`	`object`

Responses: 200

curl -s "https://api.corpact.example/v1/health"

Assets

Supported mints and their verification status

GET/v1/assetsScope: assets:read

Response field (200)	Type	Description
`assets`	`object[]`

Responses: 200, 400, 401, 403, 404, 429

curl -s "https://api.corpact.example/v1/assets" \
  -H "authorization: Bearer $CORPACT_API_KEY"

Wallets

Register a wallet to the caller's tenant and request an idempotent historical sync

POST/v1/wallets/syncScope: wallets:sync

Body field	Type	Description
`owner` *	`string`	Solana wallet address (base58)

Response field (202)	Type	Description
`owner`	`string`
`registration`	`"registered" \| "already_registered"`	Whether this request added the wallet to the caller's tenant
`status`	`"queued" \| "running"`
`job`	`"enqueued" \| "already_pending"`

Responses: 202, 400, 401, 403, 404, 429

curl -s -X POST "https://api.corpact.example/v1/wallets/sync" \
  -H "authorization: Bearer $CORPACT_API_KEY" \
  -H 'content-type: application/json' \
  -d '{"owner":"<wallet address>"}'

Wallets registered to the caller's tenant

GET/v1/walletsScope: ledger:read

Response field (200)	Type	Description
`tenant`	`string`
`maxWallets`	`integer`
`wallets`	`object[]`

Responses: 200, 400, 401, 403, 404, 429

curl -s "https://api.corpact.example/v1/wallets" \
  -H "authorization: Bearer $CORPACT_API_KEY"

Progress and result of the latest sync

GET/v1/wallets/{owner}/statusScope: ledger:read

Parameter	In	Type	Description
`owner` *	path	`string`	Solana wallet address (base58)

Response field (200)	Type	Description
`sync`	`object \| null`

Responses: 200, 400, 401, 403, 404, 429

curl -s "https://api.corpact.example/v1/wallets/<owner>/status" \
  -H "authorization: Bearer $CORPACT_API_KEY"

Ledger

Positions, dividend income, convertible exposure and coverage for a wallet

GET/v1/portfolioScope: ledger:read

Parameter	In	Type	Description
`owner` *	query	`string`	Solana wallet address (base58)

Response field (200)	Type	Description
`owner`	`string`
`dataset`	`object`
`asOfSlot`	`string \| null`
`asOfTime`	`string \| null`
`dataStatus`	`object \| null`
`valuationStatus`	`string`
`coverage`	`object`
`totals`	`object`
`positions`	`object[]`

Responses: 200, 400, 401, 403, 404, 429

curl -s "https://api.corpact.example/v1/portfolio?owner=<owner>" \
  -H "authorization: Bearer $CORPACT_API_KEY"

Dividend, split and unclassified entries, newest first

GET/v1/incomeScope: ledger:read

Parameter	In	Type	Description
`owner` *	query	`string`	Solana wallet address (base58)
`limit`	query	`integer`	Default 50. Range 1–200.
`offset`	query	`integer`	Default 0. Range 0–….

Response field (200)	Type	Description
`owner`	`string`
`dataset`	`object`
`entries`	`object[]`
`nextOffset`	`integer \| null`

Responses: 200, 400, 401, 403, 404, 429

curl -s "https://api.corpact.example/v1/income?owner=<owner>" \
  -H "authorization: Bearer $CORPACT_API_KEY"

One entry with its chain, classification and issuer evidence

GET/v1/income/{id}Scope: ledger:read

Parameter	In	Type	Description
`owner` *	query	`string`	Solana wallet address (base58)
`id` *	path	`string`

Response field (200)	Type	Description
`id`	`string`
`owner`	`string`
`mint`	`string`
`kind`	`"dividend" \| "split" \| "unclassified_adjustment"`
`quantity`	`string`
`quantityDisplay`	`string`
`symbol`	`string`
`usd`	`string \| null`
`valuation`	`"issuer_net_cash" \| "market_estimate" \| null`
`warnings`	`string[]`
`reasons`	`string[]`
`headline`	`string`
`effectiveAt`	`string`
`revision`	`integer`	Range 1–….
`correctedAt`	`string \| null`
`history`	`object[]`	Every recognition and reversal of this entry, oldest first
`evidence`	`object`

Responses: 200, 400, 401, 403, 404, 429

curl -s "https://api.corpact.example/v1/income/<id>?owner=<owner>" \
  -H "authorization: Bearer $CORPACT_API_KEY"

Income and share yield per window, and trailing net distribution per share, with coverage

GET/v1/yieldScope: ledger:read

Parameter	In	Type	Description
`owner` *	query	`string`	Solana wallet address (base58)

Response field (200)	Type	Description
`owner`	`string`
`dataset`	`object`
`definitions`	`object`
`positions`	`object[]`

Responses: 200, 400, 401, 403, 404, 429

curl -s "https://api.corpact.example/v1/yield?owner=<owner>" \
  -H "authorization: Bearer $CORPACT_API_KEY"

CSV export: the append-only journal (default) or current income entries, with confidence fields

GET/v1/exportScope: ledger:read

Parameter	In	Type	Description
`owner` *	query	`string`	Solana wallet address (base58)
`dataset`	query	`"journal" \| "income"`	Default "journal".

Responses: 200, 400, 401, 403, 404, 422, 429

curl -s "https://api.corpact.example/v1/export?owner=<owner>" \
  -H "authorization: Bearer $CORPACT_API_KEY"

Append-only audit trail: every recognition and reversal of income, newest first

GET/v1/journalScope: ledger:read

Parameter	In	Type	Description
`owner` *	query	`string`	Solana wallet address (base58)
`limit`	query	`integer`	Default 50. Range 1–200.
`offset`	query	`integer`	Default 0. Range 0–….

Response field (200)	Type	Description
`owner`	`string`
`dataset`	`object`
`entries`	`object[]`
`nextOffset`	`integer \| null`

Responses: 200, 400, 401, 403, 404, 429

curl -s "https://api.corpact.example/v1/journal?owner=<owner>" \
  -H "authorization: Bearer $CORPACT_API_KEY"

Operations

Monitoring checks with thresholds (PLAN §14)

GET/v1/ops/statusScope: ops:read

Response field (200)	Type	Description
`status`	`"ok" \| "warn" \| "critical"`
`checkedAt`	`string`
`checks`	`object[]`

Responses: 200, 400, 401, 403, 404, 429

curl -s "https://api.corpact.example/v1/ops/status" \
  -H "authorization: Bearer $CORPACT_API_KEY"

Prometheus metrics (scrape with the key as a bearer token)

GET/v1/ops/metricsScope: ops:read

Responses: 200, 400, 401, 403, 404, 429

curl -s "https://api.corpact.example/v1/ops/metrics" \
  -H "authorization: Bearer $CORPACT_API_KEY"

actions

Every corporate-action type, its ledger treatment, real-instance count and validation status

GET/v2/taxonomyScope: ledger:read

Response field (200)	Type	Description
`kinds`	`object[]`

Responses: 200, 400, 401, 403, 404, 429

curl -s "https://api.corpact.example/v2/taxonomy" \
  -H "authorization: Bearer $CORPACT_API_KEY"

Corporate actions applied to a wallet, newest first: type, treatment, lifecycle state, evidence and validation status

GET/v2/actionsScope: ledger:read

Parameter	In	Type	Description
`owner` *	query	`string`	Solana wallet address (base58)
`limit`	query	`integer`	Default 50. Range 1–200.
`offset`	query	`integer`	Default 0. Range 0–….

Response field (200)	Type	Description
`owner`	`string`
`dataset`	`object`
`actions`	`object[]`
`nextOffset`	`integer \| null`

Responses: 200, 400, 401, 403, 404, 429

curl -s "https://api.corpact.example/v2/actions?owner=<owner>" \
  -H "authorization: Bearer $CORPACT_API_KEY"

One corporate action with its full lifecycle, distinct timestamps, every issuer revision, chain evidence, journal history and lineage

GET/v2/actions/{id}Scope: ledger:read

Parameter	In	Type	Description
`owner` *	query	`string`	Solana wallet address (base58)
`id` *	path	`string`

Response field (200)	Type	Description
`id`	`string`
`mint`	`string`
`symbol`	`string`
`effectiveAt`	`string`
`type`	`"cash_dividend" \| "withholding_adjustment" \| "stock_dividend" \| "cash_and_stock_dividend" \| "forward_split" \| "reverse_split" \| "unit_split" \| "cash_in_lieu" \| "spin_off" \| "rights_distribution" \| "stock_merger" \| "cash_merger" \| "mixed_merger" \| "identity_change" \| "redemption" \| "delisting" \| "seizure" \| "unknown"`
`treatment`	`"income" \| "quantity_basis" \| "basis_allocation" \| "identity" \| "not_booked"`	income: units added are income. quantity_basis: units rescaled, basis spread across them. basis_allocation: units added are principal bought with distributed value. identity: same position in a new underlying form. not_booked: recognised, not booked; conversion disabled
`validation`	`object`
`lifecycle`	`object`
`quantity`	`string`	Units added (negative: removed). Zero for an ordinary split
`quantityDisplay`	`string`
`factor`	`string \| null`	New units per old unit, for splits, stock dividends and identity changes
`distributedFraction`	`string \| null`	Share of the position's value delivered by a spin-off or rights distribution: (M_new − M_old) ÷ M_new
`usd`	`string \| null`	Income value; only for income. Null means unknown, never zero
`proceedsUsd`	`string \| null`	Issuer proceeds for a distribution, when published and plausible. Never income
`valuation`	`"issuer_net_cash" \| "market_estimate" \| null`
`retentionRate`	`string \| null`	A currency retention the issuer published in its withholding field; not tax, already reflected in net cash
`refundNote`	`string \| null`	For a withholding refund: the issuer's explanation
`underlying`	`object \| null`
`headline`	`string`
`warnings`	`string[]`
`reasons`	`string[]`
`revision`	`integer`	Range 1–….
`correctedAt`	`string \| null`
`evidence`	`object`
`owner`	`string`
`dataset`	`object`
`timestamps`	`object`
`history`	`object[]`	Every recognition and reversal of this action, oldest first
`lineage`	`object \| null`	The lineage link this action wrote, for identity changes

Responses: 200, 400, 401, 403, 404, 429

curl -s "https://api.corpact.example/v2/actions/<id>?owner=<owner>" \
  -H "authorization: Bearer $CORPACT_API_KEY"

A mint's recorded identities, the lineage links between them, and where the basis of its earliest identity is now

GET/v2/instruments/{mint}/lineageScope: ledger:read

Parameter	In	Type	Description
`mint` *	path	`string`	Token mint address (base58)

Response field (200)	Type	Description
`mint`	`string`
`dataset`	`object`
`identities`	`object[]`
`links`	`object[]`	Append-only; a corrected link names the link it supersedes
`current`	`object[]`	Where the basis of the earliest recorded identity is now, traced through every link that is not superseded. Empty when no identity change is recorded

Responses: 200, 400, 401, 403, 404, 429

curl -s "https://api.corpact.example/v2/instruments/<mint>/lineage" \
  -H "authorization: Bearer $CORPACT_API_KEY"

#Service

#Service and database health

#Assets

#Supported mints and their verification status

#Wallets

#Register a wallet to the caller's tenant and request an idempotent historical sync

#Wallets registered to the caller's tenant

#Progress and result of the latest sync

#Ledger

#Positions, dividend income, convertible exposure and coverage for a wallet

#Dividend, split and unclassified entries, newest first

#One entry with its chain, classification and issuer evidence

#Income and share yield per window, and trailing net distribution per share, with coverage

#CSV export: the append-only journal (default) or current income entries, with confidence fields

#Append-only audit trail: every recognition and reversal of income, newest first

#Operations

#Monitoring checks with thresholds (PLAN §14)

#Prometheus metrics (scrape with the key as a bearer token)

#actions

#Every corporate-action type, its ledger treatment, real-instance count and validation status

#Corporate actions applied to a wallet, newest first: type, treatment, lifecycle state, evidence and validation status

#One corporate action with its full lifecycle, distinct timestamps, every issuer revision, chain evidence, journal history and lineage

#A mint's recorded identities, the lineage links between them, and where the basis of its earliest identity is now

Service

Service and database health

Assets

Supported mints and their verification status

Wallets

Register a wallet to the caller's tenant and request an idempotent historical sync

Wallets registered to the caller's tenant

Progress and result of the latest sync

Ledger

Positions, dividend income, convertible exposure and coverage for a wallet

Dividend, split and unclassified entries, newest first

One entry with its chain, classification and issuer evidence

Income and share yield per window, and trailing net distribution per share, with coverage

CSV export: the append-only journal (default) or current income entries, with confidence fields

Append-only audit trail: every recognition and reversal of income, newest first

Operations

Monitoring checks with thresholds (PLAN §14)

Prometheus metrics (scrape with the key as a bearer token)

actions

Every corporate-action type, its ledger treatment, real-instance count and validation status

Corporate actions applied to a wallet, newest first: type, treatment, lifecycle state, evidence and validation status

One corporate action with its full lifecycle, distinct timestamps, every issuer revision, chain evidence, journal history and lineage

A mint's recorded identities, the lineage links between them, and where the basis of its earliest identity is now