> 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

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](/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](/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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.