# FireBot — Full technical documentation

> Every FireBot contract on Polygon PoS (chain id 137): what it does, its address, and the functions the app calls against it. This mirrors the human docs at https://firebot.gg/docs. For a short overview see https://firebot.gg/llms.txt; for live metrics see https://firebot.gg/api (JSON).

The protocol is a small set of immutable contracts — no upgrade proxy, no admin path to mint FBX. Contracts fall into two groups: tokens (the ERC-20s users hold) and vaults & venues (the yield-bearing destinations).

## Tokens

| Symbol | Name | Decimals | Address |
| --- | --- | --- | --- |
| FBX | FireBot | 18 | `0xd125443f38a69d776177c2b9c041f462936f8218` |
| EP | Elemental Particles | 18 | `0x60ed6acef3a96f8cdaf0c0d207bbafa66e751af2` |
| USDT | Tether USD | 6 | `0xc2132d05d31c914a87c6611c10748aeb04b58e8f` |
| DCI | Dynamic Composite Index | 18 | `0xc91953E110EbB0039859304A0d1b64f8450763fC` |
| WSTETH | Wrapped Staked ETH | 18 | `0x03b54a6e9a984069379fae1a4fc4dbae93b3bccd` |
| WETH | Wrapped Ether | 18 | `0x7ceb23fd6bc0add59e62ac25578270cff1b9f619` |
| WBTC | Wrapped Bitcoin | 8 | `0x1bfd67037b42cf73acf2047067bd4f2c47d9bfd6` |
| WMATIC | Wrapped Matic / POL | 18 | `0x0d500B1d8E8eF31E21C99d1Db9A6444d3ADf1270` |

POL (the native gas token) has no ERC-20 address — balances are read via `eth_getBalance`.

## Vaults & venues

### FireVaultFBXV2 — Auto-FBX vault · fireFBX receipt

- Address: `0x960d43BE128585Ca45365CD74a7773B9d814dfBE`

Auto-compounding FBX vault. Users deposit FBX and receive fireFBX shares; the vault claims and reinvests rewards on every interaction. The share price (FBX per fireFBX) only moves up.

| Function | Type | Signature | Purpose |
| --- | --- | --- | --- |
| deposit | write | `deposit(uint256 amountFBX) returns (uint256 amountFireFBX)` | Deposit FBX, mint fireFBX shares pro-rata against the current rate. |
| withdraw | write | `withdraw(uint256 amountFireFBX) returns (uint256 amountFBX)` | Burn fireFBX shares, return the underlying FBX at the current rate. |
| claimRewardsAndBalance | write | `claimRewardsAndBalance()` | Force a compound — anyone can call to refresh the share price. |
| withdrawalRate | read | `withdrawalRate() returns (uint256)` | Current FBX-per-share rate, scaled by 1e18. Used to convert shares ↔ FBX. |
| totalFBXBalance | read | `totalFBXBalance() returns (uint256)` | Total FBX under management — vault TVL in token units. |

> Note: The contract itself is the fireFBX ERC-20: balanceOf(user) returns share balance.

### FireVaultEP — Auto-EP vault · fireEP receipt

- Address: `0xA2b205F8C0F0E30b3f73B7716a718C53cB8E5cC3`

Auto-compounding EP vault. Same shape as Auto-FBX, but the reward path mints new EP from the EP-staking emissions and reinvests it.

| Function | Type | Signature | Purpose |
| --- | --- | --- | --- |
| deposit | write | `deposit(uint256 amountEP) returns (uint256 amountFireEP)` | Deposit EP, mint fireEP shares at the current rate. |
| withdraw | write | `withdraw(uint256 amountFireEP) returns (uint256 amountEP)` | Burn fireEP shares, return the underlying EP. |
| claimAndMint | write | `claimAndMint()` | Force a compound — claims pending FBX, mints EP from it, restakes. |
| withdrawalRate | read | `withdrawalRate() returns (uint256)` | EP-per-share rate, scaled by 1e18. |
| getReserveEP / getReserveFBX | read | `getReserveEP() returns (uint256), getReserveFBX() returns (uint256)` | Vault-side accounting of EP staked and FBX held pre-mint. |

### FirePool — EP+FBX Fire Pool · also the swap router

- Address: `0xE20E046B230a5530438d32ABfBCC3E61d7670234`

Auto-compounding LP for the EP/FBX pair. The same contract is the protocol AMM — `swapExactEPForFBX` and `swapExactFBXForEP` use the pool reserves with a constant-product quote.

| Function | Type | Signature | Purpose |
| --- | --- | --- | --- |
| addLiquidity | write | `addLiquidity(uint256 amountInEP, uint256 amountInFBX, uint256 minFPT, uint256 deadline)` | Deposit a paired EP + FBX amount, receive FPT LP tokens. minFPT is your slippage floor. |
| removeLiquidity | write | `removeLiquidity(uint256 amountInFPT, uint256 minEP, uint256 minFBX, uint256 deadline)` | Burn FPT, withdraw your EP + FBX share of the reserves. |
| swapExactEPForFBX | write | `swapExactEPForFBX(uint256 amountInEP, uint256 minAmountOutFBX, uint256 deadline)` | Trade EP for FBX along the pool curve. Reverts if output < minAmountOutFBX. |
| swapExactFBXForEP | write | `swapExactFBXForEP(uint256 amountInFBX, uint256 minAmountOutEP, uint256 deadline)` | Trade FBX for EP along the pool curve. Reverts if output < minAmountOutEP. |
| claimRewards | write | `claimRewards()` | Force a compound on the LP rewards. |
| reserveEP / reserveFBX | read | `reserveEP() returns (uint256), reserveFBX() returns (uint256)` | The pool's tracked EP and FBX reserves — used to quote swaps off-chain. |
| poolRate | read | `poolRate() returns (uint256)` | EP-per-FBX (or inverse, depending on orientation), scaled by 1e18. |

### FUSDv2 — USDT → DCI vault · FUSD receipt

- Address: `0x3c56f017D9cE85350dF8f4B495033AAA15563A99`

Points-based stable-coin vault. Users mint FUSD against USDT 1:1; the contract accrues points over time per FUSD. DCI rewards are distributed pro-rata against totalPoints().

| Function | Type | Signature | Purpose |
| --- | --- | --- | --- |
| mint | write | `mint(uint256 amountUSDT)` | Deposit USDT, receive an equal amount of FUSD. Starts accruing points immediately. |
| redeem | write | `redeem(uint256 amountFUSD)` | Burn FUSD, withdraw the underlying USDT 1:1. |
| claim | write | `claim(address account)` | Claim accrued DCI rewards for an account (any caller can trigger). |
| claimCompoundRewards | write | `claimCompoundRewards(bool shouldAccrue)` | Bookkeeping helper used by the contract internals when accruing. |
| points | read | `points(address account) returns (uint256)` | Accrued points for an account. Drives the DCI claim share. |
| totalPoints | read | `totalPoints() returns (uint256)` | Denominator for the pro-rata DCI distribution. |

### ElementalParticles — EP token + EP→FBX staking

- Address: `0x60Ed6aCEF3a96F8CDaF0c0D207BbAfA66e751af2`

The EP ERC-20 with staking baked into the token contract. Stakers earn FBX from a daily emission set at the protocol level. Accrual caps at 30 days since the last claim — claim within that window to keep earning at the full rate.

| Function | Type | Signature | Purpose |
| --- | --- | --- | --- |
| stakeEP | write | `stakeEP(uint256 amountEP)` | Stake EP from the caller. Reward accrual starts on the next emission tick. |
| unstakeEP | write | `unstakeEP(uint256 amountEP)` | Withdraw staked EP. Pending FBX must be claimed separately. |
| claimRewards | write | `claimRewards() returns (uint256)` | Sweep accrued FBX rewards to the caller. |
| claimableRewards | read | `claimableRewards(address account) returns (uint256, uint256, uint256)` | Currently-claimable FBX for an account + bookkeeping fields. |
| userInfos | read | `userInfos(address account) returns (uint256, uint256, uint256)` | Per-user state: tuple[0] = staked EP, then internal accumulators. |

> Note: EP is the same token used as the staking surface — the EP balance returned by balanceOf is *unstaked* EP.

## Swap & liquidity

There is no separate router — the FirePool contract is also the EP/FBX AMM, via `swapExactEPForFBX` and `swapExactFBXForEP`. Quotes are constant-product against `reserveEP()` / `reserveFBX()`. Minting EP burns FBX, so EP/FBX trades push the FBX supply down over time. Both swap functions take a `minAmountOut` slippage floor and a unix-seconds `deadline`; the transaction reverts if either condition fails at execution time. The pool fee is fixed in the contract (no fee-tier parameter).

## Price references

Tokens with a Chainlink Data Feed on Polygon (ETH, BTC, MATIC/POL, wstETH) read `latestAnswer()`. FBX and DCI have no Chainlink feed, so they fall back to their Uniswap-V2 pair against USDT. EP has no direct USDT pair — it is priced through the Fire Pool FBX rate (`reserveFBX / reserveEP`) then through the FBX/USDT pair.

### Chainlink Data Feeds

| Feed | Address | Notes |
| --- | --- | --- |
| ETH / USD | `0xF9680D99D6C9589e2a93a78A04A279e509205945` | Chainlink AggregatorV3. latestAnswer() returns ETH/USD scaled by 1e8. |
| BTC / USD | `0xc907E116054Ad103354f2D350FD2514433D57F6f` | Chainlink AggregatorV3. latestAnswer() returns BTC/USD scaled by 1e8. |
| MATIC / USD (POL) | `0xAB594600376Ec9fD91F8e885dADF0CE036862dE0` | Chainlink AggregatorV3. POL is the rebranded MATIC, same token — this feed prices both. |
| wstETH / ETH | `0x10f964234cae09cB6a9854B56FF7D4F38Cda5E6a` | Chainlink ratio feed (1e18-scaled). Multiply by ETH/USD for the wstETH/USD price. |

### Uniswap-V2 fallback pools

| Pool | Address | Notes |
| --- | --- | --- |
| FBX / USDT pool | `0x1000bb854fbc6d98dc9d859d6cb47e22a31eb8f9` | Uniswap-V2 pair. FBX has no Chainlink feed — spot price = reserves(USDT) / reserves(FBX), decimal-adjusted. |
| DCI / USDT pool | `0xe7b7cf919e2798defc1f08133312cd151e5a5bed` | Uniswap-V2 pair. DCI has no Chainlink feed — same reserve-ratio formula gives DCI/USDT. |

## Contract ABIs

Machine-readable ABIs (JSON) are published under `/abi/`. Start with the manifest at https://firebot.gg/abi/index.json — it maps every deployed address to its ABI file. Raw ABIs: https://firebot.gg/abi/<name>.json (worldCupPool, firePool, epStaking, fbxVault, epVault, fusd, erc20, chainlinkFeed, univ2Pair). These cover the functions the app calls; token contracts also implement the full ERC-20 standard.