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

# Integrating with Moment

> What an integrator needs: the vault, reading a TimeBalance, sync and present value.

For builders.

To integrate with Moment you need an ERC-4626 vault as input, a way to read a TimeBalance as windows of TBT, the sync rules, and present-value math.

> [!WARNING]
>
> Contract names, function names, addresses and ABIs will be published at launch. See [Contracts and parameters](https://docs.momentrates.xyz/for-builders/contracts-and-parameters.md).

## 1. The input: an ERC-4626 vault

Every Moment market is built on one ERC-4626 vault. In the example market the vault share is sUSDS and the underlying asset is USDS.

* TBT is denominated in the **underlying asset**, not in shares.
* The only price Moment reads is the vault's `previewRedeem`. There is no external oracle.
* Your integration should treat the vault as the source of truth for value. If the vault loses value, every TimeBalance on it does too.

Routing in from a wallet token goes: token → underlying asset → vault shares → TimeBalance. Wrapping and unwrapping carry no Moment fee. See [Fixed](https://docs.momentrates.xyz/use-the-app/fixed.md).

## 2. Reading a TimeBalance

A TimeBalance is a shape, not a number. A read should return the amount held in each period, plus the amount from the last maturity on:

$$
\{\,(\,[\text{Now}, M_1),\ h_1\,),\ (\,[M_1, M_2),\ h_2\,),\ \dots,\ (\,[M_n, \infty),\ h_{n+1}\,)\,\}
$$

Things to handle:

* **Windows move.** When a maturity passes, its window starts at Now ([invariant 4](https://docs.momentrates.xyz/for-builders/how-it-works.md#invariant-4-time-moves-the-start)). Read against the current block time.
* **Units only add within a window.** Never sum $h_i$ across windows to get "a balance".
* **The current period is what earns.** The amount in $[\text{Now}, \cdot)$ is what earns the vault's yield right now.
* **Liquidity is held separately.** TBT in limit orders and Recursive bins is not in the free TimeBalance. Value it from the LP position. Filled amounts move into the TimeBalance at the next sync, so count them once.

## 3. Sync semantics

Balances change at **sync**, not continuously on-chain. Any interaction with a position syncs it.

* Yield since the last sync is added to the base TimeBalance as a flat amount over $[\text{Now}, \infty)$, net of the 5% performance fee. There is no claim step.
* Limit fills land in the maker's TimeBalance at the maker's next sync.
* LP tokens and their bin sync together, separately from the free TimeBalance. An LP sync pays more LP tokens plus base TBT.

For an integration this means a stored balance can be stale. Either sync before acting, or use a view that includes pending yield.

## 4. Measuring value: present value

To show a single number for a position, or to total TVL, use **present value**:

$$
\text{PV} = \sum_i h_i \,\big(D(a_i) - D(b_i)\big), \qquad D(\text{Now}) = 1,\ D(\infty) = 0
$$

where $[a_i, b_i)$ are the windows held, $h_i$ the amount in each, and $D$ is the discount factor from the book's period rates:

$$
D(M_n) = \prod_{j=1}^{n} \frac{1}{1 + r_j t_j}
$$

> [!CAUTION]
>
> Never report raw TBT units added across windows. A short window of 2,500 TBT can be worth a few dollars.

Each period's discount uses the **mid** of its best bid and best ask. If only one side exists, use that side. If neither exists, present value is **N/A**: it cannot be calculated. The Dashboard and the TVL metric use the same rule.

## 5. Trading and liquidity from a contract

| Need | What to know |
| - | - |
| Quote a trade | Rates are per period; a multi-period trade chains them. Quotes are net of the 0.5% taker fee. |
| Execute a trade | Multi-period trades are atomic. Pass a slippage bound on the whole route and a deadline. |
| Place a limit order | One side, one maturity, one rate. Joins the bin's open cohort. LP tokens do not rebase. |
| Add recursive liquidity | Both sides at the bin's current ratio; LP tokens rebase. |
| Handle maturity | Nothing to do. Bins stop quoting; positions become plain TimeBalance. |

## 6. Deployments

Networks, addresses and market IDs will be listed in [Contracts and parameters](https://docs.momentrates.xyz/for-builders/contracts-and-parameters.md) at launch.


## Related topics

- [What is Moment?](https://docs.momentrates.xyz/start/what-is-moment.md)
- [Moment: choose when you earn yield](https://docs.momentrates.xyz/index.md)
- [Brand kit](https://docs.momentrates.xyz/about/brand-kit.md)
- [Leverage](https://docs.momentrates.xyz/use-the-app/leverage.md)
- [For traders](https://docs.momentrates.xyz/background/for-traders.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.