Skip to Content

View Cap Table

GET /cap-table/holdings/stock returns who holds stock right now. It reads positions from the contract and joins them with the stakeholder and stock class records in MongoDB. The app’s Holdings view uses the same route.

curl -s "$API/cap-table/holdings/stock?issuerId=$ISSUER_ID"
KeyContents
holdingsOne entry per stakeholder and stock class with shares: the full stakeholder and stockClass records, plus quantity, sharePrice, and timestamp.
stakeholdersEvery stakeholder in MongoDB for the issuer, including those with no shares.
stockClassesEvery stock class in MongoDB for the issuer.
issuerThe issuer record.
metaissuanceCount (issuance records in MongoDB), positions (entries in holdings), and chainSkipped, which is true when the issuer has no deployed_to.

quantity and sharePrice are human values: the route divides the contract’s ×1e10 values before responding. See Scaling.

The route returns 400 without issuerId and 404 for an unknown issuer.

How holdings are calculated

  • A stakeholder can hold several securities in one class, and each holding combines them. quantity is their total, sharePrice is the price weighted by quantity, and timestamp is when the newest of them was created, in Unix seconds.
  • Only stakeholders and stock classes in MongoDB are checked, so shares held by a stakeholder missing from MongoDB don’t appear.
  • The route reads the contract once per stakeholder and class pair, so it slows down as the cap table grows. If a read fails, that pair is left out and the server logs a warning.
  • Options, RSUs, convertibles, and other MongoDB-only records never appear here.

To see each security and its id, read history.

What’s next?

Last updated on