> For the complete documentation index, see [llms.txt](https://docs.fira.money/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.fira.money/developers/integrations.md).

# Integrations

A practical guide for protocols and front-ends integrating with Fira's on-chain contracts.

This section is aimed at developers who want to build on top of the Fira Protocol — whether you are a DeFi aggregator routing swaps, a lending protocol using Fira yield tokens as collateral, or a front-end displaying position data.

{% hint style="info" %}
All Fira contracts are deployed on Ethereum mainnet. See [Deployment](https://docs.fira.money/developers/deployment.md) for addresses.
{% endhint %}

## Quick start

### 1. Identify the entry point

| Goal                            | Contract    | Key interface                   |
| ------------------------------- | ----------- | ------------------------------- |
| Wrap USDC into yield-bearing FW | USDCFW      | `IFiraWrappedStandardized`      |
| Swap BT ↔ FW                    | FiraMarket  | `IPMarket`                      |
| Mint / redeem BT + CT           | CouponToken | `IBCToken`                      |
| Add / remove LP liquidity       | FiraRouter  | `IPActionAddRemoveLiqV3`        |
| Borrow at fixed rate            | FiraRouter  | `IPActionBorrow`                |
| Read market state & oracle      | FiraMarket  | `IPMarket.readState`, `observe` |

### 2. Approve tokens

All Fira entry points pull tokens from `msg.sender` via `transferFrom`. Before calling any state-mutating function, approve the target contract (or the Router) for the relevant ERC-20.

### 3. Use the Router or call contracts directly

The **FiraRouter** aggregates most user-facing actions behind a single address with typed facet interfaces. Integrators can:

* Call **Router facets** for complex multi-step flows (swap + borrow, add liquidity with single-sided input, etc.).
* Call **individual contracts** (FiraMarket, USDCFW, CouponToken) directly for simpler interactions.

{% hint style="warning" %}
If calling FiraMarket swap functions directly (not via Router), you must implement the `IPMarketSwapCallback` interface. The market uses a flash-callback pattern: it transfers tokens to you first, then calls your callback to pull payment.
{% endhint %}

## Common patterns

### Reading prices and rates

```solidity
// Current FW exchange rate (1e18 scale)
uint256 rate = IFiraWrappedStandardized(fw).exchangeRate();

// Market state including implied rate, reserves, TWAP
MarketState memory state = IPMarket(market).readState(router);

// BC Index (yield accrual factor for CT)
uint256 bcIndex = IBCToken(ct).bcIndexCurrent();

// TWAP observations (array of secondsAgo offsets)
uint32[] memory secs = new uint32[](2);
secs[0] = 1800; // 30 min ago
secs[1] = 0;    // now
uint216[] memory cumRates = IPMarket(market).observe(secs);
```

### Previewing deposits and redeems

```solidity
// How many FW shares for a given USDC deposit
uint256 fwOut = IFiraWrappedStandardized(fw).previewDeposit(usdc, amount);

// How much USDC for redeeming a given amount of FW
uint256 usdcOut = IFiraWrappedStandardized(fw).previewRedeem(usdc, fwAmount);
```

### Checking expiry

```solidity
bool expired = IPMarket(market).isExpired();
uint256 expiryTs = IPMarket(market).expiry();
```

Post-expiry, BT redeems 1:1 for FW and CT stops accruing. LP positions should be exited before expiry for optimal value.

## Amount conventions

* **FW, BT, CT amounts** — Native token decimals (matching the underlying, e.g. 6 for USDC-backed FW).
* **Exchange rates, indices, proportions** — 1e18 fixed-point.
* **Signed integers (`int256`)** — Used for swap amounts. Negative = paying, positive = receiving.
* **Slippage** — Always the caller's responsibility via `minOut` / `minSharesOut` parameters. The contracts will revert if the minimum is not met.

## Pages

* [Interfaces & API Surface](https://docs.fira.money/developers/integrations/interfaces.md) — Complete reference of all Fira interfaces, grouped by module


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.fira.money/developers/integrations.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
