> For the complete documentation index, see [llms.txt](https://docs.ipor.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ipor.io/build-on-fusion/atomists/curating-a-fusion-vault/integrating-pendle-pt-tokens.md).

# Integrating Pendle PT Tokens

Integrating Pendle Principal Tokens (PT) into an IPOR Fusion vault enables fixed-yield strategies. However, because PTs are yield-bearing assets with unique pricing and maturity mechanics, Atomists must follow a specific configuration workflow to ensure the vault correctly accounts for these assets.

This guide covers the three pillars of PT integration: **Tracking**, **Valuation**, and **Execution**.

### 1. Asset Tracking

By default, a Fusion Vault only "sees" the assets explicitly defined in its configuration. If an Alpha strategist swaps vault collateral for a Pendle PT, the asset will not appear in the vault's balance or the UI unless it is registered.

#### Adding Tracked Assets

Atomists must add the specific PT ERC20 address to the **Tracked Assets** list.

* **Why:** This ensures the vault's `totalAssets()` logic includes the PT balance.
* **Action:** Use the `PlasmaVaultGovernance` interface to add the PT contract address to the vault’s tracked ERC20 tokens (Market ID 7).

### 2. Valuation (Price Oracles)

Pendle PT tokens are not typically supported by standard Chainlink price feeds. Without a valid price feed, the vault cannot calculate its Total Value Locked (TVL) or the share price, often leading to a "0.00" display or transaction reverts.

#### Custom Price Feeds

Atomists must configure a **Custom Price Feed** via the `PriceOracleMiddleware`.

* **Mechanism:** PT tokens should be priced based on the underlying Pendle Market.
* **Configuration:** Instead of a direct spot price, use a specialized oracle that pulls the PT price from the **Pendle Market contract**. This is then registered in the `PriceOracleMiddleware` under the **Custom Price Feeds** section. Navigate to the `Price Feed` section in the Fusion interface to provide the Pendle Market address to derive the PT price relative to the underlying asset (e.g., PT-sDAI priced against sDAI).

Price feeds can be created with the [factory](https://app.ipor.io/build-on-fusion/price-feed/ethereum/pt).

### 3. Substrate Setup for Swapping

For the `UniversalTokenSwapper` to handle PT tokens, the Atomist must explicitly grant substrates for both the asset and the routing infrastructure.

1. **The PT Token:** Granted as an allowed asset (Type 1).
2. **The Pendle Router:** Granted as an allowed target for the swapper executor (Type 2).

### 4. Execution: Swapping vs. Minting

A common point of confusion is the difference between the **Pendle Fuse** and the **Universal Token Swapper**.

#### The Pendle Fuse

The specialized Pendle Fuse is designed for **primary market operations**:

* **Minting:** Converting an underlying asset into PT and YT.
* **Redeeming:** Converting PT back to the underlying asset *at maturity*.
* **Limit:** This fuse does not handle market swaps.

#### Swapping via Universal Token Swapper

To buy or sell PT tokens on the open market (secondary market) before maturity, you must use the **Universal Token Swapper** (Market ID: 12).

### 5. Technical: Substrate Encoding for Swapping

The `UniversalTokenSwapper` uses a typed substrate system. When configuring substrates for Pendle PTs via `grantMarketSubstrates`, use the following encoding logic provided by the `UniversalTokenSwapperSubstrateLib`:

| **Substrate Type** | **ID (Type Byte)** | **Usage for Pendle**                                                   |
| ------------------ | ------------------ | ---------------------------------------------------------------------- |
| **Token**          | `0x01`             | **PT Token Address:** Allows the swapper to spend/receive the PT.      |
| **Target**         | `0x02`             | **Pendle Router Address:** Allows the swapper to call the Router.      |
| **Slippage**       | `0x03`             | **Max Slippage:** Defines the USD-value delta allowed for the PT swap. |

#### Encoding Format

Substrates are `bytes32` values where the first byte is the Type ID:

* **Token/Target:** `[1-byte Type][11-byte zero padding][20-byte Address]`
* **Slippage:** `[1-byte Type][31-byte Slippage Value in WAD]`

### 6. Substrate Configuration Checklist

To successfully curate a vault using Pendle PTs, ensure the following substrates are granted:

| **Market**              | **Market ID** | **Required Substrate**                             |
| ----------------------- | ------------- | -------------------------------------------------- |
| **ERC20 Vault Balance** | 7             | The PT Token Address (to track holdings)           |
| **Universal Swapper**   | 12            | The PT Token Address (Type 1: Allowed token)       |
| **Universal Swapper**   | 12            | The Pendle Router Address (Type 2: Allowed target) |
| **Price Oracle**        | N/A           | Custom PT-to-Asset feed derived from Pendle Market |

### Atomist Pro-Tips

#### Handling Maturity

When a PT token reaches maturity, its price effectively becomes 1:1 with the underlying asset. However, the vault doesn't automatically "exit" the position. The Alpha must execute a `redeem` action via the Pendle Fuse or swap it out to move the capital back into a liquid state or a new PT vintage.

#### Decimal Sensitivity

PT tokens often have specific decimal configurations. Always verify the `underlyingDecimals` in the `PriceOracleMiddleware` match the PT's contract to avoid massive over- or under-valuation of the vault.

#### Testing on Forks

Before deploying to mainnet, always simulate the Pendle swap and balance update on a local fork (Anvil). Ensure that after the swap, `totalAssets()` correctly reflects the PT position and that the `updateMarketsBalances` function handles the custom oracle without reverting.