Carta

Carta holds a company's ownership: who holds shares, on what terms, and what a round did to it. /v1/captable (31 operations) is the same ledger — stakeholders, share classes, share issuances, options, SAFEs, convertibles and rounds — with GET /v1/captable/summary computing the table rather than storing it.

That last point is the design: the cap table is derived. Ownership percentages are not a column anybody writes. They fall out of the issuances, so they cannot drift from them.

Start here

A Carta export is a roster and a set of issuances; the roster loads in one call.

# 1. mint a key — sk- belongs on a server, pk- is safe in a browser
curl -sS -X POST https://api.hanzo.ai/v1/account/keys \
  -H "Authorization: Bearer $HANZO_SESSION" \
  -H 'Content-Type: application/json' \
  -d '{"type":"secret"}'

# 2. load the roster — the body is one stakeholder or an array of them
curl -sS -X POST https://api.hanzo.ai/v1/captable/stakeholders \
  -H "Authorization: Bearer $HANZO_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '[
    {"name":"A Founder","email":"[email protected]",
     "stakeholderType":"INDIVIDUAL","currentRelationship":"FOUNDER"},
    {"name":"Seed Fund I","email":"[email protected]",
     "stakeholderType":"INSTITUTION","currentRelationship":"INVESTOR"}
  ]'

# 3. read the table — computed, not stored
curl -sS https://api.hanzo.ai/v1/captable/summary \
  -H "Authorization: Bearer $HANZO_API_KEY"

Step 3 returns both holders under byStakeholder at zero: nothing has been issued yet, and a percentage is arithmetic over issuances rather than a field you loaded. Email is the identity within a company, so re-running step 2 skips the rows already there and reports how many it actually inserted — an import that died halfway resumes by running it again.

Core capabilities

Nouns

The call

Issuing shares to a stakeholder:

# the holder
SH=$(curl -sS -X POST https://api.hanzo.ai/v1/captable/stakeholders \
  -H "Authorization: Bearer $HANZO_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"name":"A Founder","email":"[email protected]"}' | jq -r .id)

# the issuance
curl -sS -X POST https://api.hanzo.ai/v1/captable/shares \
  -H "Authorization: Bearer $HANZO_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "stakeholderId": "'"$SH"'",
    "classId": "common",
    "quantity": 4000000,
    "pricePerShare": "0.0001"
  }'

Reading the table:

curl -sS https://api.hanzo.ai/v1/captable/summary \
  -H "Authorization: Bearer $HANZO_API_KEY"

Prices are decimal strings, not floats. A per-share price of 0.0001 and a position worth nine figures have to survive the same arithmetic, and binary floating point does not carry both.

What does not carry

A 409A is an appraisal, and appraisals are not a capability. The cap table itself carries over whole — that is what the 31 operations above are. What does not is Carta's valuation service: an independent firm signing an opinion on fair market value, which is what gives a 409A its safe harbour. A priced round here already carries its share class and price per share, so the number lands where you would expect; nothing produces the opinion behind it.

No electronic securities or transfer agent function. Carta is the transfer agent of record for many issuers. This is a ledger of what you tell it. Signing the documents that make an issuance real is /v1/esign; being the registered agent is not a thing this does.

No stakeholder portal. Carta gives every holder a login to see their own position. There is no per-stakeholder identity here — the org holds the table, and what a holder sees is what you build on top of the read.

No vesting engine driving notifications. A grant records its schedule. There is no scheduler emailing people as tranches vest; put that on /v1/tasks if you need it.

No scenario modelling or waterfall. Carta models exits and dilution across preference stacks. summary reports the table as it stands. Modelling what a term sheet would do to it is your spreadsheet, for now.