API reference

Equity Grants

get/v1/equity-grants

List equity grants

equity_grants.listread tokenidempotent

The ledger's equity grants, each with what has vested and its schedule. Values are in the market's currency (USD).

Parameters

limit integer · query	Page size, 1–200.
cursor string \| null · query	The `next_cursor` of the previous page.
account_id integer \| null · query	Only grants whose shares land in this account.
X-Organization-Id string \| null · header

Returns 200 · EquityGrantList

data array of EquityGrant · required
has_more boolean · required
next_cursor string \| null · required

Example

curl -X GET "https://api.lumaledger.app/v1/equity-grants" \
  -H "Authorization: Bearer $LUMALEDGER_TOKEN"

post/v1/equity-grants

Create an equity grant

equity_grants.createwrite tokenidempotent

Record a grant and its vesting schedule. Every tranche already vested posts as wages at its vest-day close, with the withheld shares as tax; later tranches post on their dates.

Parameters

Idempotency-Key string \| null · header	Any unique string (a UUID is ideal). A retry with the same key returns the first attempt's response instead of doing the work twice. Keys are kept for 24 hours.
X-Organization-Id string \| null · header

Body · EquityGrantCreate

account_id integer · required	The investment account vested shares land in.
cliff_months integer	0–240. Default: `0`.
duration_months integer · required	1–240.
frequency_months integer · required	1–120.
grant_date date · required
grant_type string	Pattern: `^rsu$`. Default: `"rsu"`.
label string \| null
symbol string · required
total_shares string · required	Pattern: `^\d+(\.\d+)?$`.
vest_start date \| null	Omitted: the grant date.
withholding_rate string \| null	Share of each vest withheld for tax, 0–1. Omitted: 0.22. Pattern: `^(0(\.\d+)?\|1(\.0+)?)$`.

Returns 201 · EquityGrant

account_id integer · required	The investment account vested shares land in (see `accounts.list`).
account_name string · required
cliff_months integer · required
duration_months integer · required
frequency_months integer · required
grant_date date · required
grant_type string · required	`rsu`.
id integer · required
label string \| null · required
next_vest Vest \| null · required
schedule array of Vest · required
symbol string · required
total_shares string · required	Pattern: `^-?\d+(\.\d+)?$`.
unvested_shares string · required	Not the holder's yet: never part of net worth. Pattern: `^-?\d+(\.\d+)?$`.
unvested_value Money \| null · required	`unvested_shares` at the latest close.
vest_start date · required
vested_income Money · required	Wages the vested tranches paid, at their vest-day closes.
vested_shares string · required	Pattern: `^-?\d+(\.\d+)?$`.
withholding_rate string · required	Share of each vest withheld for tax, 0–1. Pattern: `^-?\d+(\.\d+)?$`.

Example

curl -X POST "https://api.lumaledger.app/v1/equity-grants" \
  -H "Authorization: Bearer $LUMALEDGER_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "account_id": 1,
    "duration_months": 48,
    "frequency_months": 3,
    "grant_date": "2026-09-01",
    "symbol": "…",
    "total_shares": "4000"
  }'

delete/v1/equity-grants/{equity_grant_id}

Delete an equity grant

equity_grants.deletewrite tokendestructiveidempotent

Remove a grant and everything its vests posted.

Parameters

equity_grant_id integer · path · required
X-Organization-Id string \| null · header

Returns 204 with no body.

Example

curl -X DELETE "https://api.lumaledger.app/v1/equity-grants/{equity_grant_id}" \
  -H "Authorization: Bearer $LUMALEDGER_TOKEN"

get/v1/equity-grants/{equity_grant_id}

Get an equity grant

equity_grants.getread tokenidempotent

One equity grant by its id.

Parameters

equity_grant_id integer · path · required
X-Organization-Id string \| null · header

Returns 200 · EquityGrant

account_id integer · required	The investment account vested shares land in (see `accounts.list`).
account_name string · required
cliff_months integer · required
duration_months integer · required
frequency_months integer · required
grant_date date · required
grant_type string · required	`rsu`.
id integer · required
label string \| null · required
next_vest Vest \| null · required
schedule array of Vest · required
symbol string · required
total_shares string · required	Pattern: `^-?\d+(\.\d+)?$`.
unvested_shares string · required	Not the holder's yet: never part of net worth. Pattern: `^-?\d+(\.\d+)?$`.
unvested_value Money \| null · required	`unvested_shares` at the latest close.
vest_start date · required
vested_income Money · required	Wages the vested tranches paid, at their vest-day closes.
vested_shares string · required	Pattern: `^-?\d+(\.\d+)?$`.
withholding_rate string · required	Share of each vest withheld for tax, 0–1. Pattern: `^-?\d+(\.\d+)?$`.

Example

curl -X GET "https://api.lumaledger.app/v1/equity-grants/{equity_grant_id}" \
  -H "Authorization: Bearer $LUMALEDGER_TOKEN"

Objects

EquityGrant

A grant, what has vested, and the schedule for the rest.

Fields

account_id integer · required	The investment account vested shares land in (see `accounts.list`).
account_name string · required
cliff_months integer · required
duration_months integer · required
frequency_months integer · required
grant_date date · required
grant_type string · required	`rsu`.
id integer · required
label string \| null · required
next_vest Vest \| null · required
schedule array of Vest · required
symbol string · required
total_shares string · required	Pattern: `^-?\d+(\.\d+)?$`.
unvested_shares string · required	Not the holder's yet: never part of net worth. Pattern: `^-?\d+(\.\d+)?$`.
unvested_value Money \| null · required	`unvested_shares` at the latest close.
vest_start date · required
vested_income Money · required	Wages the vested tranches paid, at their vest-day closes.
vested_shares string · required	Pattern: `^-?\d+(\.\d+)?$`.
withholding_rate string · required	Share of each vest withheld for tax, 0–1. Pattern: `^-?\d+(\.\d+)?$`.

EquityGrantCreate

Fields

account_id integer · required	The investment account vested shares land in.
cliff_months integer	0–240. Default: `0`.
duration_months integer · required	1–240.
frequency_months integer · required	1–120.
grant_date date · required
grant_type string	Pattern: `^rsu$`. Default: `"rsu"`.
label string \| null
symbol string · required
total_shares string · required	Pattern: `^\d+(\.\d+)?$`.
vest_start date \| null	Omitted: the grant date.
withholding_rate string \| null	Share of each vest withheld for tax, 0–1. Omitted: 0.22. Pattern: `^(0(\.\d+)?\|1(\.0+)?)$`.

EquityGrantList

A page of equity grants, by id.

Fields

data array of EquityGrant · required
has_more boolean · required
next_cursor string \| null · required

Money

An amount and its currency. `amount` is a base-10 string with two decimal places and an optional leading minus sign. Parse it with a decimal type, not a float.

Fields

amount string · required	Pattern: `^-?\d+\.\d{2}$`.
currency string · required	ISO 4217 code. Pattern: `^[A-Z]{3}$`.

UnitPrice

A price per share or per unit. Unlike `Money` it keeps the precision the institution quoted (up to 8 places): a coin or a penny stock is not priced in whole cents.

Fields

amount string · required	Pattern: `^-?\d+(\.\d+)?$`.
currency string · required	ISO 4217 code. Pattern: `^[A-Z]{3}$`.

Vest

Fields

date date · required
price UnitPrice \| null · required	The close it vested at, or today's for a tranche still ahead.
shares string · required	Pattern: `^-?\d+(\.\d+)?$`.
shares_withheld string \| null · required	Kept back to cover tax; vested tranches only. Pattern: `^-?\d+(\.\d+)?$`.
value Money \| null · required	`shares` × `price`: wages on a vested tranche, an estimate on a future one.
vested boolean · required	True once the date has passed: the shares are the holder's.