# Zapper Guide

This page explains what a **Zapper** is (an automation contract), when it helps, and what risks to watch for when you use it.

{% hint style="info" %}
**Not investment advice** — Zapper flows can include stablecoin borrowing, leverage, and DEX swaps. These carry liquidation risk and potential loss.
{% endhint %}

## At a glance

* A Zapper bundles “approve → swap → CDP action → cleanup” into fewer user steps
* It pulls required tokens, executes the route, and returns leftovers to the receiver (in one transaction)
* Some flows can use **Permit2** (signature-based approvals) to reduce approval friction
* Some flows can use **DEX flash swaps** (temporary in-tx liquidity) to assist leverage routes

## One diagram: what a zapper does

{% @mermaid/diagram content="flowchart TD
U\[User wallet] -->|Approve or Permit2 signature| Z\[Zapper]
Z -->|CDP actions| C\[CDP core: BorrowerOperations / Trove Manager]
Z -->|Swaps: stable leg| S\[StableSwap]
Z -->|Swaps: action leg| D\[DEX router / wrappers]
Z -->|Return leftovers| U

```
style U fill:#B0BBF4,color:#333,stroke:#4C5FD5,stroke-width:2px
style Z fill:#EEFBA0,color:#333,stroke:#D1F24A,stroke-width:2px
style C fill:#4C5FD5,color:#fff,stroke:#3A49C5,stroke-width:2px
style S fill:#D1F24A,color:#333,stroke:#B8DA2C,stroke-width:2px
style D fill:#B0BBF4,color:#333,stroke:#4C5FD5,stroke-width:2px" %}
```

## Why use a zapper?

Zappers are most useful when a position change normally takes multiple steps:

* opening a Trove and swapping assets in the same flow
* adjusting debt/collateral while routing through StableSwap + DEX actions
* closing a position and converting collateral into a desired output token

{% columns %}
{% column width="50%" %}

#### Manual flow

* You call multiple contracts in sequence
* More approvals + more room for mistakes
* Harder to ensure leftover tokens get returned cleanly
  {% endcolumn %}

{% column width="50%" %}

#### Zapper flow

* One “intent” becomes a pre-built route
* Permit2 can reduce approvals (when supported)
* Leftovers sweep returns dust back to a receiver
  {% endcolumn %}
  {% endcolumns %}

## How it works (conceptually)

Zappers in Hann Finance are designed around a few recurring patterns:

* **Manager/receiver controls**: a Trove can enforce which “manager” and “receiver” are allowed to receive collateral during a route.
* **Stable phase + action phase**: routes can separate a stable-asset swap leg from a more general action leg.
* **Leftovers sweep**: the zapper snapshots balances and returns leftover tokens to the receiver (within a dust tolerance).
* **Budgets and invariants**: leverage routes typically enforce caps (e.g., flash fee caps, final debt caps) and “unexpected token” guards.

## Common zapper variants (by collateral)

{% columns %}
{% column width="33%" %}

#### WKAIA Zapper

* Wraps native KAIA into WKAIA when needed
* Can unwrap back to KAIA on withdrawal (depending on the flow)
  {% endcolumn %}

{% column width="33%" %}

#### HNKAIA Zapper

* Supports HNKAIA (wrapped Kaia LST exposure) collateral branches
* Leveraged variants can reduce intermediate swaps when the same token is used across steps
  {% endcolumn %}

{% column width="33%" %}

#### SuperEarn USDT Zapper

* Supports a collateral branch that uses a wrapper around a SuperEarn USDT receipt / yield token (if configured)
* Leverage routes can bundle wrapping/unwrapping and leftovers handling into one transaction
* Concept deep dive: [Yield-bearing stable receipt tokens](https://hann-finance.gitbook.io/hann-finance/resources/deep-dives/yield-bearing-stables)
  {% endcolumn %}
  {% endcolumns %}

## Common flows

{% tabs %}
{% tab title="Standard Trove actions" %}
Use this for actions like: open Trove, add collateral, repay debt, withdraw collateral, close Trove.

{% stepper %}
{% step %}

#### Step 1: Choose the action and receiver

Pick what you want to do and where outputs should go (your wallet, or a receiver address you control).
{% endstep %}

{% step %}

#### Step 2: Provide inputs

You provide the required input token(s) (collateral and/or USDHN). Depending on the flow, you may use an approval or a Permit2 signature.
{% endstep %}

{% step %}

#### Step 3: Zapper executes CDP calls

The zapper performs the necessary CDP calls (via BorrowerOperations) and may apply temporary manager/receiver settings for safety.
{% endstep %}

{% step %}

#### Step 4: Leftovers are returned

Any leftover tokens from swaps or rounding are returned to the receiver, and temporary permissions are restored.
{% endstep %}
{% endstepper %}
{% endtab %}

{% tab title="Leverage (flash-assisted) actions" %}
Use this for leverage up/down flows that require temporary liquidity and a multi-hop route.

{% stepper %}
{% step %}

#### Step 1: Provide initial collateral (+ gas compensation if required)

Some zapper variants collect a small gas-compensation amount in the native token as part of the transaction.
{% endstep %}

{% step %}

#### Step 2: Flash liquidity is borrowed

A FlashSwapper can obtain temporary liquidity via a DEX flash swap callback, execute the route, then settle it within the same transaction.
{% endstep %}

{% step %}

#### Step 3: Route execution (stable → action)

The route can run a **stable phase** (e.g., stable ↔ stable on StableSwap) and an **action phase** (DEX swaps, wrapping/unwrapping, ERC-4626 deposit/withdraw, etc.).
{% endstep %}

{% step %}

#### Step 4: Finalize the Trove update and repay

The zapper finalizes the Trove change and settles the flash step. If any stage fails safety checks (deadlines, output bounds, fee caps, or “unexpected token” guards), the transaction reverts.
{% endstep %}

{% step %}

#### Step 5: Restore permissions and return leftovers

Manager/receiver settings are restored and any leftover dust is swept back to the receiver.
{% endstep %}
{% endstepper %}

{% hint style="warning" %}
**\[TBD] Supported routes** — Available leverage routes and collateral types are surfaced in the UI. Start with small sizes and conservative limits.
{% endhint %}
{% endtab %}
{% endtabs %}

## Risks and safety notes

{% tabs %}
{% tab title="Liquidation risk" %}
Automation does not reduce liquidation risk. If your CR becomes unsafe due to price moves, interest accrual, or poor execution, your Trove can be liquidated.
{% endtab %}

{% tab title="Slippage and min-out" %}
Routes rely on min-out / max-in safeguards. If liquidity is thin or the market is stressed, your tx can revert — or execute with worse outcomes if your limits are too loose.
{% endtab %}

{% tab title="Approvals and Permit2" %}
Permit2 can reduce approvals, but it is still an authorization. Always review the token, amount, and expiration in the signature payload.
{% endtab %}

{% tab title="Smart-contract risk" %}
Zapper flows touch multiple contracts (CDP + routers + DEX + wrappers). Bugs, misconfiguration, or oracle issues can cause losses.
{% endtab %}
{% endtabs %}

{% hint style="danger" %}
**High leverage + thin liquidity is brittle** — start small and use conservative limits until you understand how routes behave in real market conditions.
{% endhint %}

## FAQ

### Will I get leftover tokens back?

Zapper flows use a “leftovers sweep” pattern: the contract tracks balances and returns leftover amounts to a receiver address, within a dust tolerance.

### Why can my zapper tx revert?

Common reasons include: deadline exceeded, output bounds not satisfied, flash fee cap exceeded, or an unexpected final token after a route.

## Next pages

* DEX basics: [StableSwap DEX](https://hann-finance.gitbook.io/hann-finance/protocol/stableswap-dex)
* Looping (leverage concept): [Loop Strategies](https://hann-finance.gitbook.io/hann-finance/protocol/loops)
* Liquidation mechanics: [Borrowing & Liquidation](https://hann-finance.gitbook.io/hann-finance/protocol/borrowing-and-liquidation)
* Redemption (peg defense): [Redemptions & Risk](https://hann-finance.gitbook.io/hann-finance/protocol/redemptions-and-risk)
* Terms: [Glossary](https://hann-finance.gitbook.io/hann-finance/overview/glossary)