Kiln Connect offers a unified interface to craft, sign and broadcast transactions for all supported protocols so that you don't need to deal with protocols specifics and focuses on integration and user experience.

Kiln Connect in video

Send your first Kiln Connect API request

Every call to a Kiln API must include an API secret key. After you generate your first API Access for your organization, you will have access to one API Key for the corresponding environment, mainnet or testnet. Please note that you need dashboard access to start generating API Keys, if it's not already the case get in touch with our support team.

🔑

Access your API Key

Use Kiln Dashboard to create, edit, delete, and roll API keys.

• To access your API keys, in the application section of the dashboard, to see the step by step process please follow this user guide.

1. Before you begin

This guide walks you through a simple interaction with the Kiln Connect API for any staking workflow:

• getting staking yield,
• and getting reporting on a staking position for a wallet

For a better understanding of Kiln Connect API and get the core-concepts, take a tour of the API Overview or visit the API reference. If you’re ready to use staking, see our following point.

2. Send your first API request

The following flow presents the commun API endpoint that you can query on each network that Kiln Connect API supports, for this guide, we will present the flow for Ethereum Staking, you can apply the same logic on each network just by changing the selected network in the path.

Get important information about a network

Let's start by getting useful information about the network you are staking on, it's also a good opportunity to validate your API credentials.

1️⃣

/v1/eth/network-stats

From the API reference, you just need to paste your API key in the AUTHORIZATION input to try out this API call.

{
  "data": {
    "network_gross_apy": 3.5804178951752808,
    "supply_staked_percent": 27.208318358321915,
    "updated_at": "2024-06-11T06:18:14Z",
    "estimated_entry_time_seconds": 202560,
    "estimated_exit_time_seconds": 1776,
    "estimated_withdrawal_time_seconds": 765091.5,
    "eth_price_usd": 3664.2363734455
  }
}

Calling this endpoint we can see useful information about the selected network, here we can see that 27% of the total ETH supply is staked and that the annual gross percentage yield is 3.5%.

Get information about a staking position

Kiln Connect API is quite unique for accessing staking reporting data, you can access any staking position called stakes from any validators on the network.

Let's try to get information on this wallet 0x538d72dEd42A76A30f730292Da939e0577f22F57 staking position.

2️⃣

/v1/eth/stakes

From the API reference, you just need to past your API key in the AUTHORIZATION input and select the wallets to try out this API call.

{
  "data": [
    {
      "validator_address": "0x80086ce4f5dd45c3a51543dc85b32cebd767dbae32dde3f71a0af34a5f6bbc5b00a8e0bbef3039bf19b40112ee964474",
      "validator_index": 982316,
      "state": "active_ongoing",
      "activated_at": "2023-10-22T03:15:35Z",
      "activated_epoch": 237293,
      "delegated_block": 18398698,
      "delegated_at": "2023-10-21T12:31:23Z",
      "effective_balance": "32000000000000000000",
      "balance": "32014092594000000000",
      "consensus_rewards": "637641819000000000",
      "execution_rewards": "145367858679601670",
      "rewards": "783009677679601670",
      "gross_apy": 3.8136687,
      "deposit_tx_sender": "0x538d72dEd42A76A30f730292Da939e0577f22F57",
      "execution_fee_recipient": "0x0077732907bFC6208933Cfd2a51aFB8f33cA5958",
      "withdrawal_credentials": "01000000000000000000000088a4df73aac310484c60c4c0ac4904cab938c20b",
      "is_kiln": false,
      "activation_eligibility_epoch": 237281,
      "activation_eligibility_at": "2023-10-22T01:58:47Z",
      "updated_at": "2024-06-12T07:31:18Z",
      "estimated_next_skimming_slot": 9294285,
      "estimated_next_skimming_at": "2024-06-14T08:57:23Z"
    },
    {
      "validator_address": "0x800fdd6144c35252e42b7929344f56b7d8c1576c33507cc881aadd48695656172b9a86f9ddb1e88a2036f2d7d21b783d",
      "validator_index": 227487,
      "state": "withdrawal_done",
      "activated_at": "2021-09-05T16:03:35Z",
      "activated_epoch": 62588,
      "delegated_block": 13138403,
      "delegated_at": "2021-09-01T07:23:35Z",
      "exited_at": "2023-09-26T14:40:23Z",
      "exited_epoch": 231550,
      "effective_balance": "0",
      "balance": "0",
      "consensus_rewards": "2658531834000000000",
      "execution_rewards": "245340279790865029",
      "rewards": "2903872113790865029",
      "gross_apy": 3.2773063,
      "deposit_tx_sender": "0x538d72dEd42A76A30f730292Da939e0577f22F57",
      "execution_fee_recipient": "0x0077732907bFC6208933Cfd2a51aFB8f33cA5958",
      "withdrawal_credentials": "01000000000000000000000088a4df73aac310484c60c4c0ac4904cab938c20b",
      "is_kiln": false,
      "activation_eligibility_epoch": 61730,
      "activation_eligibility_at": "2021-09-01T20:32:23Z",
      "updated_at": "2024-06-12T07:31:18Z"
    },
  ],
  "pagination": {
    "current_page": 1,
    "page_size": 25,
    "total_pages": 1,
    "total_entries": 1
  }
}

Each object in the data array of stakes, each representing a position earning rewards, for ETH we consider each 32ETH validator as one position:

• You can track the exact status of your validator, in this case we can see that one position is active_ongoing and a previous position withdrawal_done already withdrawn. You can use the filters to get exactly what you are looking for
• The rewards each position generated
  • Total in rewards, or the breakdown by consensus_rewards and execution_rewards
• The gross APY of the position computed from generated rewards
• And much more, you can find all the details in the API Reference in the description of each field

3️⃣

/v1/eth/rewards

From the API reference, you just need to past your API key in the AUTHORIZATION input and select the wallets and use the start_date filter starting 2 day ago, try out this API call.

{
  "data": [
    {
      "date": "2024-06-09",
      "consensus_rewards": "3739186739000000000",
      "execution_rewards": "667343982970335218",
      "rewards": "4406530721970335218",
      "stake_balance": "51424000000000000000000",
      "gross_apy": 1.7543452,
      "cl_apy": 1.4886596,
      "el_apy": 0.2656856
    },
    {
      "date": "2024-06-10",
      "consensus_rewards": "3855485522000000000",
      "execution_rewards": "1127313612257033791",
      "rewards": "4982799134257033791",
      "stake_balance": "51392000000000000000000",
      "gross_apy": 1.9837714,
      "cl_apy": 1.534961,
      "el_apy": 0.4488105
    }
  ]
}

Using this route, you will get the rewards generated by all positions from the selected wallet. We extract the total amount staked at a given date, and how many rewards were this day. You can find the gross APY each day, on Ethereum it's lower than what we have seen calling the network-stats endpoints, it's normal since EL rewards account for the majority of the yield, and will make the APY jump on a specific day.