# 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](https://docs.fira.money/developers/deployment) 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) — Complete reference of all Fira interfaces, grouped by module


---

# Agent Instructions: 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:

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

The question should be specific, self-contained, and written in natural language.
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.