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
leverageDownto reduce exposure before liquidation, orcloseLeverageto 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, andFeeCollectedevents 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:
User deposits collateral (e.g. 100 PENGU)
KonaLooper takes a flash loan for the amplified amount
Supplies total collateral to the Kona Lend pool
Borrows against it (same asset for yield loops, or a different asset for directional trades)
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
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
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:
paused()is false — the contract has a global pause mechanism.Market is enabled —
getMarketConfig(collateral, debt).enabled == true.Leverage is in range —
minLeverageBps <= leverageBps <= maxLeverageBps.ERC20 approval — the collateral token must have
approve(KonaLooper, collateralAmount)or higher.Credit delegation — the variable debt token for the debt reserve must have
approveDelegation(KonaLooper, amount)where amount >=getRequiredDelegation(...).Quote is fresh —
quoteLeverageUpreturns current estimates; setminCollateralOutfrom 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
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.
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
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:
Point viem, ethers, or web3.py at Abstract RPC with the ABI above
Call
getAllMarkets()to see what's availableCall
quoteLeverageUp(...)with a test amount to understand the output shapeIndex
LeverageUpevents from the proxy to see real positions being openedBuild from there
Everything is on-chain. No API keys, no rate limits, no accounts to create. Just a contract and a node.
Last updated