Cookbook
Execute a stock sale
End-to-end stock sale. Stock purchase agreement, stockholder consent, share-ledger transfers on close.
Last updated
Stock purchase agreement, drag-along enforcement, transfer-agent reconciliation, post-closing cap table.
Trigger
Stockholders are selling their shares; the entity is unchanged but ownership flips.
Call sequence
1. Initiate (kind=stock_sale)
POST /v1/corporate_transactions { kind: 'stock_sale' }2. Generate SPA
POST /v1/documents { template: 'tpl_spa_v3' }3. Enforce drag-along
POST /v1/approvals { kind: 'drag_along', actions: [...] }4. Reconcile transfer agent
POST /v1/transfer_agents/{id}/reconcileIdempotency
Transaction idempotent on `(entity, kind, sellers.sort())`.
Webhooks
| Event | Description |
|---|---|
corporate_transaction.signed | SPA executed. |
cap_table.restated | Ownership flipped. |
Errors
| Status | Code | Description |
|---|---|---|
422 | drag_threshold_unmet | Drag-along threshold not satisfied. |
When to reach for it
Use this recipe when specific stockholders sell their shares to a buyer:
- Secondary transactions / partial-exit liquidity for early holders.
- Controlling-stake buyout short of a full acquisition.
- Tender-offer-style cleanups where multiple holders sell concurrently.
For a corporate-level acquisition where the target keeps its existence, prefer acquire-a-company. For asset-only transfers where no shares change hands, use execute-an-asset-sale.
Cascade outcome
A CorporateTransaction (ctx_…) walked end-to-end. On close:
- Each selling stakeholder's
ShareLedgerEntryrows for the in-scope class are rewritten askind: transferwith the buyer as the new holder. - If
controlling_stake: true(and the sale crosses a 50% threshold) →Entity.statetransitionsactive → acquired. - Otherwise the entity stays
activeand only the cap table changes. - Document pack: stock purchase agreement, stockholder consent per selling party, stock-power assignments, optional Rule 144 letter for restricted shares.
Error recovery
| Failure | Cause | Remediation |
|---|---|---|
409 share_balance_insufficient | A listed seller doesn't hold enough shares of share_class_id. | Read the cap table; remove or correct the offending stakeholder; retry with the same Idempotency-Key. |
422 mixed_share_classes_unsupported | Sellers hold different classes; the workflow expects a single class per call. | Run one execute_stock_sale per class. |
409 controlling_stake_threshold_not_crossed | controlling_stake: true but the math doesn't cross the 50% line. | Set controlling_stake: false or include additional sellers. |
403 share_ledger.transfer_required | Token policy missing share_ledger.transfer. | Mint a token with the scopes above. |
409 invalid_stage_transition | Tried to advance out of order. | Read corporate_transaction.stage; advance one stage at a time. |
Full taxonomy: errors.
Related
POST /v1/corporate_transactions— the underlying primitive.- Cap table — how share ledger transfers render.
- Exit phase — controlling-stake threshold details.
- Execute an asset sale — for asset-only deals.
- Acquire a company — for entity-level acquisitions where the target survives.