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

# Zappers

Combined liquidity and Trove actions, token approvals, manager permissions, and flash settlement.

A zapper contract combines related actions in one transaction. Hann Finance uses zappers to wrap collateral, open or adjust a Trove, add liquidity and stake LP tokens, and settle flash-assisted leverage changes. Token approvals and manager or operator permissions are separate from the combined action; the app requests missing permissions first.

| Task                    | Contract family                                 | What it combines                                                                              |
| ----------------------- | ----------------------------------------------- | --------------------------------------------------------------------------------------------- |
| Borrow against KAIA     | `WKAIAZapper`                                   | Wrap native KAIA, perform the Trove action, and unwrap payouts.                               |
| Borrow against HNKAIA   | `HNKAIAZapper`                                  | Transfer HNKAIA and perform the Trove action.                                                 |
| Borrow against earnUSDT | `EarnUSDTZapper`                                | Receive earnUSDT, wrap it as wEarnUSDT collateral, and perform the Trove action.              |
| Change leverage         | `LeverageWKAIAZapper`, `LeverageEarnUSDTZapper` | Borrow temporary liquidity, change collateral and USDHN debt, and settle the flash operation. |
| Deposit and stake LP    | `StableSwapZapper`                              | Add USDT and USDHN liquidity, then stake the new LP tokens.                                   |
| Unstake and withdraw LP | `StableSwapZapper`                              | Unstake LP tokens, burn them, and return both pool assets.                                    |

The app's mainnet configuration includes KAIA and earnUSDT leverage routes. Its testnet configuration also includes HNKAIA leverage. Mainnet HNKAIA borrowing is configured to use standard Trove actions.

## Approvals and signatures

ERC-20 approval gives a named contract permission to transfer a token from your wallet. Permit2 uses a signed authorization for that transfer. Review the token, amount, spender, and expiry shown by the wallet. If the token's allowance to Permit2 is insufficient, approve that allowance before the signature-based transfer.

The app chooses the authorization method for the wallet connection and action. For StableSwap and LP flows, browser-wallet connections use Permit2 signatures and the app's mobile connection mode uses ERC-20 approvals. KAIA supplied as native collateral travels with the transaction value and needs no ERC-20 collateral approval.

Two other permissions have distinct roles:

* **Trove manager permission** lets a zapper perform the selected position action. The app requests the correct manager setting before an adjustment or collateral-funded close when the current setting does not match.
* **RewardStaker operator permission** lets StableSwapZapper stake or unstake LP tokens on your behalf. Token approval alone does not grant this permission.

## Standard Trove actions

A Trove holds collateral and USDHN debt for one collateral branch. Standard zappers support opening, adding or withdrawing collateral, borrowing or repaying USDHN, and closing.

1. Choose the position action and enter the collateral or USDHN amount.
2. Review the resulting collateral, debt, annual interest rate, upfront fee, and collateral ratio.
3. Complete the token authorization and manager permission requested by the app.
4. Confirm the Trove transaction.
5. Check the updated position and the tokens returned to your wallet.

Opening requires the branch's collateral plus the KAIA gas-compensation deposit. For the KAIA branch, the transaction includes both the collateral amount and gas compensation; the zapper wraps them as required. For ERC-20 collateral branches, gas compensation is supplied separately as native KAIA. This deposit is separate from the network transaction fee, stays with the open Trove, and is returned on a successful owner close. Ordinary adjustments do not require a new opening deposit.

Closing with wallet-held USDHN repays the full live debt, including accrued interest, and returns the collateral. The KAIA standard zapper unwraps WKAIA payouts to KAIA; the earnUSDT standard zapper unwraps wEarnUSDT to earnUSDT.

## Flash-assisted leverage

A flash operation supplies temporary liquidity and settles it within the same transaction. The resulting Trove debt remains open after that transaction; the temporary flash obligation is fully settled.

| Operation                 | Collateral change                                     | USDHN debt change                               |
| ------------------------- | ----------------------------------------------------- | ----------------------------------------------- |
| Open or increase leverage | Add the requested collateral exposure.                | Borrow the USDHN required for settlement.       |
| Decrease leverage         | Use part of the position's collateral for settlement. | Repay USDHN with the temporary liquidity.       |
| Close using collateral    | Use collateral to fund the full repayment.            | Repay the entire live debt and close the Trove. |

The routes differ by collateral and action:

| Route                      | How it settles                                                                                                                                                                                    |
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| KAIA                       | The configured WKAIA/USDT V3 pool supplies the temporary collateral or USDT. The USDHN/USDT StableSwap leg funds the corresponding settlement or debt repayment.                                  |
| earnUSDT open or increase  | StableSwap sends USDT through an exact-output callback. SuperEarnRouter deposits it for earnUSDT, which is wrapped as wEarnUSDT and added to the Trove. Borrowed USDHN pays the StableSwap input. |
| earnUSDT decrease or close | The configured earnUSDT/USDT V3 pool supplies USDT. StableSwap converts it to USDHN for repayment, and unwrapped earnUSDT collateral settles the V3 operation.                                    |

These are branch-configured routes; the user does not provide an arbitrary router or output token.

During execution, the zapper hands the required Trove manager control to FlashSwapper and restores the prior managed state after settlement. Token balances that remain after settlement are returned to the configured receiver. The app uses the position owner's wallet as that receiver.

### Execution limits

Opening and leverage adjustments pass a final debt cap, `maxDebt`. If execution would leave more debt than this cap, the transaction reverts. The contracts also check the collateral change, flash pool and token, configured StableSwap pool, flash-fee cap, and manager/receiver state.

The collateral-funded close uses the current full debt and a separately configured close-fee cap. The app displays a `100%` slippage limit for this close flow, and its contract call carries no user-selected minimum received. The displayed net return is an estimate. Actual returned tokens depend on the executed settlement.

A failed combined transaction reverts its collateral, debt, and internal token movements. A token approval, operator approval, or manager-setting transaction confirmed beforehand remains in force, and the failed transaction still consumes network gas.

## Returned tokens and gas compensation

* Standard closing returns collateral after full USDHN repayment.
* Collateral-funded closing uses the collateral needed to settle the flash operation and returns the remaining collateral and route tokens. The KAIA zapper converts its returned WKAIA to KAIA; the earnUSDT route returns remaining earnUSDT after unwrapping its collateral.
* The gas-compensation deposit is released on closing and passed to the receiver through the branch's payout handling.
* The LP zapper returns any excess token0, token1, or LP balance produced by the current operation, measured against its starting balances.

These payouts follow the branch's token handling. A zapper does not offer conversion into any token a user chooses.

## Combined LP actions

On `/earn/usdt`, **Deposit and stake** sends both pool assets to StableSwapZapper. It calls the router's add-liquidity operation, checks `minLiquidity`, and stakes the new LP tokens through RewardStaker. **Unstake and withdraw** releases the staked LP tokens, removes liquidity, checks each token's minimum amount, and sends USDT and USDHN to your wallet.

Both combined actions check the deadline and the required RewardStaker operator permission. LP staking keeps exposure to the pool's assets. Trove automation keeps the branch's collateral-ratio and liquidation rules.

For the app steps, see [Swap, bridge, and liquidity](https://docs.hann.finance/protocol/stableswap-dex.md) and [Leverage positions](https://docs.hann.finance/protocol/loops.md). [Borrowing and liquidation](https://docs.hann.finance/protocol/borrowing-and-liquidation.md) explains the resulting Trove debt and collateral ratio.


---

# 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.hann.finance/protocol/zapper.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.
