> ## Documentation Index
> Fetch the complete documentation index at: https://docs.launchboard.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Transactions API: issue, transfer, exercise, cancel

> Record ledger mutations on your cap table — issue shares or options, transfer securities between stakeholders, exercise options, and cancel positions.

Transactions are the append-only ledger mutations that change ownership state on your cap table. Every equity event — issuing stock to a founder, granting options to an employee, transferring shares to a new investor, exercising vested options, or cancelling a forfeited grant — is recorded as a transaction. Once written, transaction records are immutable; corrections are made by recording a subsequent offsetting transaction.

Use the specialized sub-routes (`/issue-shares`, `/issue-options`, `/transfer`, `/exercise`, `/cancel`) for typed operations with focused validation. The generic `POST /transactions` endpoint accepts any `type` value but performs less validation — prefer the specialized routes when the operation fits their shape.

## List transactions

Returns a cursor-paginated log of all transactions for your organization, ordered most-recent first. You can filter by `type` to narrow results to a specific event kind.

**`GET /api/v1/transactions`**

| Query param | Type    | Description                                                                  |
| ----------- | ------- | ---------------------------------------------------------------------------- |
| `type`      | string  | Filter by transaction type (e.g. `STOCK_ISSUANCE`, `STOCK_OPTION_EXERCISE`). |
| `limit`     | integer | Page size. Defaults to 25, maximum 100.                                      |
| `cursor`    | string  | Opaque cursor returned as `nextCursor` from the previous page.               |

<CodeGroup>
  ```bash cURL theme={null}
  curl https://launchboard.xyz/api/v1/transactions \
    -H "Authorization: Bearer pg_live_your_key"
  ```

  ```bash Filter by type theme={null}
  curl "https://launchboard.xyz/api/v1/transactions?type=STOCK_ISSUANCE&limit=50" \
    -H "Authorization: Bearer pg_live_your_key"
  ```
</CodeGroup>

**Response**

```json theme={null}
{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440001",
      "orgId": "550e8400-e29b-41d4-a716-446655440000",
      "type": "STOCK_ISSUANCE",
      "securityId": "550e8400-e29b-41d4-a716-446655440010",
      "stakeholderId": "550e8400-e29b-41d4-a716-446655440020",
      "quantity": "1000000",
      "effectiveDate": "2024-01-15",
      "metadata": { "boardApprovalDate": "2024-01-10" },
      "createdAt": "2024-01-15T14:30:00.000Z"
    }
  ],
  "nextCursor": "eyJpZCI6IjU1MGU4NDAwIiwiY3JlYXRlZEF0IjoiMjAyNC0wMS0xNVQxNDozMDowMC4wMDBaIn0"
}
```

<ResponseField name="data" type="Transaction[]">
  Array of transaction log entries.
</ResponseField>

<ResponseField name="data[].id" type="string (uuid)">
  Unique transaction ID.
</ResponseField>

<ResponseField name="data[].type" type="string">
  Transaction type. One of: `STOCK_ISSUANCE`, `STOCK_OPTION_ISSUANCE`, `WARRANT_ISSUANCE`, `CONVERTIBLE_ISSUANCE`, `STOCK_TRANSFER`, `STOCK_OPTION_TRANSFER`, `WARRANT_TRANSFER`, `CONVERTIBLE_TRANSFER`, `STOCK_OPTION_EXERCISE`, `WARRANT_EXERCISE`, `CONVERTIBLE_CONVERSION`, `STOCK_CANCELLATION`, `STOCK_OPTION_CANCELLATION`, `WARRANT_CANCELLATION`, `CONVERTIBLE_CANCELLATION`, `STOCK_REPURCHASE`, `VESTING_START`, `VESTING_ACCELERATION`, `VESTING_EVENT`, `STOCK_CLASS_ADJUSTMENT`, `STOCK_PLAN_ADJUSTMENT`, `STOCK_SPLIT`, `STOCK_RETRACTION`, `STAKEHOLDER_UPDATE`, `VALUATION_UPDATE`.
</ResponseField>

<ResponseField name="data[].securityId" type="string (uuid) | null">
  The security this transaction applies to, when applicable.
</ResponseField>

<ResponseField name="data[].stakeholderId" type="string (uuid) | null">
  Primary stakeholder involved in the transaction.
</ResponseField>

<ResponseField name="data[].quantity" type="string | null">
  Number of shares or units, serialized as a string to preserve precision.
</ResponseField>

<ResponseField name="data[].effectiveDate" type="string">
  Date the transaction took effect (`YYYY-MM-DD`).
</ResponseField>

<ResponseField name="data[].metadata" type="object | null">
  Type-specific supplementary data (approval dates, transfer reasons, exercise prices, etc.).
</ResponseField>

<ResponseField name="nextCursor" type="string | null">
  Pass as `cursor` to retrieve the next page. `null` when there are no more results.
</ResponseField>

***

## Issue shares

Creates a stock issuance transaction and records the resulting security. If the target share class has tokenization enabled, tokens are minted on-chain immediately — no separate approval gate is required.

**`POST /api/v1/transactions/issue-shares`**

Requires role: **EDITOR**. Idempotent with an `Idempotency-Key` header.

<ParamField body="stakeholderId" type="string (uuid)" required>
  ID of the stakeholder receiving the shares.
</ParamField>

<ParamField body="stockClassId" type="string (uuid)" required>
  ID of the share class to issue from.
</ParamField>

<ParamField body="quantity" type="string" required>
  Number of shares to issue. Pass as a string to preserve precision (e.g. `"1000000"`).
</ParamField>

<ParamField body="certificateId" type="string" required>
  Human-readable certificate identifier (e.g. `"CS-001"`). Maximum 50 characters.
</ParamField>

<ParamField body="effectiveDate" type="string" required>
  Date the issuance takes effect (`YYYY-MM-DD`).
</ParamField>

<ParamField body="pricePerShare" type="string">
  Price per share at issuance. Pass as a string (e.g. `"1.50"`). Defaults to `null`.
</ParamField>

<ParamField body="vestingTermsId" type="string (uuid)">
  ID of the vesting schedule to attach. Omit for immediately vested grants.
</ParamField>

<ParamField body="vestingStartDate" type="string">
  Date vesting begins (`YYYY-MM-DD`). Defaults to `effectiveDate` when omitted.
</ParamField>

<ParamField body="valuationId" type="string (uuid)">
  ID of the valuation used to price this issuance.
</ParamField>

<ParamField body="boardApprovalDate" type="string">
  Date the board approved this issuance (`YYYY-MM-DD`).
</ParamField>

<ParamField body="stockholderApprovalDate" type="string">
  Date stockholder approval was obtained (`YYYY-MM-DD`).
</ParamField>

<ParamField body="description" type="string">
  Optional notes. Maximum 2000 characters.
</ParamField>

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://launchboard.xyz/api/v1/transactions/issue-shares \
    -H "Authorization: Bearer pg_live_your_key" \
    -H "Content-Type: application/json" \
    -H "Idempotency-Key: issuance-alice-series-a-2024" \
    -d '{
      "stakeholderId": "550e8400-e29b-41d4-a716-446655440020",
      "stockClassId": "550e8400-e29b-41d4-a716-446655440030",
      "quantity": "5000000",
      "certificateId": "CS-001",
      "effectiveDate": "2024-03-01",
      "pricePerShare": "2.00",
      "boardApprovalDate": "2024-02-28"
    }'
  ```
</CodeGroup>

**Response — `201 Created`**

```json theme={null}
{
  "data": {
    "transactionId": "550e8400-e29b-41d4-a716-446655440001",
    "securityId": "550e8400-e29b-41d4-a716-446655440010"
  }
}
```

<ResponseField name="data.transactionId" type="string (uuid)">
  ID of the ledger transaction record.
</ResponseField>

<ResponseField name="data.securityId" type="string (uuid)">
  ID of the newly created security. Use this to fetch full security details via `GET /api/v1/securities/{id}`.
</ResponseField>

<Note>
  If the share class is tokenized (`tokenizationStatus: "DEPLOYED"`), Launchboard mints the corresponding SPL tokens to the stakeholder's wallet immediately after the transaction commits. Token minting happens asynchronously in the background — the `201` response is returned before minting completes.
</Note>

***

## Issue options

Creates a stock option grant transaction and records the resulting security.

**`POST /api/v1/transactions/issue-options`**

Requires role: **EDITOR**. Idempotent with an `Idempotency-Key` header.

<ParamField body="stakeholderId" type="string (uuid)" required>
  ID of the stakeholder receiving the option grant.
</ParamField>

<ParamField body="stockPlanId" type="string (uuid)" required>
  ID of the equity plan (option pool) to draw from.
</ParamField>

<ParamField body="quantity" type="string" required>
  Number of options to grant (e.g. `"100000"`).
</ParamField>

<ParamField body="exercisePrice" type="string" required>
  Per-share strike price (e.g. `"0.10"`).
</ParamField>

<ParamField body="optionType" type="string" required>
  `ISO` or `NSO`.
</ParamField>

<ParamField body="certificateId" type="string" required>
  Human-readable grant identifier (e.g. `"OPT-042"`). Maximum 50 characters.
</ParamField>

<ParamField body="effectiveDate" type="string" required>
  Grant date (`YYYY-MM-DD`).
</ParamField>

<ParamField body="stockClassId" type="string (uuid)">
  Share class the options convert into upon exercise. Typically inferred from the equity plan.
</ParamField>

<ParamField body="expirationDate" type="string">
  Date the options expire unexercised (`YYYY-MM-DD`). Defaults to 10 years from grant date when omitted.
</ParamField>

<ParamField body="vestingTermsId" type="string (uuid)">
  Vesting schedule to attach to this grant.
</ParamField>

<ParamField body="vestingStartDate" type="string">
  Date vesting begins (`YYYY-MM-DD`).
</ParamField>

<ParamField body="boardApprovalDate" type="string">
  Board approval date (`YYYY-MM-DD`).
</ParamField>

<ParamField body="valuationId" type="string (uuid)">
  Valuation used to set the 409A-compliant exercise price.
</ParamField>

<ParamField body="description" type="string">
  Optional notes. Maximum 2000 characters.
</ParamField>

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://launchboard.xyz/api/v1/transactions/issue-options \
    -H "Authorization: Bearer pg_live_your_key" \
    -H "Content-Type: application/json" \
    -H "Idempotency-Key: grant-bob-2024-q1" \
    -d '{
      "stakeholderId": "550e8400-e29b-41d4-a716-446655440021",
      "stockPlanId": "550e8400-e29b-41d4-a716-446655440031",
      "quantity": "100000",
      "exercisePrice": "0.10",
      "optionType": "ISO",
      "certificateId": "OPT-042",
      "effectiveDate": "2024-03-15",
      "vestingTermsId": "550e8400-e29b-41d4-a716-446655440040",
      "boardApprovalDate": "2024-03-14"
    }'
  ```
</CodeGroup>

**Response — `201 Created`**

```json theme={null}
{
  "data": {
    "transactionId": "550e8400-e29b-41d4-a716-446655440002",
    "securityId": "550e8400-e29b-41d4-a716-446655440011"
  }
}
```

***

## Transfer a security

Moves a security (or part of a security) from one stakeholder to another. The original security is partially or fully cancelled and a new security is created for the recipient.

**`POST /api/v1/transactions/transfer`**

Requires role: **EDITOR**. Idempotent with an `Idempotency-Key` header.

<ParamField body="securityId" type="string (uuid)" required>
  ID of the security to transfer.
</ParamField>

<ParamField body="fromStakeholderId" type="string (uuid)" required>
  ID of the current holder transferring the security.
</ParamField>

<ParamField body="toStakeholderId" type="string (uuid)" required>
  ID of the stakeholder receiving the security.
</ParamField>

<ParamField body="quantity" type="string" required>
  Number of shares to transfer. Must be less than or equal to the security's current quantity.
</ParamField>

<ParamField body="effectiveDate" type="string" required>
  Date the transfer takes effect (`YYYY-MM-DD`).
</ParamField>

<ParamField body="pricePerShare" type="string">
  Transfer price per share, if applicable (e.g. secondary sale).
</ParamField>

<ParamField body="transferReason" type="string">
  Free-text reason for the transfer (e.g. `"Secondary sale — Series B"`).
</ParamField>

<ParamField body="boardApprovalDate" type="string">
  Board approval date (`YYYY-MM-DD`).
</ParamField>

<ParamField body="description" type="string">
  Optional notes. Maximum 2000 characters.
</ParamField>

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://launchboard.xyz/api/v1/transactions/transfer \
    -H "Authorization: Bearer pg_live_your_key" \
    -H "Content-Type: application/json" \
    -H "Idempotency-Key: transfer-alice-to-carol-2024" \
    -d '{
      "securityId": "550e8400-e29b-41d4-a716-446655440010",
      "fromStakeholderId": "550e8400-e29b-41d4-a716-446655440020",
      "toStakeholderId": "550e8400-e29b-41d4-a716-446655440022",
      "quantity": "250000",
      "effectiveDate": "2024-04-01",
      "pricePerShare": "3.50",
      "transferReason": "Secondary sale"
    }'
  ```
</CodeGroup>

**Response — `201 Created`**

```json theme={null}
{
  "data": {
    "transactionId": "550e8400-e29b-41d4-a716-446655440003",
    "newSecurityId": "550e8400-e29b-41d4-a716-446655440012"
  }
}
```

<ResponseField name="data.newSecurityId" type="string (uuid)">
  ID of the new security created for the recipient. The `Location` response header also points to `GET /api/v1/securities/{newSecurityId}`.
</ResponseField>

***

## Exercise options

Converts vested options into stock. The source option security is partially or fully cancelled and a new `STOCK` security is created for the exercising stakeholder.

**`POST /api/v1/transactions/exercise`**

Requires role: **EDITOR**. Idempotent with an `Idempotency-Key` header.

<ParamField body="securityId" type="string (uuid)" required>
  ID of the option security to exercise.
</ParamField>

<ParamField body="quantity" type="string" required>
  Number of options to exercise.
</ParamField>

<ParamField body="exercisePrice" type="string" required>
  Per-share exercise price at the time of exercise (e.g. `"0.10"`).
</ParamField>

<ParamField body="effectiveDate" type="string" required>
  Exercise date (`YYYY-MM-DD`).
</ParamField>

<ParamField body="paymentMethod" type="string">
  `CASH`, `CASHLESS`, or `NET_EXERCISE`. Defaults to `CASH` when omitted.
</ParamField>

<ParamField body="boardApprovalDate" type="string">
  Board approval date (`YYYY-MM-DD`).
</ParamField>

<ParamField body="description" type="string">
  Optional notes. Maximum 2000 characters.
</ParamField>

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://launchboard.xyz/api/v1/transactions/exercise \
    -H "Authorization: Bearer pg_live_your_key" \
    -H "Content-Type: application/json" \
    -H "Idempotency-Key: exercise-bob-opt042-2024" \
    -d '{
      "securityId": "550e8400-e29b-41d4-a716-446655440011",
      "quantity": "25000",
      "exercisePrice": "0.10",
      "paymentMethod": "CASH",
      "effectiveDate": "2024-06-01"
    }'
  ```
</CodeGroup>

**Response — `201 Created`**

```json theme={null}
{
  "data": {
    "transactionId": "550e8400-e29b-41d4-a716-446655440004",
    "newSecurityId": "550e8400-e29b-41d4-a716-446655440013"
  }
}
```

<ResponseField name="data.newSecurityId" type="string (uuid)">
  ID of the new `STOCK` security created for the exercised shares.
</ResponseField>

***

## Cancel a security

Records a cancellation, forfeiture, expiration, or repurchase of a security. The security's status transitions to `CANCELLED`. If `returnToPool` is `true` and the security is an option, the cancelled quantity is returned to the equity plan pool.

**`POST /api/v1/transactions/cancel`**

Requires role: **EDITOR**. Idempotent with an `Idempotency-Key` header.

<ParamField body="securityId" type="string (uuid)" required>
  ID of the security to cancel.
</ParamField>

<ParamField body="quantity" type="string" required>
  Number of shares or options to cancel. For a full cancellation, pass the security's full quantity.
</ParamField>

<ParamField body="cancellationReason" type="string" required>
  `FORFEITURE`, `EXPIRATION`, `REPURCHASE`, or `TERMINATION`.
</ParamField>

<ParamField body="effectiveDate" type="string" required>
  Date the cancellation takes effect (`YYYY-MM-DD`).
</ParamField>

<ParamField body="returnToPool" type="boolean">
  When `true`, the cancelled option quantity is returned to the equity plan pool. Defaults to `false`.
</ParamField>

<ParamField body="boardApprovalDate" type="string">
  Board approval date (`YYYY-MM-DD`).
</ParamField>

<ParamField body="description" type="string">
  Optional notes. Maximum 2000 characters.
</ParamField>

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://launchboard.xyz/api/v1/transactions/cancel \
    -H "Authorization: Bearer pg_live_your_key" \
    -H "Content-Type: application/json" \
    -H "Idempotency-Key: cancel-bob-opt042-forfeiture" \
    -d '{
      "securityId": "550e8400-e29b-41d4-a716-446655440011",
      "quantity": "75000",
      "cancellationReason": "FORFEITURE",
      "returnToPool": true,
      "effectiveDate": "2024-05-15"
    }'
  ```
</CodeGroup>

**Response — `200 OK`**

```json theme={null}
{
  "data": {
    "transactionId": "550e8400-e29b-41d4-a716-446655440005"
  }
}
```

***

## Error codes

| Status | When it occurs                                                                                     |
| ------ | -------------------------------------------------------------------------------------------------- |
| `401`  | Missing or invalid API key.                                                                        |
| `403`  | Key role is below the required level (`EDITOR`).                                                   |
| `404`  | Referenced security, stakeholder, or share class not found.                                        |
| `422`  | Request body failed validation — check the `errors` field in the response for field-level details. |