For the reporting, we differentiate to sets of endpoints:

1. those that are independent from a user action, and that should be fetched and cached on your backend
2. those that need to be fetched when there is a user interaction

I - Data that should be cached on your backend

These queries give you all the data needed to display product information user can deposit to. They do not need to be done at every user interaction. Instead doing it once every day or few hours is fine.

Step 1: Fetch your deployments

Deployments are the Kiln products that have been deployed for you, querying them through this api enables you to pilote which one you want to add / enable / disable from your integrator dashboard.

🩷

GET /v1/deployments

{
  "data": [
    {
      "id": "9c4520b7-838c-4feb-aefa-679a498af845",
      "product_type": "defi",
      "name": "ETH Dedicated Staking",
      "display_name": "Dedicated Staking",
      "description": "A Dedicated Staking deployment that earns ETH rewards",
      "chain": "eth",
      "chain_id": 1,
      "address": "0x81Ca2c97f491b13c1EAFeF1ae2cF72DDD1fCBFB6",
      "status": "active",
      "asset_icon": "https://example.com/icon.png",
      "protocol_icon": "https://example.com/icon.png",
      "product_fee": "0.01"
    }
  ]
}

Enabled deployments have an "active" status, the others should be filtered out.

Step 2: Fetch your product data

Now that we have the enabled deployments list, we can query their product information using the chain_id and address of the deployment.

🩷

GET /v1/products?chain_ids=1,2,3&asset_symbols=USDC,USDT&address=0xaaa

{
    "data": [
        {
            "id": "1_0xBE3bA8440aC60302D8C31E4FD3beB392990CC6af", // chainid_address
            "asset_address": "0x3E481C53e88a90d66c8eAF2CFE4E406BA4925d93",
            "asset_symbol": "USDC",
            "asset_decimals": 6,
            "asset_price_usd": 0.9999,
            "share_symbol": "skUSDC",
            "tvl": 1000000,
            "protocol": "aave_v3",
            "protocol_display_name": "AAVE V3 USDC",
            "protocol_icon": "https://public.kiln.fi/...",
            "protocol_tvl": 10000000,
            "protocol_supply_limit": 200000,
            "grr": 6.543,
            "nrr": 5.456,
            "address": "0xBE3bA8440aC60302D8C31E4FD3beB392990CC6af",
            "chain_id": 1,
            "deposit_rate": 0.8,
            "updated_at_block": 21767847
        }
    ]
}

Step 3: Fetch assets metadata

We can now fetch the asset information metadata for each of these products.

🩷

GET /v1/assets?addresses=0xeeeee&chain_ids=1,2&symbols=USDC

{
    "data": [
        {
            "id": "1_0x719EE46276410809cA5F85D41DAc506c24232905", // chainid_address
            "name": "USDC",
            "icon_url": "https://public.kiln.fi/...",
            "price_usd": 0.999,
          	"decimals": 6,
            "updated_at": 1738609264
        }
    ]
}

II - Data that is queried per user, from UI action

These queries must be done when a user accesses this earn section of your platform, so that you have the latest balances to display.

It should be refreshed after a Deposit as well to display the latest balances and positions changes to the user.

Step 1: Fetch user positions

Fetch all the positions of the user: ERC20 balances, ETH balances, Product (defi, pooling etc.) balances, accross all supported EVMs.

🩷

GET /v1/positions?chain_ids=1,2,3&wallet=0x719EE46276410809cA5F85D41DAc506c24232905&type=

{
    "data": {
        "summary": {
            "total_usd": 123123,
            "product_total_usd": 21234,
            "assets_total_usd": 22222,
            "total_earned_usd": 1111
        },
        "positions": [
            {
                "type": "ERC20", // can be "ETH" | "ERC20" | "PRODUCT"
                "balance": "1231",
                "decimals": 6,
                "chain_id": 1,
                "icon": "https://public.kiln.fi/...",
                "details": { // if type is ERC20
                    "asset_address": "0xC0B17458d50F2EAaD3cF9C880EcfE1545fbd8192",
                    "asset_symbol": "USDC",
                    "asset_price_usd": 0.999
                }
            },
            {
                "type": "PRODUCT", // can be "ETH" | "ERC20" | "PRODUCT"
                "balance": "1231",
                "decimals": 6,
                "chain_id": 1,
                "icon": "https://public.kiln.fi/...",
                "details": { // if type is PRODUCT
                    "product": "DEFI",
                    "product_address": "0x6A8Ed703b37FAF3e0a37E084F2341D93604fC03E",
                    "total_rewards": 12313,
                    "total_deposited_amount": 111111,
                    "total_withdrawn_amount": 22,
                    "nrr": 10.234,
                    "grr": 9.923,
                    "additional_rewards": [
                        // each element is an ERC20 position
                    ]
                }
            }
        ]
    }
}

Step 2: Fetch assets metadata

If needed, fetch the metadata for the ERC20 assets fetched from the position.

🩷

GET /v1/assets?addresses=1_0xeeeee

{
    "data": [
        {
            "id": "1_0x719EE46276410809cA5F85D41DAc506c24232905", // chainid_address
            "name": "USDC",
            "icon_url": "https://public.kiln.fi/...",
            "price_usd": 0.999,
         		"decimals": 6,
            "updated_at": 1738609264
        }
    ]
}