Search…
Ethereum
How to programmatically delegate and retrieve rewards for delegated wallets on Ethereum.

Delegation flow

At a high-level, the flow for staking Ethereum involves:
  1. 1.
    Generating a validation key. Our API described below provides an endpoint to do so.
  2. 2.
    Funding this validator with a 32 ETH deposit. This is an example of such a transaction.
  3. 3.
    Monitoring validator performance and accrued rewards. Our dashboard provides such reporting, and the data can also be retrieved via API.
Kiln's React Components library provides an example implementation of this flow.
1
import { EthStakingWidget } from "@kilnfi/react-components";
2
import "@kilnfi/react-components/dist/cjs/index.css";
3
​
4
const App = () => {
5
const config: Config = {
6
apiUrl: '...', // KILN API URL
7
apiKey: '...', // KILN API TOKEN
8
accountId: '...', // KILN ACCOUNT ID
9
network: 'goerli', // goerli | mainnet
10
chainId: 5, // network chain id
11
};
12
13
const provider = '' // A JsonRpcProvider (see: https://docs.ethers.io/v5/api/providers/jsonrpc-provider/)
14
const account = '...' // connected wallet address
15
16
return (
17
<EthStakingWidget
18
config={config}
19
provider={provider}
20
account={account}
21
>
22
<EthStakingWidget.Header />
23
<EthStakingWidget.SelectAmount />
24
<EthStakingWidget.RewardsForecast />
25
<EthStakingWidget.Status />
26
</EthStakingWidget>
27
)
28
}
Copied!

Reporting API

Ethereum stake API object

Ethereum Stake is an API object linked to an Account and represents a validation key (ie a 32ETH stake).
Field
Value
Format
pubkey
Validation public key
String
state
Current deployment state
State (see State machine)
state_updated_at
Last state update date
iso
balance
Validator balance (in gwei)
String (Bigint)
rewards
Validator accrued rewards (in gwei)
String (BigInt)
apy
APY of accrued rewards
Number
effective_balance
Validator effective balance
String (Bigint)
deposit_tx_sender
Staker Ethereum Address
String

State machine

This state machine represents all the state an Ethereum object can be in. Transitions are performed automatically by Kiln services.
State
Description
UPLOADED
Validator key is uploaded and waiting for deployment
ETH1_DEPOSIT_IN_PROGRESS
Deposit transaction is made but not yet in a finalized block
ETH1_DEPOSITED
32 ETH deposit is complete on Ethereum mainnet chain
DEPLOYMENT_REVIEW
Validator configuration is under review to avoid errors or slashing risks
WAITING_FOR_DEPOSIT
Deployed and waiting for the Beacon Chain to process the deposit
PENDING
Validator is waiting in activation queue to start validation (~2 days)
ACTIVE
Validator is participating to the network
INACTIVE
Validator is offline
SLASHED
Validator has been slashed for bad behavior
TO_BE_DELETED
User wants to stop a validator
DELETION_REVIEW
Validator deletion is under review
DELETING
Validator is exiting and being deleted
DELETED
Validator has exit and been deleted

Ethereum network stats API object

This object represents stats about the Ethereum network.
Field
Value
Format
apy
Current network staking APY
Number
supply_staked_percent
Current percentage of tokens staked on the network
Number

Ethereum API routes

The following routes are available in the Kiln API:
post
https://api.kiln.fi/v1
/eth/keys
Create a new Ethereum Stake (validation key)
get
https://api.kiln.fi/v1
/eth/stakes
Retrieve Ethereum Stakes, for an Account, a Wallet or a Pubkey
get
https://api.kiln.fi/v1
/eth/network-stats
Retrieve Ethereum Network Statistics