The Stakekit API takes into account all the metadata needed to create a complete user-facing staking interface. The StakeKit Dapp (https://dapp.stakek.it) is an example of an app built exclusively using our API and utilizes the StakeKit widget (source: https://github.com/stakekit/widget).

Yield Interface

interface YieldDto {
  /** The yieldID */
  id: string;
  /** The Token associated with the Yield */
  token: TokenDto;
  /** Arguments that needs to be passed to while performing enter / exit actions */
  args: ActionArgumentResponseDto;
  /** The current status of the yield. If it is possible to enter or exit */
  status: YieldStatusResponseDto;
  /** The reward rate of the yield once the balance is fully staked */
  apy: number;
  /** Metadata that contains everything needed to build a UI around staking */
  metadata: YieldMetadataDto;
  /** Validators with metadata that can be delegated t */
  validators: ValidatorDto[];
}

Properties

`id: string;`

The YieldID is one of the most important properties of the YieldDto interface. This is the ID that lets our system know which yield to interact with, whether it be fetching balances, staking, unstaking, or performing other Pending Actions. See API Reference for more details.

`token: TokenDto;`

This is the token the end user will use to stake.

export interface TokenDto {
	/** Name of the token */
  name: string;
	/** Network, Example: ethereum, arbitrum, cosmos */
  network: Networks
	/** The token ticker, example: ETH, ATOM, MATIC  */
  symbol: string;
	/** The decimal places used in the token  */	
  decimals: number;
	/** The token address, not required in case of native token such as ETH, ATOM, etc  */	
  address?: string;
	/** Used to fetch token prices  */	
  coinGeckoId?: string;
	/** The token logo, usually hosted on the StakeKit CDN (assets.stakek.it)  */	
  logoURI?: string;
}

`apy: number;`

Calling the yields endpoint will result in the receipt of metadata. APY information can be found at the top of the metadata for a given yield.

Example:

...
{  
  "apy": 0.06846711791246461,  
  "args": {  
    "enter": {  
      "addresses": {  
        "address": {  
          "required": true,  
          "network": "solana"  
        },
        ...

Use the yield endpoint to return that given yield's metadata which includes the estimated average rewards, as well as the estimated rewards for each available validator (where applicable).

Use APY (takes compounding interest into account) when:

"rewardClaiming": "auto", in the metadata

Use APR (doesn’t take compounding into account) when:

"rewardClaiming": "manual",in the metadata

Example:

....{ 
	"id": "solana-sol-native-multivalidator-staking",  
  "logoURI": "https://assets.stakek.it/tokens/sol.svg",  
    "name": "SOL Native Multivalidator Staking",  
    "revshare": {  
      "enabled": true  
    },  
    "rewardClaiming": "auto",  
    "rewardSchedule": "block",  
    "supportsMultipleValidators": true,  
    "supportsLedgerWalletApi": true,  
    "token": {  
      "name": "Solana",  
      "network": "solana",  
      "symbol": "SOL",  
      "decimals": 9,  
      "coinGeckoId": "solana",  
      "logoURI": "<https://assets.stakek.it/tokens/sol.svg">  
    },
      ....

Validator APR

On native staking yields, the actual end user rewards are dependent on which validator they delegate to. The actual rewards vary from validator to validator, due to validators charging different fee amounts. In order to be able provide the end user with accurate information, each yield includes accurate APR information for each available validator. This is found in the validators section of the metadata and does not apply to other types of yield outside of native staking.

Example of Validator Information:

"validators": [  
    {  
      "address": "cosmosvaloper1gpx52r9h3zeul45amvcy2pysgvcwddxrgx6cnv",  
      "name": "StakeLab",  
      "image": "https://assets.stakek.it/validators/stakelab.png",  
      "website": "https://stakelab.fr/?utm_campaign=StakingRewards",  
      "apr": 0.22546636480688323,  
      "commission": 0.05,  
      "stakedBalance": "1470610.108582",  
      "votingPower": 0.005987999542896,  
      "preferred": true  
    },  
    {  
      "address": "cosmosvaloper15urq2dtp9qce4fyc85m6upwm9xul3049e02707",  
      "name": "Chorus One",  
      "image": "https://assets.stakek.it/validators/chorus_one.png",  
      "website": "https://chorus.one",  
      "apr": 0.2125652407665867,  
      "commission": 0.075,  
      "stakedBalance": "3821829.725411",  
      "votingPower": 0.0155616464998011,  
      "preferred": true  
    },
  ...

`metadata: YieldMetadataDto;`

export interface YieldMetadataDto {
	/** Name of the yield. Example: Cosmos Native Staking  */	
  name: string;
	/** Logo URI in svg format */	
  logoURI: string;
  /** High-level description about the yield */	
  description: string;
  /** Link to the StakeKit documentation for this yield */	
  documentation: string;
  /** Information about the yield provider (empty in case of validator staking) */	
  provider?: YieldProviderDto;
  /** The token in which the transaction fees will be paid */	
  gasFeeToken: TokenDto;
  /** List of tokens in which rewards or yield are received */	
  rewardTokens?: TokenDto[];
  /** Type of the yield. Can be staking, liquid-staking, lending, or vault */	
  type: YieldType;
  /** Can be block, hour, day, week, month */	
  rewardSchedule: RewardSchedule;
  /** { days\* - number } */	
  cooldownPeriod?: TimePeriodDto;
  /** { days\* - number } */	
  warmupPeriod: TimePeriodDto;
  /** { days\* - number } */	
  withdrawPeriod?: TimePeriodDto;
  /** Either auto or manual */	
  rewardClaiming: RewardClaiming;
}

Optional parameters (only apply to certain yields)

Depending on the type of yield and exceptions, some parameters might not be included in the yield's metadata.

`provider`

Yields for which there is an external provider (such as DeFi protocols like Aave and foundations distributing tokens to "stakers" such as the ApeCoin Foundation) will have the provider param in its metadata.

Most native staking yields do not have this parameter included, while all yields sourced through DeFi protocols do.

Morpho-Aave Example:

  "provider": {
    "id": "morpho-aave",
    "name": "Morpho Aave",
    "externalLink": "https://www.morpho.xyz/",
    "description": "",
    "logoURI": "https://cdn.morpho.xyz/assets/logos/logo-dark.svg"
  },

`minimumStake`

There are a number of native staking yields that require the user to stake a minimum amount — these yields include native staking for AVAX, ONE, BNB, MATIC, and APE. These yields have the minimumStake param in their metadata, with the integer representing the native token units.

BNB Native Staking Example:

"minimumStake": 1,

The above parameter can also be found in the args.

    "args": {
      "amount": {
        "required": true,
        "minimum": 1
      }
    }

`supportsMultipleValidators`

This applies only to staking yields. However, there are a few exceptions of staking yields that do not have multi-validator support, which means there is a default validator selection and the user cannot choose which validator to delegate to.

`withdrawPeriod`

The withdrawal period comes after the cooldown period has passed. When an end user requests to unstake their assets, the cooldownPeriod starts. During this cooldown period, the assets are no longer staked and accruing rewards, however, they aren't liquid and available to the user just yet. Following the conclusion of the cooldownPeriod, there is a time window called withdrawPeriod during which the user can claim their tokens. In instances where the tokens aren't claimed on time, they will need to be restaked.

`defaultValidator`

It is the default validator address that gets populated when a user interacts with a native staking yield. However, most yields have multi-validator support and the user is free to edit this default selection and delegate their stake to an alternate validator from the list of available options.

`args: ActionArgumentResponseDto;`

You will find args at the top of each yield's metadata. This is the data required to be passed in order to enter or exit a position.

Cosmos Native Staking Example:

{
  "apy": 0.20318221202235548,
  "args": {
    "enter": {
      "addresses": {
        "address": {
          "required": true,
          "network": "cosmos"
        },
        "additionalAddresses": {
          "cosmosPubKey": {
            "required": true
          }
        }
      },
      "args": {
        "amount": {
          "required": true,
          "minimum": 0
        },
        "validatorAddress": {
          "required": true
        }
      }
    },
    "exit": {
      "addresses": {
        "address": {
          "required": true,
          "network": "cosmos"
        }
      },
      "args": {
        "amount": {
          "required": true,
          "minimum": 0
        },
        "validatorAddress": {
          "required": true
        }
      }
    }
  },