> 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/request-lifecycle-reference.md).

# Request lifecycle reference

This page documents the exact request primitives an external integration should track for open and close flows.

## Core primitives

Every integration should treat these as first-class data:

* request key
* request type (`open` or `close`)
* request status (`Pending`, `Cancelled`, `Executed`)
* request-specific state from `PositionManager`

## Where the request key comes from

### Open requests

The following functions return a `bytes32` request key:

* `createOpenPosition(...)`
* `createOpenPositionNAT(...)`

### Close requests

The following function returns a `bytes32` request key:

* `createClosePosition(...)`

### Event source

For both open and close flows, `PositionManager` also emits:

* `GenerateRequestKey(account, key, isOpen)`

If your transaction-sending stack does not surface the return value from a state-changing call, parse the transaction receipt and index `GenerateRequestKey`.

## Status enum

The lifecycle enum is:

* `Pending = 0`
* `Cancelled = 1`
* `Executed = 2`

These statuses apply to both open requests and close requests.

## Open-request read model

Read open-request state from:

* `openPositionRequests(requestKey)`
* `getOpenPositionRequestPath(requestKey)`

The important returned fields are:

* `account`
* `underlyingAssetIndex`
* `expiry`
* `optionTokenId`
* `minSize`
* `amountIn`
* `minOutWhenSwap`
* `status`
* `sizeOut`
* `executionPrice`
* `processBlockTime`
* `amountOut`

## Close-request read model

Read close-request state from:

* `closePositionRequests(requestKey)`
* `getClosePositionRequestPath(requestKey)`

The important returned fields are:

* `account`
* `underlyingAssetIndex`
* `expiry`
* `optionTokenId`
* `size`
* `minAmountOut`
* `minOutWhenSwap`
* `withdrawNAT`
* `status`
* `amountOut`
* `executionPrice`
* `processBlockTime`

## Request-queue metadata

If you also index queue order, use:

* `positionRequestKeys(index)`
* `positionRequestTypes(index)`
* `getPositionRequestInfo(requestIndex)`

This metadata is useful for operator dashboards and queue analytics, but the canonical lifecycle lookup for an external user remains the request key.

## Minimal integration sequence

1. submit the open or close transaction
2. capture the request key from the function return or `GenerateRequestKey`
3. persist the request key together with request type and intended position metadata
4. poll the corresponding request getter in `PositionManager`
5. treat `Executed` and `Cancelled` as terminal states
6. reconcile token balances, execution output, and expiry state

## What to persist

At minimum, persist:

* chain ID
* account
* request type
* request key
* transaction hash
* intended `optionTokenId` or display-market mapping
* creation timestamp
* expiry

## Common integration mistakes

* relying on the transaction hash instead of the request key
* assuming the request is final immediately after the transaction is mined
* reading only ERC-1155 balances without checking request status
* forgetting that close requests can transfer the option token into `PositionManager` while the request is still `Pending`