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.

All Fira contracts are deployed on Ethereum mainnet. See Deployment for addresses.

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.

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.

Common patterns

Reading prices and rates

// 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

// 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

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 — Complete reference of all Fira interfaces, grouped by module