Skip to content
StartupBuilder
by startups.studio
by Startups.Studio
Code
Changelog
APIFinanceInstrument

Instrument routes: cancel, convert, exercise

The Instrument Verbs cancel, convert, exercise as api.sb routes, with inputs, result, refusals and an example.

Reference for Instrument, one group of Instrument routes.

Instrument.cancel

Cancel ends an unvested, expired or forfeited Instrument and returns any option Shares to the pool. Verb page.

Text
POST /{namespace}/instruments/{instrument}/cancel

Path: instrument. Body, as JSON: the other inputs. Emits Instrument.canceled.

Inputs

InputTypeRequiredDescription
instrumentInstrumentrequiredThe Instrument to end.
reasonstringrequiredWhy it ends: unvested, expired or forfeited.

Returns

OutputTypeRequiredDescription
instrumentInstrumentrequiredThe canceled Instrument, kept with its history.

Refuses when

CheckErrorFixThen call
The key is valid, but its scopes do not allow this operation.forbiddenUse a key whose scopes cover the operation, or ask an owner of the namespace to grant them.None.

Example

Terminal
curl -X POST https://api.sb/leaseline.app/instruments/instrument_yZz4i2meOW/cancel \
  -H "Authorization: Bearer $STARTUP_BUILDER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"reason":"unvested"}'
JSON
{
  "api": "https://api.sb/leaseline.app",
  "instrument": {
    "$id": "https://api.sb/leaseline.app/instruments/instrument_yZz4i2meOW",
    "$type": "Instrument",
    "kind": "safe",
    "status": "outstanding"
  },
  "action": {
    "$id": "https://api.sb/leaseline.app/actions/act_br07HsG8MG",
    "operation": "Instrument.cancel",
    "status": "done"
  },
  "links": {
    "self": "https://api.sb/leaseline.app/actions/act_br07HsG8MG"
  }
}

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.

Text
POST /{namespace}/instruments/{instrument}/convert

Path: instrument. Body, as JSON: the other inputs. Emits Instrument.converted.

Inputs

InputTypeRequiredDescription
instrumentInstrumentrequiredThe SAFE or note.
roundPricemoneyrequiredThe price per Share of the priced round.

Returns

OutputTypeRequiredDescription
shareslist of SharerequiredThe Shares issued on conversion.
instrumentInstrumentrequiredThe Instrument, now converted.

Refuses when

CheckErrorFixThen call
The key is valid, but its scopes do not allow this operation.forbiddenUse a key whose scopes cover the operation, or ask an owner of the namespace to grant them.None.

Example

Terminal
curl -X POST https://api.sb/leaseline.app/instruments/instrument_yZz4i2meOW/convert \
  -H "Authorization: Bearer $STARTUP_BUILDER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"roundPrice":{"amount":29,"currency":"USD"}}'
JSON
{
  "api": "https://api.sb/leaseline.app",
  "shares": [
    {
      "$id": "https://api.sb/leaseline.app/shares/share_yiQ4iEmeOW",
      "$type": "Share",
      "class": "common",
      "quantity": 1
    }
  ],
  "instrument": {
    "$id": "https://api.sb/leaseline.app/instruments/instrument_yZz4i2meOW",
    "$type": "Instrument",
    "kind": "safe",
    "status": "outstanding"
  },
  "action": {
    "$id": "https://api.sb/leaseline.app/actions/act_br07HsG8MG",
    "operation": "Instrument.convert",
    "status": "done"
  },
  "links": {
    "self": "https://api.sb/leaseline.app/actions/act_br07HsG8MG"
  }
}

Instrument.exercise

Exercise buys the Shares an option or warrant covers at its strike price, up to what has vested. Verb page.

Text
POST /{namespace}/instruments/{instrument}/exercise

Path: instrument. Body, as JSON: the other inputs. Emits Instrument.exercised.

Inputs

InputTypeRequiredDescription
instrumentInstrumentrequiredThe option or warrant.
quantityintegerrequiredHow many Shares to buy.

Returns

OutputTypeRequiredDescription
shareSharerequiredThe Shares bought.
instrumentInstrumentrequiredThe Instrument, now exercised.

Refuses when

CheckErrorFixThen call
The key is valid, but its scopes do not allow this operation.forbiddenUse a key whose scopes cover the operation, or ask an owner of the namespace to grant them.None.

Example

Terminal
curl -X POST https://api.sb/leaseline.app/instruments/instrument_yZz4i2meOW/exercise \
  -H "Authorization: Bearer $STARTUP_BUILDER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"quantity":1}'
JSON
{
  "api": "https://api.sb/leaseline.app",
  "share": {
    "$id": "https://api.sb/leaseline.app/shares/share_yiQ4iEmeOW",
    "$type": "Share",
    "class": "common",
    "quantity": 1
  },
  "instrument": {
    "$id": "https://api.sb/leaseline.app/instruments/instrument_yZz4i2meOW",
    "$type": "Instrument",
    "kind": "safe",
    "status": "outstanding"
  },
  "action": {
    "$id": "https://api.sb/leaseline.app/actions/act_br07HsG8MG",
    "operation": "Instrument.exercise",
    "status": "done"
  },
  "links": {
    "self": "https://api.sb/leaseline.app/actions/act_br07HsG8MG"
  }
}

get, list

Previous

grant

Next