Instrument methods: cancel, convert, exercise
The Instrument Verbs cancel, convert, exercise as typed SDK methods, with inputs, result, refusals and an example.
Reference for Instrument, one group of Instrument methods.
Instrument.cancel
Cancel ends an unvested, expired or forfeited Instrument and returns any option Shares to the pool. Verb page.
interface InstrumentVerbs {
cancel(input: InstrumentCancelInput, options?: SB.CallOptions): SB.Call<Instrument>
}Emits Instrument.canceled.
Inputs
| Input | Type | Required | Description |
|---|---|---|---|
instrument | Instrument | required | The Instrument to end. |
reason | string | required | Why it ends: unvested, expired or forfeited. |
Returns
| Output | Type | Required | Description |
|---|---|---|---|
instrument | Instrument | required | The canceled Instrument, kept with its history. |
Refuses when
| Check | Error | Fix | Then call |
|---|---|---|---|
| The key is valid, but its scopes do not allow this operation. | forbidden | Use a key whose scopes cover the operation, or ask an owner of the namespace to grant them. | None. |
Example
import { $ } from 'startup-builder'
const instrument = await $.Instrument.cancel({ instrument: 'instrument_yZz4i2meOW', reason: 'unvested' })Instrument.convert
Convert turns a SAFE or note into Shares at a priced round, at its cap or discount, whichever gives more Shares. Verb page.
interface InstrumentVerbs {
convert(input: InstrumentConvertInput, options?: SB.CallOptions): SB.Call<InstrumentConvertOutput>
}Emits Instrument.converted.
Inputs
| Input | Type | Required | Description |
|---|---|---|---|
instrument | Instrument | required | The SAFE or note. |
roundPrice | money | required | The price per Share of the priced round. |
Returns
| Output | Type | Required | Description |
|---|---|---|---|
shares | list of Share | required | The Shares issued on conversion. |
instrument | Instrument | required | The Instrument, now converted. |
Refuses when
| Check | Error | Fix | Then call |
|---|---|---|---|
| The key is valid, but its scopes do not allow this operation. | forbidden | Use a key whose scopes cover the operation, or ask an owner of the namespace to grant them. | None. |
Example
import { $ } from 'startup-builder'
const { shares, instrument } = await $.Instrument.convert({ instrument: 'instrument_yZz4i2meOW', roundPrice: { amount: 29, currency: 'USD' } })Instrument.exercise
Exercise buys the Shares an option or warrant covers at its strike price, up to what has vested. Verb page.
interface InstrumentVerbs {
exercise(input: InstrumentExerciseInput, options?: SB.CallOptions): SB.Call<InstrumentExerciseOutput>
}Emits Instrument.exercised.
Inputs
| Input | Type | Required | Description |
|---|---|---|---|
instrument | Instrument | required | The option or warrant. |
quantity | integer | required | How many Shares to buy. |
Returns
| Output | Type | Required | Description |
|---|---|---|---|
share | Share | required | The Shares bought. |
instrument | Instrument | required | The Instrument, now exercised. |
Refuses when
| Check | Error | Fix | Then call |
|---|---|---|---|
| The key is valid, but its scopes do not allow this operation. | forbidden | Use a key whose scopes cover the operation, or ask an owner of the namespace to grant them. | None. |
Example
import { $ } from 'startup-builder'
const { share, instrument } = await $.Instrument.exercise({ instrument: 'instrument_yZz4i2meOW', quantity: 1 })