For the complete documentation index, see llms.txt. This page is also available as Markdown.

Agent Integration Spec

Why this matters

DeFi is moving toward autonomous agents — bots and AI systems that can read market state, reason about risk, and execute strategies without human intervention at every step. The KonaLooper contract on Abstract was designed to make that easy.

A single contract gives agents everything they need: market discovery, trade quoting, position inspection, and execution — all through standard eth_call reads and signed transactions. No proprietary APIs. No off-chain dependencies. No authentication layers. Just an EVM contract with a clean interface.

What agents can build with this

  • Yield optimization — Scan lending rates across markets, identify positive carry, and open same-asset yield loops that multiply supply APY while earning protocol rewards on both sides of the position.

  • Directional strategies — Go long WETH or PENGU against stablecoins, or short them, with leverage up to 4x. Agents can combine on-chain oracle reads with their own signal models.

  • Risk management — Monitor health factors across user positions, trigger leverageDown to reduce exposure before liquidation, or closeLeverage to exit entirely when conditions deteriorate.

  • Portfolio rebalancing — Adjust leverage targets dynamically as market conditions shift. Quote the cost of rebalancing before committing.

  • Position tracking — Index LeverageUp, LeverageDown, and FeeCollected events to reconstruct full position history, calculate realized PnL, and build dashboards — all from on-chain data.


Architecture at a glance

KonaLooper is a stateless flash loan orchestrator deployed on Abstract Mainnet (chain ID 2741). It does not custody funds. Here's the flow:

  1. User deposits collateral (e.g. 100 PENGU)

  2. KonaLooper takes a flash loan for the amplified amount

  3. Supplies total collateral to the Kona Lend pool

  4. Borrows against it (same asset for yield loops, or a different asset for directional trades)

  5. Repays the flash loan from borrow proceeds

All of this happens atomically in one transaction. After execution, the user's wallet holds the collateral and debt positions directly in the lending pool. The looper holds nothing.


Deployed contracts

Contract
Address

KonaLooper (ERC-1967 proxy — use for all calls)

0x09A4518945C9cD484B5eac3FACf4A5B0bdd3A5bc

KonaLooper implementation (verification only)

0x39fb6d7B5566d2F844863F2AaE1C7C74896e0B31

PunchSwap router (swap path, used internally)

0x441E0627Db5173Da098De86b734d136b27925250

Kona Lend pool

0x8f16B5713F412C5dE4951Aaf678Eb8409101f819

Price oracle

0xE4Cd99d4698482ff263C300fbe2fA5fFE08af1622

Supported assets

Symbol
Address
Decimals

WETH

0x3439153EB7AF838Ad19d56E1571FBD09333C2809

18

USDC

0x84A71ccD554Cc1b02749b35d22F684CC8ec987e1

6

USDT

0x0709F39376dEEe2A2dfC94A58EdEb2Eb9DF012bD

6

PENGU

0x9eBe3A824Ca958e4b3Da772D2065518F009CBa62

18

Markets are defined by (collateralAsset, debtAsset) pairs. Discover them dynamically via getAllMarkets() — never hardcode.


Reading on-chain state

Every agent interaction starts with reads. These are free eth_call operations that require no signing and no gas.

Discover markets

The MarketConfig struct contains: enabled, maxLeverageBps, minLeverageBps, swapPath[], reverseSwapPath[], slippageToleranceBps, feeBps.

Quote a trade

Always quote immediately before execution. Pool state changes between blocks.

Inspect positions

Important: healthFactor here is the user's account-wide health factor from the lending pool. If the user has multiple positions or manual supply/borrow activity, this number reflects all of it. For isolated position risk, compute from collateral value, debt value, and the reserve's liquidation threshold.

Check permissions


Executing trades

Open or increase leverage

Reduce leverage

Close entirely

Native ETH variants (leverageUpETH, leverageDownETH, closeLeverageETH) are available when WETH is the collateral.


Preflight checklist

Before submitting any leverageUp transaction, agents must verify:

  1. paused() is false — the contract has a global pause mechanism.

  2. Market is enabled — getMarketConfig(collateral, debt).enabled == true.

  3. Leverage is in range — minLeverageBps <= leverageBps <= maxLeverageBps.

  4. ERC20 approval — the collateral token must have approve(KonaLooper, collateralAmount) or higher.

  5. Credit delegation — the variable debt token for the debt reserve must have approveDelegation(KonaLooper, amount) where amount >= getRequiredDelegation(...).

  6. Quote is fresh — quoteLeverageUp returns current estimates; set minCollateralOut from this, not from a cached value.

First-time edge case: If the user has never supplied the collateral asset on Kona Lend before, the first loop may need a small initial supply to prime the reserve. Detect this by checking the user's kToken balance for that reserve.


Units and encoding

Field
Encoding

leverageBps, maxLeverageBps, etc.

Basis points where 10,000 = 1.0x. So 35000 = 3.5x leverage.

Token amounts (collateralAmount, etc.)

Raw integers in the token's smallest unit. USDC = 6 decimals, WETH/PENGU = 18. Never assume 18.

slippageToleranceBps, feeBps

Standard basis points divided by 10,000.

healthFactor

18-decimal fixed point from the lending pool. 1e18 = health factor of 1.0. Below this = liquidatable.


Events

Index these from the KonaLooper proxy address to build position history, analytics, or agent memory:

LeverageUp — Emitted when a position is opened or increased.

LeverageDown — Emitted when leverage is reduced.

MarketConfigSet — Market parameters changed.

FeeCollected — Protocol fee taken.

Additional events: MarketEnabled, MarketDisabled, Paused, Unpaused, Upgraded.

Standard eth_getLogs with topic filters is sufficient for a lightweight indexer.


Error handling

The contract uses custom errors. When a transaction reverts, decode the error selector against the ABI to get a specific reason rather than retrying blindly.

Error
Meaning

ContractPaused

Protocol is paused, try later

MarketIsDisabled / MarketNotConfigured

This market pair isn't active

LeverageTooHigh / LeverageTooLow / LeverageRange

Requested leverage outside allowed bounds

InsufficientCreditDelegation

User hasn't delegated enough borrow allowance (includes current vs required in error data)

InsufficientBalance / InsufficientCollateral

Not enough tokens

SlippageExceeded

Price moved beyond tolerance between quote and execution

HealthFactorTooLow

Resulting position would be immediately liquidatable

InvalidOraclePrice

Oracle returned zero or stale price for an asset

InvalidLeverage / InvalidFee / InvalidSwapPath

Malformed parameters


Agent capability tiers

Tier
What it does
Keys required

Observe

Read markets, quote trades, monitor positions and events

None

Compose

Build unsigned transaction calldata, compute approval steps, simulate outcomes

None

Execute

Sign and broadcast transactions, handle receipts, rebalance positions

Yes — with explicit user authorization

Agents should default to Observe. Only escalate when the user has explicitly granted signing authority. Always simulate or quote immediately before any write.


Full ABI

The complete KonaLooper ABI for the current deployment. Use this directly with viem, ethers, web3.py, or any ABI-compatible library.


Integration checklist

Use this before shipping any agent, bot, or automation against KonaLooper.


Getting started

The fastest path to a working agent:

  1. Point viem, ethers, or web3.py at Abstract RPC with the ABI above

  2. Call getAllMarkets() to see what's available

  3. Call quoteLeverageUp(...) with a test amount to understand the output shape

  4. Index LeverageUp events from the proxy to see real positions being opened

  5. Build from there

Everything is on-chain. No API keys, no rate limits, no accounts to create. Just a contract and a node.

Last updated