Overview

The Kiln API provides a comprehensive set of endpoints for interacting with various blockchain networks. The API follows one common route structure that you can apply on each network. In this document, we will present the key concepts of Kiln Connect API and some examples of usage.

Glossary

Please note that this is a generic glossary, since each network is unique, you might find some specificities for each blockchains they will be explained in the API reference on each fields or API endpoints.

Stakes

Stake: A deposit of funds or tokens into a blockchain network to participate in the consensus mechanism and earn rewards.
Validator: A node or entity responsible for validating transactions and maintaining the blockchain network.
Validator Index: A unique identifier assigned to a validator by Kiln that can be used to query other endpoints and get specific information about a validator, it serve the same purpose as doing query with the validator address.
Activated Epoch/Block: The epoch or block number when a stake was activated and started participating in the consensus process.
Delegated At: The timestamp when a stake was delegated to a validator.
Exited At/Epoch: The timestamp or epoch when a stake was exited or stopped participating in the consensus process.
Deposit Transaction Sender: The wallet address that initiated the deposit transaction for the stake.
Execution Fee Recipient: The wallet address that receives the execution fees associated with the stake, m
Withdrawal Credentials: A unique identifier used to verify the ownership of a stake during the withdrawal process.
Effective Balance: The amount of funds or tokens actively participating in the consensus process for a given stake.
Balance: The total amount of funds or tokens associated with a stake, including rewards.
Consensus Rewards: The rewards earned by a stake for participating in the consensus process.
Execution Rewards: The rewards earned by a stake for executing transactions on the network.
Rewards: The total rewards earned by a stake, including consensus and execution rewards.
Claimable Rewards: The portion of rewards that can be claimed or withdrawn by the stake owner.
Gross APY: The raw annual percentage yield earned on-chain by a stake, including rewards and compounding effects. On /stakes or /rewards it's computed from the rewards received so it's normal that it's not exactly the network interest rate.
Net APY: The Net annual percentage yield earned by a stake, Gross - tx fees - validator_fees (- any other onchain fees).
Kiln Stake: A flag indicating whether a stake is operated by Kiln's Validators.
Skimming Slot/At: The slot or timestamp when rewards are expected to be skimmed or collected from a stake.

Rewards

Rewards earned by a stake you can get the total rewards on each stakes, and use the /rewards for a daily historical breakdown.

Operations

Operation: An on-chain transaction or event related to a stake, such as a deposit, withdrawal, or reward distribution.
Operation Type: The specific type of operation, such as a deposit, consensus withdrawal, execution reward, share minting, share burning, delegator restaking, delegator unstaking, or delegator claiming rewards.

Network Stats

Network Statistics: Aggregate data and metrics related to the overall state of a blockchain network, such as the total number of validators, total stake, or other relevant metrics, this endpoint is unique for each blockchain.

Excel Reports

Reports: Comprehensive documents or files containing detailed information about stakes and rewards, typically in a spreadsheet or tabular format.

Accounts and Wallets

Account: Accounts are like folders in which you can organize your stakes or clients' stakes. An account can contain stakes on multiple protocols. It's useful to retrieve an account asset portfolio.
Wallet: A cryptocurrency wallet address used to interact with the blockchain network and manage funds or tokens, generally used to get information about the stakes related to this wallet.

Route Structure

The routes are structured based on the blockchain network and the type of operation being performed. Each route follows a specific pattern:

/v{version}/{blockchain}/{operation}

For example:

/v1/eth/stakes - List Ethereum stakes
/v1/xtz/rewards - List Tezos rewards
/v1/matic/transaction/unstake-claim-tokens - Generate a transaction to withdraw unbounded tokens on Polygon

Core Endpoints on each blockchains

On Kiln Connect API, all network that we support offer the following routes, covering all repporting and transaction crafting needs.

Stakes: Endpoints related to staking operations, such as listing stakes, linking stakes to a Kiln account, and generating staking transactions.
Rewards: Endpoints for retrieving historical rewards earned from staking operations, typically broken down by day or cycle.
Operations: Endpoints that provide information about on-chain operations related to stakes, such as transactions and their status.
Network Stats: Endpoints that expose network-level statistics for various blockchains.
Transactions: Endpoints for generating, preparing, broadcasting, and checking the status of transactions related to staking operations, such as unstaking, claiming tokens, and withdrawing rewards.

Then each blockchain can offer additional capabilities, they are better detailed in the API reference.

Usefull Query Parameters

The API supports various query parameters to filter and customize the data returned by the endpoints. Some common query parameters include:

wallets: Filter by specific deposit wallet addresses, note that you can pass multiple wallets if needed
- delegators: Same usage as wallet but on Cosmos based chains, to stick with the ecosystem logic.
start_date and end_date: Generally used on rewards to filter data within a specific date range.
filter_states: Generally used on /stakes it's really convenient to filter only the positions with a given status.
include_usd: Include USD-denominated values in the response.
page_size and page: Pagination parameters for controlling the number of results returned.

Example usage:

GET /v1/eth/rewards?wallets=0x538d72dEd42A76A30f730292Da939e0577f22F57&start_date=2023-01-01&end_date=2023-01-31&include_usd=true

This request retrieves Ethereum rewards for the specified wallet address between January 1, 2023, and January 31, 2023, and includes USD-denominated values in the response.