> 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/integration-guide.md).

# Integration guide

This guide provides the shortest path from zero context to a working Callput integration.

The two most important companion references are:

* [Pricing Mechanics](/traders/pricing-mechanism.md)
* [Request Lifecycle Reference](/developers/request-lifecycle-reference.md)

## Before you start

Lock down these assumptions first.

* Base is the current public documentation baseline
* tradable market discovery comes from the public market feed
* open and close request truth comes from `PositionManager`
* post-expiry settlement truth comes from `SettleManager`
* `ViewAggregator` is a convenience layer, not the canonical tradable market source

## Source-of-truth matrix

| Task                          | Primary source                           | Notes                            |
| ----------------------------- | ---------------------------------------- | -------------------------------- |
| tradable market discovery     | public market feed                       | current public baseline          |
| displayed price and greeks    | public market feed                       | market exploration layer         |
| contract addresses            | Base address bundle                      | verify before shipping           |
| open and close request status | `PositionManager`                        | requires `request key`           |
| position balance              | ERC-1155 options token                   | pending close can be misleading  |
| settlement eligibility        | expiry + token balance + `SettleManager` | pre-expiry settlement is invalid |

## Read path

{% stepper %}
{% step %}

#### Load the tradable market list

Pull the current market listing from the public market feed.
{% endstep %}

{% step %}

#### Normalize the display model

Convert instrument, expiry, strike, strategy, mark IV, mark price, and greeks into your application model.
{% endstep %}

{% step %}

#### Map display state to execution state

Map the displayed market state to the leg-level request inputs and, eventually, to the final `optionTokenId`.
{% endstep %}

{% step %}

#### Load address and token metadata

Use the Base address bundle for `PositionManager`, `SettleManager`, and the relevant options token contracts.
{% endstep %}
{% endstepper %}

## Open request flow

{% stepper %}
{% step %}

#### Validate user input

* check the network
* check the allowed underlying
* check expiry against the deadline buffer
* check balance and allowance
  {% endstep %}

{% step %}

#### Build request parameters

An open request typically needs:

* underlying asset index
* position length
* `isBuys`
* `optionIds`
* `isCalls`
* `_minSize`
* `path`
* `amountIn`
* `_minOutWhenSwap`
* `leadTrader`
  {% endstep %}

{% step %}

#### Include the execution fee

The current exact execution fee required by `PositionManager` must be provided.
{% endstep %}

{% step %}

#### Submit the transaction

Call `createOpenPosition` or `createOpenPositionNAT` when appropriate.

Both functions return a `bytes32` request key.
{% endstep %}

{% step %}

#### Persist the request key

Use this priority order:

1. the returned `bytes32` from the contract call
2. the `GenerateRequestKey(account, key, isOpen)` event in the receipt
3. queue metadata only as a secondary index

Do not rely on the transaction hash alone.
{% endstep %}

{% step %}

#### Poll for lifecycle status

Use `openPositionRequests(requestKey)` and `getOpenPositionRequestPath(requestKey)` to resolve `Pending`, `Executed`, or `Cancelled`.
{% endstep %}
{% endstepper %}

## Close request flow

{% stepper %}
{% step %}

#### Confirm the current position balance

Make sure the user actually holds the relevant `optionTokenId` balance.
{% endstep %}

{% step %}

#### Check expiry and close eligibility

The request must be outside the deadline buffer and valid under trading-hours rules.
{% endstep %}

{% step %}

#### Submit `createClosePosition`

Include the size, path, minimum output constraints, and execution fee.

`createClosePosition` returns a `bytes32` request key.
{% endstep %}

{% step %}

#### Handle pending-close state correctly

When the close request is created, the option token amount can already be transferred into `PositionManager`.

Read state from `closePositionRequests(requestKey)` and `getClosePositionRequestPath(requestKey)`.
{% endstep %}
{% endstepper %}

## Settlement flow

{% stepper %}
{% step %}

#### Verify expiry

Do not attempt settlement before expiry.
{% endstep %}

{% step %}

#### Verify token balance

The user must hold the relevant `optionTokenId` balance.
{% endstep %}

{% step %}

#### Choose the output path

Decide whether to accept the default payout asset or use a swap path.
{% endstep %}

{% step %}

#### Call `SettleManager`

Persist the settlement result and update local inventory accordingly.
{% endstep %}
{% endstepper %}

## What a minimal robust integration looks like

At minimum, the integration should persist:

* chain ID
* account
* request key
* request type
* transaction hash
* intended `optionTokenId`
* creation time
* expiry

Without that request-lifecycle layer, the integration can submit transactions but cannot operate reliably.