# Integrator Guide

This page is a practical checklist for integrating Hann Finance into a wallet, dApp, or backend service.

{% hint style="warning" %}
**No addresses here** — Contract addresses must be sourced from official address sources. Do not copy addresses from third parties.
{% endhint %}

## At a glance

* Decide what you integrate: **Trove UI**, **USDHN**, **Earn**, **StableSwap**, or **Zappers**.
* Use a reliable source of truth for addresses (deployment files / registry).
* Indexing Troves usually requires tracking **Trove ownership (NFT)** and position state.
* If you integrate zapper-based leverage, account for **DEX flash swaps** and the **manager/receiver** state machine.
* For the full contract surface map (no addresses): [Smart Contracts](https://hann-finance.gitbook.io/hann-finance/developers/smart-contracts).
* For Trove lifecycle + statuses (including “zombie”): [Trove Manager (State Machine)](https://hann-finance.gitbook.io/hann-finance/developers/trove-manager).

## What you can integrate

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

#### User-facing features

* Open/adjust/close Troves
* Mint/repay USDHN
* Deposit/withdraw Earn
* Swap / LP on StableSwap
* One-click flows via Zappers
  {% endcolumn %}

{% column width="50%" %}

#### Infra / analytics

* Index Trove ownership and health
* Track USDHN supply and peg indicators
* Monitor liquidation/redemption events
* Track StableSwap pool liquidity and swaps
  {% endcolumn %}
  {% endcolumns %}

## Where to get contract addresses

Preferred sources (in order):

1. **Official address bundle** published by the team
2. **On-chain registry contracts** (if exposed)
3. **Verified explorer pages** linked from official channels

{% hint style="warning" %}
**\[TBD] Publish address bundle** — Add links or a page that lists the canonical address sources for each chain.
{% endhint %}

## Integration checklist

{% stepper %}
{% step %}

#### Step 1: Resolve addresses and ABIs

You need:

* core protocol contract addresses
* USDHN token address
* Earn / Stability Pool addresses (per collateral branch)
* StableSwap router/pool addresses (if you integrate swaps)
* Zapper addresses (if you integrate one-click)

{% hint style="warning" %}
ABIs must match deployed bytecode. Do not assume testnet ABIs are identical to mainnet.
{% endhint %}
{% endstep %}

{% step %}

#### Step 2: Pick your interaction surface

* **Direct core calls:** best for full control; more UI work.
* **Zapper calls:** best UX; more composability and routing considerations.

User doc reference: [Zapper Guide](https://hann-finance.gitbook.io/hann-finance/protocol/zapper)
{% endstep %}

{% step %}

#### Step 3: Index the state you need

Common indexer needs:

* Trove creation and ownership changes (NFT transfers)
* Collateral and debt changes per Trove
* Liquidation and redemption events
* Earn deposit/withdraw events
  {% endstep %}

{% step %}

#### Step 4: Add safety rails

* display CR and liquidation risk clearly
* default to conservative slippage and deadlines
* warn users about depegs, liquidations, and smart contract risks
  {% endstep %}
  {% endstepper %}

## Flash + swap components (conceptual)

If you integrate the automation stack, the key moving parts to understand are:

* **Manager/receiver controls**: leverage entrypoints typically require a strict manager state, then temporarily hand over inside flash callbacks, then restore.
* **FlashSwapper**: uses DEX flash swaps (callback-based) so leverage routes can source temporary liquidity and settle it within one transaction.
* **StableSwap pools**: stable-to-stable legs (USDHN and other stable assets).
* **External DEX venues**: spot swaps / wraps / un-wraps for non-stable steps (when configured).
* **Leftovers sweep**: snapshot-based refunds so user tokens aren’t trapped after execution.

{% hint style="info" %}
Component and function names can differ by implementation. Rely on deployed ABIs for exact names.
{% endhint %}

## Minimal example (TypeScript pseudocode)

```ts
// Pseudocode only. Replace with official addresses + ABIs.
const addresses = {
  usdhn: "0x...",       // [TBD]
  borrowerOps: "0x...", // [TBD]
  troveNft: "0x...",    // [TBD]
};

async function getUsdhnBalance(user: string) {
  const usdhn = new ethers.Contract(addresses.usdhn, USDHN_ABI, provider);
  return await usdhn.balanceOf(user);
}
```

{% hint style="warning" %}
**\[TBD] ABI and schema package** — Publish a stable ABI package or a versioned JSON schema so integrators can pin to a release.
{% endhint %}

## Next reads

* Architecture: [Technical Overview](https://hann-finance.gitbook.io/hann-finance/developers/technical-overview)
* Risk framing: [Risk Disclosure](https://hann-finance.gitbook.io/hann-finance/risks/risk-disclosure)