> For the complete documentation index, see [llms.txt](https://docs.callput.app/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.callput.app/developers/option-token-id-and-state-machine.md).

# Option token id and state machine

The two most important primitives in a Callput integration are `optionTokenId` and the request state machine.

## Identifier model

### `instrument`

A human-readable market label.

### `optionId`

An identifier for an individual option leg used as request input.

### `optionTokenId`

The final ERC-1155 position identifier created after request validation and normalization.

## `optionTokenId` bit layout

The shared encoding model packs `optionTokenId` into a 256-bit integer with the following structure.

| Bits            | Meaning                                  |
| --------------- | ---------------------------------------- |
| `[255:240]`     | `underlyingAssetIndex`                   |
| `[239:200]`     | `expiry`                                 |
| `[199:196]`     | `strategy`                               |
| `[195:194]`     | `length - 1`                             |
| repeated blocks | per-leg `isBuy`, `strikePrice`, `isCall` |
| `[1:0]`         | `vaultIndex`                             |

## Strategy and leg normalization

The final `optionTokenId` is not a raw record of the original input order. Callput normalizes strikes and the associated leg metadata before determining the final strategy.

That matters most for spread handling. The final `optionTokenId` should always be treated as the authoritative position identifier.

## Request state machine

The request lifecycle enum is:

* `Pending`
* `Cancelled`
* `Executed`

These states apply to both open requests and close requests.

## Open request state machine

### Create

The user submits an open request.

### Pending

The request is waiting in the queue.

### Executed

The position is created successfully.

### Cancelled

The request ended without execution.

## Close request state machine

### Create

The user submits a close request.

### Pending

The request is waiting in the queue, and the relevant option token amount can already be held inside `PositionManager`.

### Executed

The close completed successfully.

### Cancelled

The close request ended without execution and the option token amount is returned.

## Core takeaway

Use `optionTokenId` for final position identity, and use the request key plus request status for lifecycle tracking.