# Instrument

URL: /business/nouns/instrument · Id: `noun:instrument`

> An Instrument is a right to future ownership in a Company: a SAFE, a note, an option or a warrant.

An Instrument is a right to future ownership in a [Company](/business/nouns/company): a SAFE, a note, an option or a warrant.

## Properties
| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `kind` | `string` | Yes | Which right: `safe`, `note`, `option` or `warrant`. |
| `amount` | `money` | No | The amount invested, for a SAFE or a note. |
| `cap` | `money` | No | The valuation cap a SAFE or note converts at. |
| `discount` | `number` | No | The percent discount to the next priced round a SAFE or note converts at. |
| `strike` | `money` | No | The price per Share an option or warrant exercises at. |
| `quantity` | `integer` | No | The Shares an option or warrant covers. |
| `vesting` | `json` | No | The vesting schedule and cliff of an option grant. |
| `status` | `string` | Yes | Where it stands; a canceled or converted Instrument is kept, never deleted. |

## Object
```json
{
  "$id": "https://api.sb/patentpad.com/instruments/instrument_1",
  "$type": "Instrument",
  "kind": "safe",
  "amount": {
    "amount": 499,
    "currency": "USD"
  },
  "cap": {
    "amount": 499,
    "currency": "USD"
  },
  "discount": 1,
  "strike": {
    "amount": 499,
    "currency": "USD"
  },
  "quantity": 1,
  "vesting": {},
  "status": "outstanding"
}
```

## Relationships
- <a id="rel-held-by"></a>An Instrument **is held by** one [Holder](/business/nouns/holder): each Instrument belongs to one [Holder](/business/nouns/holder), who sees it, its vesting and its documents. `heldBy`, inverse [`instruments`](/business/nouns/holder#rel-instruments).
- <a id="rel-issued-by"></a>An Instrument **is issued by** one [Company](/business/nouns/company): an Instrument is a right in one [Company](/business/nouns/company) and counts in its fully diluted cap table. `issuedBy`, inverse [`instruments`](/business/nouns/company#rel-instruments).

## Lifecycle

| State | Meaning | Moves to |
| --- | --- | --- |
| `outstanding` (first) | Granted or issued and not yet turned into Shares. | `converted` by [Instrument.convert](/business/nouns/instrument/convert); `exercised` by [Instrument.exercise](/business/nouns/instrument/exercise); `canceled` by [Instrument.cancel](/business/nouns/instrument/cancel) |
| `converted` | A SAFE or note turned into Shares at a priced round. | None: it ends here. |
| `exercised` | Every Share it covers was bought at the strike price; a partial exercise keeps it outstanding. | None: it ends here. |
| `canceled` | Ended unvested, expired or forfeited, with any option Shares back in the pool. | None: it ends here. |

## Verbs
| Verb | Description | Subject | Event | Class |
| --- | --- | --- | --- | --- |
| [Instrument.cancel](/business/nouns/instrument/cancel) | Cancel ends an unvested, expired or forfeited Instrument and returns any option Shares to the pool. | [Legal Lead](/agents/legal/legal-lead) | [`Instrument.canceled`](/business/events/Instrument.canceled) | One-way: `send`, `do` |
| [Instrument.convert](/business/nouns/instrument/convert) | Convert turns a SAFE or note into Shares at a priced round, at its cap or discount, whichever gives more Shares. | [Legal Lead](/agents/legal/legal-lead) | [`Instrument.converted`](/business/events/Instrument.converted) | One-way (money): `send`, `do` |
| [Instrument.exercise](/business/nouns/instrument/exercise) | Exercise buys the Shares an option or warrant covers at its strike price, up to what has vested. | [Legal Lead](/agents/legal/legal-lead) | [`Instrument.exercised`](/business/events/Instrument.exercised) | One-way (money): `send`, `do` |
| [Instrument.grant](/business/nouns/instrument/grant) | Grant gives a Holder an option from the pool, with its strike price, vesting schedule and cliff. | [Legal Lead](/agents/legal/legal-lead) | [`Instrument.granted`](/business/events/Instrument.granted) | One-way: `send`, `do` |
| <a id="get"></a>[Instrument.get](/business/nouns/instrument/get) | Returns one Instrument by id. Inherited from [Noun](/business/nouns/noun). | None. | None. | Read: `try`, `do` |
| <a id="list"></a>[Instrument.list](/business/nouns/instrument/list) | Returns Instruments, newest first, one page at a time. Inherited from [Noun](/business/nouns/noun). | None. | None. | Read: `try`, `do` |

An Instrument is kept forever and never edited: it has no `update` or `delete`.

## Permissions
Which Access level may call each Verb. One-way Verbs wait their delay window.

| Operation | `owner` | `admin` | `member` | `viewer` |
| --- | --- | --- | --- | --- |
| `Instrument.get` | Yes | Yes | Yes | Yes |
| `Instrument.list` | Yes | Yes | Yes | Yes |
| `Instrument.cancel` | Yes | No | No | No |
| `Instrument.convert` | Yes | No | No | No |
| `Instrument.exercise` | Yes | No | No | No |
| `Instrument.grant` | Yes | No | No | No |

## Call it

**Ask**

```text
Grant the latest instrument with a holder.
```

**API**

```bash
curl -X POST https://api.sb/patentpad.com/instruments/grant \
  -H "Authorization: Bearer $STARTUP_BUILDER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"holder":"holder_1","quantity":1,"strike":{"amount":499,"currency":"USD"},"vesting":{}}'
```

```json
{
  "api": "https://api.sb/patentpad.com",
  "instrument": {
    "$id": "https://api.sb/patentpad.com/instruments/instrument_1",
    "$type": "Instrument",
    "kind": "safe",
    "status": "outstanding"
  },
  "action": {
    "$id": "https://api.sb/patentpad.com/actions/action_1",
    "operation": "Instrument.grant",
    "status": "done"
  },
  "links": {
    "self": "https://api.sb/patentpad.com/actions/action_1"
  }
}
```

**SDK**

```ts
import { $ } from 'startup-builder'

const instrument = await $.Instrument.grant({ holder: 'holder_1', quantity: 1, strike: { amount: 499, currency: 'USD' }, vesting: {} })
```

**CLI**

```bash
npx startup-builder do Instrument.grant --json '{"holder":"holder_1","quantity":1,"strike":{"amount":499,"currency":"USD"},"vesting":{}}'
```

**MCP**

```json
{
  "name": "do",
  "arguments": {
    "code": "return await $.Instrument.grant({ holder: 'holder_1', quantity: 1, strike: { amount: 499, currency: 'USD' }, vesting: {} })"
  }
}
```

## Example
A [Company](/business/nouns/company) raises $250,000 on a SAFE with an $8 million cap. At the next priced round the Instrument converts to [Shares](/business/nouns/share), and its record stays with status `converted`.