> 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/id/developers/integrator-kit.md).

# Panduan integrasi

Pemilihan kontrak, transaksi dompet, dan pengindeksan integrasi Hann Finance

Pilih jaringan, gunakan alamat kontrak publik dan ABI terverifikasi, siapkan panggilan dompet, lalu indeks event. [Referensi Smart contract](/id/developers/smart-contracts.md) memuat alamat dan entrypoint.

## 1. Pilih jaringan, alamat, dan ABI

| Jaringan | Chain ID | Penggunaan                                     |
| -------- | -------- | ---------------------------------------------- |
| Kaia     | `8217`   | Mainnet; kontrak Hann Finance belum diterapkan |
| Kairos   | `1001`   | Testnet untuk pengujian integrasi              |

Pilih alamat dari [tabel kontrak](/id/developers/smart-contracts.md). Ambil ABI dari sumber terverifikasi explorer. Untuk proxy, gunakan alamat proxy dengan ABI implementasinya.

Simpan chain ID, alamat, dan ABI bersama. Baca alamat agunan tiap cabang CDP serta underlying, aToken, dan token utang reserve Lending melalui getter publik.

Sebelum meminta tanda tangan, pastikan RPC dan dompet memakai chain ID yang dipilih untuk alamat kontrak.

### Baca saldo USDHN

Masukkan alamat USDHN publik, chain ID, URL RPC, dan alamat dompet. Fungsi memeriksa jaringan RPC lalu mengembalikan saldo dalam satuan dasar.

```ts
import { createPublicClient, http, type Address } from "viem";

const balanceOfAbi = [
  {
    type: "function",
    name: "balanceOf",
    stateMutability: "view",
    inputs: [{ name: "account", type: "address" }],
    outputs: [{ name: "", type: "uint256" }],
  },
] as const;

export async function getUsdhnBalance({
  contractAddress,
  chainId,
  rpcUrl,
  walletAddress,
}: {
  contractAddress: Address;
  chainId: number;
  rpcUrl: string;
  walletAddress: Address;
}): Promise<bigint> {
  const client = createPublicClient({ transport: http(rpcUrl) });
  const rpcChainId = await client.getChainId();
  if (rpcChainId !== chainId) {
    throw new Error("RPC chain ID does not match the selected network");
  }
  return client.readContract({
    address: contractAddress,
    abi: balanceOfAbi,
    functionName: "balanceOf",
    args: [walletAddress],
  });
}
```

USDHN memakai 18 desimal. Pertahankan jumlah sebagai `bigint` dan tampilkan dengan `formatUnits(balance, 18)`. Aset lain memakai desimalnya sendiri. Satuan dasar KAIA native adalah 10⁻¹⁸ KAIA.

## 2. Tentukan operasi dan spender

| Operasi                       | Target                                  | Izin atau tanda tangan                                                         |
| ----------------------------- | --------------------------------------- | ------------------------------------------------------------------------------ |
| Pinjaman CDP                  | `BorrowerOperations` atau Zapper cabang | Allowance agunan; entrypoint Zapper menentukan Permit2                         |
| Penebusan CDP langsung        | `CollateralRegistry.redeemCollateral`   | Registry membakar USDHN langsung tanpa memakai allowance                       |
| Setoran Earn                  | `StabilityPool.provideToSP` cabang      | Pool terdaftar memindahkan USDHN lewat `sendToPool`; tanpa allowance ERC-20    |
| Suplai atau bayar Lending     | `Pool`                                  | Allowance token underlying ke Pool                                             |
| Suplai atau bayar KAIA native | `WKaiaGateway`                          | KAIA native dalam `msg.value`                                                  |
| Tarik KAIA native             | `WKaiaGateway.withdrawKAIA`             | Allowance aWKAIA ke gateway                                                    |
| Pinjam KAIA native            | `WKaiaGateway.borrowKAIA`               | `approveDelegation` token utang variabel ke gateway                            |
| Setor atau minta tarik bKAIA  | `LSTVault`                              | KAIA native untuk setoran; bagian milik sendiri untuk `requestUnstakeByShares` |
| Pertukaran atau LP            | StableSwap Router atau Zapper           | Allowance token input atau LP; Permit2 pada entrypoint terkait                 |

`approve` menetapkan allowance ERC-20. `permit` menetapkannya melalui tanda tangan memakai domain, nonce, spender, jumlah, dan deadline token. Permit2 memiliki izin token dan tanda tangan sesuai entrypoint. `approveDelegation` memberikan kewenangan meminjam.

Baca allowance atau delegasi yang ada dan minta jumlah yang diperlukan. Lanjutkan setelah persetujuan terkonfirmasi. Zapper menggabungkan operasi dan rute; izin sebelumnya tetap ada jika rute revert.

Panggilan langsung `BorrowerOperations` menyediakan parameter Trove dan pengelola. Zapper menambahkan wrap native, Permit2, dan rute. Posisi yang dibuka langsung memerlukan serah-terima pengelola yang benar sebelum memakai penutupan terkelola leverage.

## 3. Siapkan transaksi dari keadaan terkini

1. Baca posisi, pemilik, parameter cabang atau reserve, desimal, dan saldo.
2. Bentuk operasi dari ABI. Trove memerlukan petunjuk urutan dan batas biaya awal. Lending variabel memakai mode `2`.
3. Sertakan batas eksekusi: minimum output atau maksimum input StableSwap dan deadline, `maxDebt` Zapper, serta batas biaya awal.
4. Gunakan `simulateContract` dengan sender, argumen, dan value native yang tepat. Tampilkan perkiraan agunan, utang, output, biaya, serta kesehatan posisi sebelum tanda tangan. Simulasi memakai keadaan blok simulasi; eksekusi memakai blok transaksi.
5. Kirim lewat dompet dan periksa receipt. Revert mempertahankan keadaan protokol sebelumnya dan tetap memakai gas. Klaim batch bKAIA yang berhasil dapat mencakup kegagalan atau retry per tiket.
6. Perbarui keadaan kontrak terkait. Lacak konfirmasi receipt dan sinkronisasi indexer secara terpisah sampai saldo serta posisi baru tersedia.

Untuk CDP, gunakan `getLatestTroveData(troveId).entireDebt` dan `entireColl` bersama harga dan batas cabang. Untuk Lending, gunakan `getUserAccountData(walletAddress)` serta konfigurasi reserve termasuk agunan dan eMode. Tampilkan kondisi likuidasi tiap produk bersama posisi.

### Rute berbantuan flash

Zapper dan FlashSwapper berizin mengontrol add manager, remove manager, dan receiver selama eksekusi. Callback menyelesaikan swap, memperbarui Trove, membayar pool DEX, lalu memulihkan pengelolaan. Kuotasi memakai pool dan token terkonfigurasi. Kontrak memeriksa batas biaya flash serta utang akhir dan mengembalikan sisa rute.

`closeTroveByCollateral` menerima tuple `troveId` dan `profitReceiver`, menjual agunan untuk seluruh utang terkini dan mengembalikan sisa. ABI tidak memiliki `minOut` dari pengguna. Tampilkan hasil penjualan agunan dan aset kembali saat menyiapkan penutupan.

## 4. Indeks posisi dan hasil

| Subjek                  | Event dan pembacaan                                                                                                                       |
| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| Kepemilikan Trove       | `TroveNFT.Transfer` cabang; `ownerOf(troveId)`                                                                                            |
| Pencatatan Trove        | `TroveUpdated`, `TroveOperation`, `BatchedTroveUpdated`, `BatchUpdated`; `getLatestTroveData`, `getTroveStatus`                           |
| Likuidasi dan penebusan | `Liquidation`, `Redemption`, `RedemptionFeePaidToTrove` dari TroveManager                                                                 |
| Earn                    | `DepositUpdated`, `DepositOperation`; getter setoran terkini, hasil agunan, dan USDHN                                                     |
| Lending                 | `Supply`, `Withdraw`, `Borrow`, `Repay`, `LiquidationCall`, `ReserveDataUpdated`; pembacaan reserve dan akun                              |
| StableSwap              | `Swap`, `Mint`, `Burn` pool; `LiquidityAdded`, `LiquidityRemoved`, dan refund router                                                      |
| bKAIA                   | `Deposit`, `RequestedBatch`, `Requested`, `UnstakeShortfall`, `TicketStatusUpdated`, `ClaimPayout`, `ClaimManySummary`, serta event retry |

Identifikasi log dengan chain ID, hash blok, hash transaksi, dan indeks log. Simpan kontrak pengirim serta cabang bersama Trove ID. Ikuti transfer NFT dan event utang agar kepemilikan portofolio diperbarui. Tangani blok yang dihapus atau diganti sebelum menerapkan proyeksi baru.

Event mencatat operasi pada bloknya; bunga dan harga terus berubah. Gabungkan riwayat event dan pembacaan terkini untuk saldo serta kesehatan posisi. Gunakan status tiket dan event pembayaran bKAIA untuk klaim individu. `claimMany` mengembalikan `processed`, `totalPaid`, dan `totalFee`; periksa juga pembayaran tiap tiket.

## Transfer lintas chain

Gunakan alamat publik, ABI terverifikasi, dan kuotasi penyedia bridge. Cocokkan chain asal/tujuan, token, penerima, jumlah, biaya, dan spender sebelum tanda tangan. Kirim instruksi asal beserta izin, lalu lacak konfirmasi asal dan pengiriman tujuan terpisah.

USDHN lintas chain memakai `USDHNOFTAdapter` atau `USDHNOFT` remote beserta ABI, peer, dan biaya yang sesuai. OFT `send` tersedia melalui antarmuka lintas chain tersebut; `USDHNToken` menyediakan antarmuka ERC-20.


---

# 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/id/developers/integrator-kit.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.