Enable your users to earn yield by supplying stablecoins into DeFi lending protocols. This guide walks you through the full integration flow: from vault display in app to deposit and withdrawal via smart contracts or API.

1. Setup

Get your API credentials

1. Log into your Kiln dashboard (testnet org)
2. Generate your API token
   → See API Keys Guide

Access test deployments

We offer ready-to-use vault deployments on mainnets, the following vaults are only compatible with Kiln Testnet API. All Vaults are following the 4626 Kiln DeFi ABI.

⚠️

Test-Only Vaults

Some L2 networks do not yet have stable DeFi testnets. For those, we provide staging vaults on mainnet. These are intended strictly for development and QA — do not use in production.

🏗

Moving to Production?

We'll deploy dedicated vaults based on your selected strategies, chain, and asset. Contact us to get started.

2. Reporting

This section covers how to query vault information for display in your frontend or monitoring dashboards.

2.1 - 🔍 Listing vaults

❇️

API - GET /v1/deployments

• retrieve all vault contracts deployed for your organization.

curl --location 'https://api.testnet.kiln.fi/v1/deployments' \
--header 'Authorization: Bearer kiln_testnet-api-key'

Returned information:

• Deployment metadata: off-chain metadata that are linked to a smart contract deployment for your organization including the product_type, display_name, description and a status.

{
    "data": [       
        {
            "id": "9ea40bbc-5fd9-44c9-a280-3e2b91e2331e",
            "organization_id": "73be1249-bd64-466a-84e4-44b53ab54660",
            "product_type": "defi",
            "name": "Morpho Steakhouse USDC",
            "display_name": "Steakhouse USDC",
            "description": "The Steakhouse USDC vault aims to optimize yields by lending USDT against blue chip crypto and real world asset (RWA) collateral markets, depending on market conditions.",
            "chain": "base",
            "chain_id": 8453,
            "address": "0x390d077f8e60ffb58805420edc635670aa4f34c3",
            "status": "active",
            "external_links": {
                "deposit_url": null
            }
        }
    ]
}

Recommended usage

• Filter by product_type === "defi" to isolate Kiln DeFi vaults
• Use:
  • display_name for user-friendly labeling
  • description for frontend tooltips or onboarding UI
  • status to dynamically include/exclude vaults (between active and deposit_paused)

Example: Skip paused vaults in deposit flow

if (vault.status !== 'deposit_paused') {
  showVaultInDepositUI(vault)
} else {
  showVaultInReportingOnly(vault)
}

This way, vaults can still be shown in reporting views (for existing positions), but not offered to new depositors.

💡Tip: Using the /deployments endpoint lets you update display names, metadata, or visibility without code changes — perfect for operational flexibility.

2.2 - 🦺 Security best practices

In production environments, we recommend maintaining your own trusted registry of verified production vaults to ensure that users are only interacting with trusted contracts. Alternatively, implementing transaction simulations, ERC-4626 transaction decoding, or other forms of address verification can help prevent users from engaging with malicious or unauthorized vaults.

const vaultRegistry: Record<chainId, string[]> = {  
  1: ['0x...vaultAddress1', '0x...vaultAddress2'],  
  42161: ['0x...vaultAddress3'],  
}

2.3 - 💸 Fetch vault information (APY, Assets, Icons)

❇️

API - GET /v1/defi/network-stats?vault_ids=<vaultId1,vaultId2,...>

• Query using ?vault_ids parameter to specify the vaults you want to query on
  • 💡 Using your internal registry or the /deployments describe above, you can construct the vault_id that is essentially the chainId and address. For example with the morpho vaults described previously, I can get the vault data fetching the following endpoint with it's vaultId 8453_0x390d077f8e60ffb58805420edc635670aa4f34c3.

curl --location 'https://api.testnet.kiln.fi/v1/defi/network-stats?vault_ids=8453_0x390d077f8e60ffb58805420edc635670aa4f34c3' \
--header 'Authorization: Bearer kiln_testnetapikey'

Returned information:

• Vault info: asset that needs to be deposited and the share_symbol representing the yield bearing position of the user.
• Vault APYs: grr (gross rewards rate), nrr (net) after commissions, additional rewards NRR and breakdown.
• Protocol info: protocol_display_name, icons, tvl, supply limit.
• when the data was last refreshed: updated_at_block

{
    "data": [
        {
            "vault_id": "8453_0x390D077f8E60ffb58805420edc635670AA4f34C3",
            "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
            "asset_icon": "https://public.kiln.fi/icons/assets/usdc.svg",
            "asset_symbol": "USDC",
            "asset_decimals": 6,
            "asset_price_usd": 0.999858,
            "share_symbol": "mshUSDC",
            "vault": "0x390D077f8E60ffb58805420edc635670AA4f34C3",
            "tvl": "60114376",
            "protocol": "morpho",
            "protocol_display_name": "Morpho",
            "protocol_icon": "https://public.kiln.fi/icons/defi-protocols/morpho.svg",
            "protocol_tvl": "3879708066054",
            "protocol_supply_limit": "1000041120291933943",
            "grr": 7.510284900665283,
            "nrr": 6.383742332458496,
            "chain": "base",
            "chain_id": 8453,
            "updated_at_block": 28744460,
            "additional_rewards_nrr": 1.0255916118621826,
            "additional_rewards": [
                {
                    "asset_symbol": "MORPHO",
                    "asset_decimals": 18,
                    "asset": "0xBAa5CC21fd487B8Fcc2F632f3F4E8D37262a0842",
                    "nrr": 1.0255916118621826
                }
            ]
        }
    ]
}

💡Tip: You can cache this data so that you can reuse it later to map it to a stake (use position) or use it at different place in your UI.

Integration example

[VIEW] As a User, I can see the vaults and their information available on the chain I am connected on, so I can assess which DeFi protocol I want to be exposed to

Integration tips	Integration example
1️⃣ Focus the experience on enabling yield on a specific asset rather in some case even abstracting away the underlying DeFi protocol, show the users how much they could be generating as rewards.
2️⃣ By default show the best NRR (Net rewards rate) to your users in the selection screen, you can include additional_rewards_nrrtonrr to display the total NRR to the user. 3️⃣ Use the protocol_icons to make the UI more attractive and display to the user some information on how he is generating this yield.
4️⃣ You might want to display the current APY breakdown but also some transparency on the product fees. You can get the fees by doing round([grr-nrr]/grr _ 100) = round(7.5 - 6.4) / 7.5 _100) = 15% Alternatively it's fine to display everything using the NRR and never mention any service fees.

2.4 - 💰 Get user positions

❇️

API - GET /v1/defi/stakes?wallets=&vault_ids=

• Query using ?vault_ids parameter to specify the vaults you want to query stakes on
  • 💡use the mapping you have to query the vault list on the network you want
• Query using ?wallets parameter to get the user(s) stakes in the scope of the vault list you specify

curl --location 'https://api.testnet.kiln.fi/v1/defi/stakes?wallets=0x991c468AbcE2b4DD627a6210C145373EbABdd186&vault_ids=8453_0x390d077f8e60ffb58805420edc635670aa4f34c3' \
--header 'Authorization: Bearer kiln_testnetapikey'

Returned information:

• Position: current_balance in vault asset, so if the user deposited USDC this balance is showing the user position in USDC.
• Vault APYs: grr (gross rewards rate), nrr (net) after commissions, additional rewards NRR and breakdown.
• Protocol info: protocol_display_name, icons, tvl, supply limit.
• when the data was last refreshed: updated_at_block

{
    "data": [
        {
            "vault_id": "8453_0x390D077f8E60ffb58805420edc635670AA4f34C3",
            "current_balance": "10093264",
            "shares_balance": "10010933",
            "total_rewards": "82264",
            "current_rewards": "82264",
            "total_deposited_amount": "10011000",
            "total_withdrawn_amount": "0",
            "vault": "0x390D077f8E60ffb58805420edc635670AA4f34C3",
            "owner": "0x991c468AbcE2b4DD627a6210C145373EbABdd186",
            "chain": "base",
            "chain_id": 8453,
            "updated_at_block": 28752441
        }
    ]
}

💡Tip: You link stakes to related network-stats via the vault_id that is unique, this way you can display the nrr or additional rewards of a user position.

Integration example

[VIEW] As a User, I see my positions and rewards, so that I can assess my performance.

Integration tips	Integration example
1️⃣ You can completely abstract away the fact that there is a yield bearing token that represent the user position and show the user position in the underlying asset. In this case we decide to display the current_balance in USDC yet still show the shares_balance the user hold in his wallet. 💡Tips: All amounts are in the min unit of the asset, you will get this information from the /network-stats under asset_decimals you can display the balance in USDC by doing current_balance 1e-asset_decimals = 10093264 1e-6 = 10,093264 USDC. The shares have the same number of decimals. 2️⃣ total_rewards represents the rewards generated in the underlying asset so here USDC.
3️⃣ You might want to display the current APY of the product so that the user can know when it's time to rebalance to a more interesting yield sources or keep this investment. All information concerning the APY is known under nnr in our API and can be found in the /network-stats.

2.5 - 🕔 Get operation history (Optional)

❇️

API - GET /v1/defi/operations?wallets=&vault_ids=

• Query using ?vault_ids parameter to specify the vaults you want the transaction history
• Query using ?wallets parameter history on this vault for a specific user(s)
  • 💡Tip: you can also search all the operations of a wallet without linking it to a vault to get the full transaction history of a user.

curl --location 'https://api.testnet.kiln.fi/v1/defi/operations?wallets=0x991c468AbcE2b4DD627a6210C145373EbABdd186&vault_ids=8453_0x390d077f8e60ffb58805420edc635670aa4f34c3' \
--header 'Authorization: Bearer kiln_testnetapikey'

Returned information:

• Operations: the type of the operation: withdrawal or deposit, the amount of assets and shares involved in the operation, the vault it is made on, the owner of the stake, the transaction sender, the vault the operation is made on

{
    "data": [
        {
            "vault_id": "8453_0x390D077f8E60ffb58805420edc635670AA4f34C3",
            "type": "deposit",
            "assets": "10000000",
            "shares": "10000000",
            "sender": "0x991c468AbcE2b4DD627a6210C145373EbABdd186",
            "timestamp": "2025-02-07T11:17:05.000+00:00",
            "tx_hash": "0x8fd368221abe3c76743760a42028a26d636c8ac6f68a208a8c14409f0e6901dd",
            "vault": "0x390D077f8E60ffb58805420edc635670AA4f34C3",
            "owner": "0x991c468AbcE2b4DD627a6210C145373EbABdd186",
            "chain": "base",
            "chain_id": 8453
        }
    ]
}

3. Vaults interactions (Deposit / Withdraw)

Now that we have access to all the reporting data, we can start interacting with the vaults. In this section we will cover how you can perform a deposit and a withdraw via direct contract calls or via API. We will also present additional tips to make the user experience better.

3.1 - ↗️ Deposit transaction

1 - Check allowance & token approval

Before depositing X assets, you must make sure the user approved the vault to spend X on its behalf on the asset contract. You can perform this leveraging Kiln API to check the allowance and craft the transaction.

❇️

API - POST /v1/defi/transaction/approve

• Passing in the call body the wallet, assets, chainId, amount.
• By default we check if the wallet is able to perform the transaction, if want to bypass theses checks set the skip_gas_estimation to true.
• If the selected amount is already approved by the user the response will be 204 "The amount is already approved" and you can move the the next step.

curl --location 'https://api.testnet.kiln.fi/v1/defi/transaction/approve' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer kiln_testnetapikey' \
--data '{
    "wallet": "0x991c468AbcE2b4DD627a6210C145373EbABdd186",
    "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "amount": "3000000",
    "chain_id": 8453,
    "vault": "0x390D077f8E60ffb58805420edc635670AA4f34C3",
    "skip_gas_estimation": false 
}

{
    "data": {
        "wallet": "0x991c468AbcE2b4DD627a6210C145373EbABdd186",
        "to": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
        "data": "0x095ea7b3000000000000000000000000390d077f8e60ffb58805420edc635670aa4f34c300000000000000000000000000000000000000000000000000000000002dc6c0",
        "value": "0",
        "nonce": 10,
        "gas_limit": "112480",
        "chain_id": 8453
    }
}

Alternatively you can craft the transactions on your own and check the allowance before the token approval.

To check the allowance, call the allowance(address owner, address spender)(uint256) function on the ERC20 asset contract with the vault address as the spender, if there is not enough allowance, you must make the user perform an approve

⛓️

TX - function: approve(address spender, uint256 amount)

• to: asset contract address
• from: user wallet address
• value: 0
• parameters:
  • spender: vault address
  • amount: amount the user inputed in asset wei (ie amount * decimals)

💡Tip: don't hesitate to use Kiln Widget on testnet and inspect the transaction crafted and ABI to replicate it in your application.

2 - Deposit transaction

Now that there is enough allowance, we can make the user deposit to the vault. You can craft and broadcast the deposit transaction on this vault.

❇️

API - POST /v1/defi/transaction/deposit

• Passing in the call body the wallet, assets, chainId, amount and vault.
• By default we check if the wallet is able to perform the transaction, including if the token approval is done if want to bypass theses checks set the skip_gas_estimation to true.
  • 💡If you are a smart wallet batching transaction you will need to set this to true so that you can generate the deposit call data before having performed the approve contract call.

curl --location 'https://api.testnet.kiln.fi/v1/defi/transaction/deposit' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer kiln_testnetapikey' \
--data '{
    "wallet": "0x991c468AbcE2b4DD627a6210C145373EbABdd186",
    "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "amount": "30000000",
    "chain_id": 8453,
    "vault": "0x390D077f8E60ffb58805420edc635670AA4f34C3",
    "skip_gas_estimation": false 
}
'

{
    "data": {
        "wallet": "0x991c468AbcE2b4DD627a6210C145373EbABdd186",
        "to": "0x390D077f8E60ffb58805420edc635670AA4f34C3",
        "data": "0x6e553f650000000000000000000000000000000000000000000000000000000001c9c380000000000000000000000000991c468abce2b4dd627a6210c145373ebabdd186",
        "value": "0",
        "nonce": 10,
        "gas_limit": null,
        "chain_id": 8453
    }
}

Alternatively you can craft the transactions on your own and interact with the vault directly following the 4626 deposit function.

⛓️

TX - function: deposit(uint256 assets, address receiver)

• to: vault address
• from: user wallet address
• value: 0
• parameters:
  • assets: amount the user inputed in asset expressed in the lowest unit of the token (ie asset_amount * 10**decimal).
  • receiver: user wallet address (or another if you want to let the user input a receiver wallet)

💡Tip: You can implement Kiln Vaults ABI, all vaults are following the 4626 standard, this way you can standardize your integration across all DeFi Lending protocols.

Now the user successfully deposited, received vault shares and can now receive supply rewards as frequently as the protocol distributes them!

Integration example

Integration tips	Integration example
1️⃣ Don't hesitate to display the vault metadata in the deposit flow, but also additional information like when are the rewards distributed, where is the yield coming from and the withdraw modality. For Kiln DeFi, users can withdraw anytime will instantly get their deposit assets (eg USDC) + rewards back!
2️⃣ You can compute the amount of shares the user will receive and get the vaults shares symbol from "3.3 Fetch vault information". As they are not pegged 1:1 with the deposited assets, it can be useful to help the user understand what he is doing. 💡 You can preview this amount by doing a view call on the vault and calling previewDeposit(uint256 assets) where assets is the amount of ERC20 to deposit in assets expressed in the lowest unit of the token (ie asset_amount * 10**decimal). ⚠️ If this call reverts, it can mean that the underlying protocol is not accepting supply funds at the moment, you can then display a "Deposits on this protocol are unavailable at the moment, retry later". 3️⃣ You can also display a preview of the deposit flow.
4️⃣ At the end of the deposit flow, you can redirect the user to the reporting view where he will see generated rewards and position value.

3.2 - ↙️ Withdraw flow

3.2.1 - Partial withdraw

In the 4626 Vaults standards, users can decide to withdraw an amount in assets (eg. USDC) or shares (eg. mshUSDC). A partial withdraw will happen if the user decide for example to without 25% of his 100 USDC position, and will ask to withdraw 25 USDC.

You can craft the withdraw transaction from Kiln connect API.

❇️

API - POST /v1/defi/transaction/withdraw

• Passing in the call body the wallet, assets, chainId, amount and vault.
• By default we check if the wallet is able to perform the transaction, including if you have enough funds to withdraw, you can bypass this by setting skip_gas_estimation to true.

curl --location 'https://api.testnet.kiln.fi/v1/defi/transaction/withdraw' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer kiln_testnetapikey' \
--data '{
    "wallet": "0x991c468AbcE2b4DD627a6210C145373EbABdd186",
    "amount": "3000000",
    "chain_id": 8453,
    "vault": "0x390D077f8E60ffb58805420edc635670AA4f34C3",
    "skip_gas_estimation": false 
}'

{
    "data": {
        "wallet": "0x991c468AbcE2b4DD627a6210C145373EbABdd186",
        "to": "0x390D077f8E60ffb58805420edc635670AA4f34C3",
        "data": "0xb460af9400000000000000000000000000000000000000000000000000000000002dc6c0000000000000000000000000991c468abce2b4dd627a6210c145373ebabdd186000000000000000000000000991c468abce2b4dd627a6210c145373ebabdd186",
        "value": "0",
        "nonce": 10,
        "gas_limit": "2092772",
        "chain_id": 8453
    }
}

Alternatively you can craft the withdraw transaction on your own as withdraw function is following the 4626 standard.

⛓️

TX - function: withdraw(uint256 assets, address receiver, address owner)

• to: vault address
• from: user wallet address
• value: 0
• parameters:
  • assets: amount the user inputed in asset expressed in the lowest unit of the token (ie asset_amount * 10**decimal).
  • receiver: user wallet address (or another if you want to let the user input a receiver wallet)
  • owner: user wallet address

3.2.2 - Complete withdraw

This case is made to avoid leaving dust in the user wallet, as there is time between the user input and the actual moment the transaction is executed, shares rate might have changed. If you specify the amount in asset it will ensure you withdraw this amount but it's possible that it don't convert all your shares.

This case is easily manageable via Kiln API by using the same withdraw endpoint yet by passing "max" in amount.

❇️

API - POST /v1/defi/transaction/withdraw

• Passing in the call body the wallet, assets, chainId, amount and vault.
  • When amount is set to the string value "max", this endpoint will craft a redeem transaction with the shares_balance of this user, making him withdraw everything.
  • 💡Tip: You can preview this amount by doing a view call on the vault calling previewRedeem(uint256 shares) and passing the shares_balance of the user from the /stakes.
• By default we check if the wallet is able to perform the transaction, including if you have enough funds to withdraw, you can bypass this by setting skip_gas_estimation to true.

curl --location 'https://api.testnet.kiln.fi/v1/defi/transaction/withdraw' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer kiln_testnetapikey' \
--data '{
    "wallet": "0x991c468AbcE2b4DD627a6210C145373EbABdd186",
    "amount": "max",
    "chain_id": 8453,
    "vault": "0x390D077f8E60ffb58805420edc635670AA4f34C3",
    "skip_gas_estimation": false 
}'

{
    "data": {
        "wallet": "0x991c468AbcE2b4DD627a6210C145373EbABdd186",
        "to": "0x390D077f8E60ffb58805420edc635670AA4f34C3",
        "data": "0xba087652000000000000000000000000000000000000000000000000000000000098c135000000000000000000000000991c468abce2b4dd627a6210c145373ebabdd186000000000000000000000000991c468abce2b4dd627a6210c145373ebabdd186",
        "value": "0",
        "nonce": 10,
        "gas_limit": "1880986",
        "chain_id": 8453
    }
}

Alternatively you can craft the redeem transaction on your own:

⛓️

TX - function: redeem(uint256 shares, address receiver, address owner)

• to: vault address
• from: user wallet address
• value: 0
• parameters:
  • shares: amount in shares, you MUST get this value by calling balanceOf(address owner) on the vault where owner is the user wallet address. Alternatively you can use the shares_balance from Kiln's /stakes.
  • receiver: user wallet address (or another if you want to let the user input a receiver wallet)
  • owner: user wallet address

Integration example

Integration tips	Integration example
1️⃣ The UI can be a simple input, with a showcase of how much can be withdrawn in underlying assets. You can completely abstract away the shares amount. You will get the current_balance from the /stakes endpoint. 💡Tip: All amounts are in the min unit of the asset, you will get this information from the /network-stats under asset_decimals you can display the balance in USDC by doing current_balance 1e-asset_decimals = 10093264 1e-6 = 10,09 USDC. The shares have the same number of decimals. 2️⃣ It can help to always show the $ amount to the user, indeed here we see that the conversion rate is not 1<>1, this will generally be the case. Some users can get lost, showing the amount in the local currency help showcase that the user is not loosing money in the process.
3️⃣ You can show to the user how many USDC he will receive and even show the conversion rate. 💡 Tip: You can preview this amount by doing a view call on the vault calling previewWithdraw(uint256 assets) where assets is the amount of ERC20 to deposit in assets expressed in the lowest unit of the token (ie asset_amount * 10**decimal). If this call reverts, it can mean that the underlying protocol is not accepting withdraw of supply funds at the moment, you can then display a "Withdrawals on this protocol are unavailable at the moment, retry later".
4️⃣ In the case the user want to do a full withdraw, we recommend adding a MAX button that is locking the amount to withdraw. This is required as a redeem(uint256 shares, address receiver, address owner) is necessary to not leave the user with dust in his wallet and have the reporting page show 0.00001 USDC still generating rewards.

🎉

Congratulations!

You now have a solid understanding of ERC-4626 and how to seamlessly integrate Kiln DeFi into your application. You're all set to bring DeFi lending to your users!

Now that the testnet integration is done we just need to switch you to the mainnet API and deploy your selected vaults 🙏

4. Checklist & next steps

Now let's validate that the implementation works properly. We recommend creating a test suite from this list and running it frequently, and especially during each release.

• 💸 As a User, I should be able to see all available vaults on the chain I am connected on
• 💸 As a User, I should be able to see each vault NRR, its asset, and the protocol it relies on
• 💸 As a User, I should be able to select a vault to deposit on based on the asset on my wallet
• 💸 / ↗️ As a User, I should be able to see the amount of shares and the name I will receive when inputing a number of asset to deposit
• ↗️ As a User with no allowance on the asset to the vault, I should sign an approve transaction with the amount to deposit as amount
  • on explorer, transaction must be valid with the specs above (from, to, value, param values etc)
• ↗️ As a User with enough allowance on the asset to the vault, I should not be asked to sign an approval transaction
• ↗️ As a User, I should be able to deposit my assets on the vault.
  • on explorer, transaction must be valid with the specs above (from, to, value, param values etc)
• 💰 As a User, I should be able to see my positions in all of your vaults with the amount in assets and fiat value and my rewards amount
• ↙️ As a User, I should be able to select a vault to withdraw on based on my positions
• ↙️ As a User, I should be able to preview the withdrawal of my positions, by seeing the asset I will receive on my wallet, when inputing the value to withdraw
• ↙️ As a User who wants to withdraw part of its positions, I should be able to sign a withdraw transaction
  • on explorer, transaction must be valid with the specs above (from, to, value, param values etc)
• ↙️ As a User who wants to withdraw 100% of its positions, I should be able to sign a redeem transaction
  • on explorer, transaction must be valid with the specs above (from, to, value, param values etc)

🎉

Congratulations!

You now have a solid understanding of ERC-4626 and how to integrate Kiln DeFi into your application. You're all set to bring DeFi lending to your users!