Skip to Content
DevelopmentIssue Stock

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"] } } JSON

The 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.

Response
{ "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

CheckRevert when it fails
The stakeholder exists onchainNoStakeholder
The stock class exists onchainInvalidStockClass
The issuer has enough authorized shares leftIssuer: Insufficient shares authorized
The class has enough authorized shares leftStockClass: Insufficient shares authorized
quantity and share_price are both above zeroInvalidQuantityOrPrice

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

FieldRequiredNotes
stakeholder_idYesThe stakeholder receiving the shares.
stock_class_idYesThe class being issued.
quantityYesNumber of shares, as a string.
share_priceYesamount and currency.
stock_legend_idsYesIds of stock legends. Send [] for none.
custom_idYesYour label for the issuance, such as a certificate number.
security_law_exemptionsYesExemptions the issuance relies on, as { "description", "jurisdiction" } objects. Send [] for none.
commentsNoFree-form notes, stored onchain.
issuance_typeNoRSA or FOUNDERS_STOCK.
stock_plan_id, vesting_terms_idNoIds of a stock plan or vesting terms record.
board_approval_date, stockholder_approval_dateNoYYYY-MM-DD.
consideration_textNoWhat the stakeholder paid, in words.
cost_basisNoamount and currency.
share_numbers_issuedNoOne { 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.

What’s next?

Last updated on