# Carta

URL: https://docs.hanzo.ai/docs/guides/migrate/carta

> Carta keeps who owns what in a company. Here that is /v1/captable — 31 operations over stakeholders, share classes, SAFEs, options and rounds, with the summary derived rather than stored.

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.

```bash
# 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":"founder@example.com",
     "stakeholderType":"INDIVIDUAL","currentRelationship":"FOUNDER"},
    {"name":"Seed Fund I","email":"ops@seedfund.example",
     "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

| Capability     | What it does                                                                                                | Operations |
| -------------- | ----------------------------------------------------------------------------------------------------------- | ---------- |
| `/v1/captable` | Stakeholders, share classes, issuances, options, SAFEs, notes and rounds, with `summary` computed over them | 31         |
| `/v1/esign`    | Sends the documents an issuance rests on for signature, each with its own audit trail                       | 13         |
| `/v1/dataroom` | Diligence rooms: documents behind tracked links, with per-link view analytics                               | 26         |

## Nouns

| Carta                             | Hanzo                                                  |
| --------------------------------- | ------------------------------------------------------ |
| Issuer / Company                  | `GET` and `PUT /v1/captable/company`                   |
| Stakeholder                       | `/v1/captable/stakeholders`, `{id}` to amend or remove |
| Share class (Common, Preferred A) | `/v1/captable/classes`                                 |
| Certificate / share issuance      | `/v1/captable/shares`                                  |
| Transfer                          | `POST /v1/captable/shares/transfer`                    |
| Option grant                      | `/v1/captable/options`                                 |
| Option pool / equity plan         | `/v1/captable/plans`                                   |
| SAFE                              | `/v1/captable/safes`                                   |
| Convertible note                  | `/v1/captable/convertibles`                            |
| Financing round                   | `/v1/captable/rounds`, closed at `/{id}/close`         |
| Investment in a round             | `POST /v1/captable/rounds/{id}/investments`            |
| Cap table view                    | `GET /v1/captable/summary` — computed                  |
| 409A valuation                    | Nothing. See below                                     |

## The call

Issuing shares to a stakeholder:

```bash
# 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":"founder@example.com"}' | 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:

```bash
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.