Issue Stock
With an issuer, a stock class, and a stakeholder in place, you can issue stock. Each issuance creates a new block of shares, called a security, owned by the stakeholder.
In the app
Open the company and choose Issue stock (/app/companies/<issuerId>?view=issue-stock). The app checks the request, then your wallet calls issueStock. The poller writes the issuance to MongoDB from the onchain event, including the ids the contract assigns.
With the API
POST /transactions/issuance/stock issues the stock with the server key. The server key needs OPERATOR or ADMIN on the cap table; see Server-signed routes.
curl -s -X POST "$API/transactions/issuance/stock" \
-H "Content-Type: application/json" \
-d @- <<JSON
{
"issuerId": "$ISSUER_ID",
"data": {
"stakeholder_id": "$STAKEHOLDER_ID",
"stock_class_id": "$STOCK_CLASS_ID",
"quantity": "100000",
"share_price": { "amount": "4.20", "currency": "USD" },
"stock_legend_ids": [],
"custom_id": "CS-001",
"security_law_exemptions": [],
"comments": ["Founder stock issuance"]
}
}
JSONThe request returns once the transaction confirms. The response echoes your fields plus an id, a security_id, and a date. The server fills those three in to pass OCF validation: id and security_id are random placeholders, and date is today’s UTC date. The contract assigns the real ids, which you read from history once the poller catches up.
{
"stockIssuance": {
"id": "<PLACEHOLDER_ID>",
"security_id": "<PLACEHOLDER_SECURITY_ID>",
"date": "2026-01-01",
"object_type": "TX_STOCK_ISSUANCE",
"stakeholder_id": "<STAKEHOLDER_ID>",
"stock_class_id": "<STOCK_CLASS_ID>",
"quantity": "100000",
"share_price": { "amount": "4.20", "currency": "USD" },
"stock_legend_ids": [],
"custom_id": "CS-001",
"security_law_exemptions": [],
"comments": ["Founder stock issuance"]
}
}Send human values. The contract stores quantity and share_price.amount ×1e10; the server scales them on the way in and the poller scales them back. See Scaling.
What the contract checks
| Check | Revert when it fails |
|---|---|
| The stakeholder exists onchain | NoStakeholder |
| The stock class exists onchain | InvalidStockClass |
| The issuer has enough authorized shares left | Issuer: Insufficient shares authorized |
| The class has enough authorized shares left | StockClass: Insufficient shares authorized |
quantity and share_price are both above zero | InvalidQuantityOrPrice |
The poller also needs the stakeholder in MongoDB. If the stakeholder exists onchain but not in MongoDB, the poller stops on that issuer and retries until you register the stakeholder with POST /stakeholder/register-onchain.
Fields
| Field | Required | Notes |
|---|---|---|
stakeholder_id | Yes | The stakeholder receiving the shares. |
stock_class_id | Yes | The class being issued. |
quantity | Yes | Number of shares, as a string. |
share_price | Yes | amount and currency. |
stock_legend_ids | Yes | Ids of stock legends. Send [] for none. |
custom_id | Yes | Your label for the issuance, such as a certificate number. |
security_law_exemptions | Yes | Exemptions the issuance relies on, as { "description", "jurisdiction" } objects. Send [] for none. |
comments | No | Free-form notes, stored onchain. |
issuance_type | No | RSA or FOUNDERS_STOCK. |
stock_plan_id, vesting_terms_id | No | Ids of a stock plan or vesting terms record. |
board_approval_date, stockholder_approval_date | No | YYYY-MM-DD. |
consideration_text | No | What the stakeholder paid, in words. |
cost_basis | No | amount and currency. |
share_numbers_issued | No | One { starting_share_number, ending_share_number } range. More than one returns 400. |
vestings passes validation but isn’t stored, because the contract has no field for it.