Understanding Rewards - Dialect Developer Documentation

Rewards are additional incentives provided by DeFi protocols to encourage specific actions like depositing, borrowing, or maintaining certain positions. Unlike base APY rates generated by protocol activity, rewards are typically funded by the protocol itself or partners to drive liquidity and usage.

Markets API Rewards

Understanding APY Structure

The Markets API provides three types of APY data for each market:

Base APY (Natural Protocol Yields)

This is the APY you’ll always get. It’s excluding the rewards.

baseDepositApy - Interest earned from borrowers paying to use your deposited assets
baseBorrowApy - Interest rate you pay to borrow assets from the protocol

{
  "baseDepositApy": 0.0345,
  "baseBorrowApy": 0.1375
}

Rewards (Extra Incentives)

This is the APY that comes on top of the base APY for doing a specific actions on the platform. These are funded by protocols/partners to drive specific behaviors.

rewards array - Additional token incentives on top of base yields

{
  "rewards": [
    {
      "type": "deposit",
      "apy": 0.0846,
      "token": {
        "address": "AuQaustGiaqxRvj2gtCdrd22PBzTn8kM3kEPEkZCtuDw",
        "symbol": "ADX",
        "decimals": 6,
        "icon": "https://i.ibb.co/52cM38T/adrena-logo-adx-color-200x200.png"
      },
      "marketAction": "deposit"
    }
  ]
}

Total APY (What You Actually Earn)

This is the APY including rewards.

depositApy = baseDepositApy + sum of all deposit reward APYs
borrowApy = baseBorrowApy - sum of all borrow reward APYs (rewards reduce cost for borrowers)

{
  "depositApy": 0.1041,
  "borrowApy": 0.0459
}

Example: Real Market Analysis

Let’s walk through actual market data from Kamino to understand how rewards work:

Deposit Rewards

Deposit rewards increase the yield of depositing an asset. You can earn either a single reward token or multiple tokens from one deposit action.

Single Token Reward

This example shows a market with a single token reward for depositing USDC, in this case ADX tokens.

{
  "id": "kamino.5bgPMvzZv29jkFEuMwxQRJQf64gKcPfLEEUHhyrP8tce",
  "token": {
    "symbol": "USDC",
    "address": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
    "decimals": 6,
    "icon": "https://raw.githubusercontent.com/solana-labs/token-list/main/assets/mainnet/EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v/logo.png"
  },
  "baseDepositApy": 0.032, // 3.2% from lending activity
  "depositApy": 0.1041, // 10.41% total (base + rewards)
  "baseBorrowApy": 0.1363, // 13.63% borrow cost
  "borrowApy": 0.1363, // Same - no borrow rewards
  "rewards": [
    {
      "type": "deposit", // Single action needed
      "apy": 0.0721, // 7.21% in ADX tokens
      "token": {
        "address": "AuQaustGiaqxRvj2gtCdrd22PBzTn8kM3kEPEkZCtuDw",
        "symbol": "ADX",
        "decimals": 6,
        "icon": "https://i.ibb.co/52cM38T/adrena-logo-adx-color-200x200.png"
      },
      "marketAction": "deposit" // You deposit USDC
    }
  ]
}

What This Tells You:

Depositors earn: 3.2% base + 7.21% ADX rewards = 10.41% total
Borrowers pay: 13.63% (no rewards to reduce cost)
Action needed: Deposit USDC to get ADX rewards

Multiple Token Rewards

Some markets offer multiple reward tokens for a single deposit action. Here’s a real example where depositing USDS earns both HUMA and USDS rewards:

{
  "id": "kamino.9XbExNmevn7jzNzbX3kAzxKq83mdYP5ZN4xcYpLUVHGU",
  "token": {
    "symbol": "USDS",
    "address": "USDSwr9ApdHk5bvJKMjzff41FfuX8bSxdKcR81vTwcA",
    "decimals": 6,
    "icon": "https://ipfs.io/ipfs/QmTW9HWfb2wsQqEVJiixkQ73Nsfp2Rx4ESaDSiQ7ThwnFM"
  },
  "depositApy": 0.1171, // 11.71% total return
  "baseDepositApy": 0.0079, // 0.79% base lending yield
  "borrowApy": 0.0199, // 1.99% borrow cost
  "baseBorrowApy": 0.0199, // Same - no borrow rewards
  "rewards": [
    {
      "type": "deposit",
      "apy": 0.0553, // 5.53% in HUMA tokens
      "token": {
        "address": "HUMA1821qVDKta3u2ovmfDQeW2fSQouSKE8fkF44wvGw",
        "symbol": "HUMA",
        "decimals": 6,
        "icon": "https://meta.huma.finance/huma.svg"
      },
      "marketAction": "deposit"
    },
    {
      "type": "deposit",
      "apy": 0.054, // 5.4% in USDS tokens
      "token": {
        "address": "USDSwr9ApdHk5bvJKMjzff41FfuX8bSxdKcR81vTwcA",
        "symbol": "USDS",
        "decimals": 6,
        "icon": "https://ipfs.io/ipfs/QmTW9HWfb2wsQqEVJiixkQ73Nsfp2Rx4ESaDSiQ7ThwnFM"
      },
      "marketAction": "deposit"
    }
  ]
}

What This Tells You:

Depositors earn: 0.79% base + 5.53% HUMA + 5.4% USDS = 11.71% total
Borrowers pay: 1.99% (no rewards)
Action needed: Just deposit USDS once to earn both HUMA and USDS rewards
Calculation: depositApy (11.71%) = baseDepositApy (0.79%) + HUMA APY (5.53%) + USDS APY (5.4%)

Multiple token rewards are also possible for borrow rewards. The same rules apply as for deposit rewards.

Borrow Rewards

Borrow rewards reduce the cost of borrowing an asset.

{
  "id": "kamino.FBLWZjz7nKJUUMBah7Gzv3GqWEpzZdhwJy79YS8tZUg1",
  "token": {
    "symbol": "jitoSOL",
    "address": "J1toso1uCk3RLmjorhTtrVwY9HJ7X8V9yYac6Y7kGCPn",
    "decimals": 9,
    "icon": "https://storage.googleapis.com/token-metadata/JitoSOL-256.png"
  },
  "baseDepositApy": 0.0739, // 7.39% natural staking yield
  "depositApy": 0.0739, // Same - no deposit rewards
  "baseBorrowApy": 0.0918, // 9.18% natural borrow cost
  "borrowApy": 0.032, // 3.2% actual cost (reduced by rewards)
  "rewards": [
    {
      "type": "borrow", // Single action needed
      "apy": 0.0598, // 5.98% in JTO tokens
      "token": {
        "address": "jtojtomepa8beP8AuQc6eXt5FriJwfFMwQx2v2f9mCL",
        "symbol": "JTO",
        "decimals": 9,
        "icon": "https://metadata.jito.network/token/jto/image"
      },
      "marketAction": "borrow" // You borrow jitoSOL
    }
  ]
}

What This Tells You:

Depositors earn: 7.39% (just the base staking yield, no extra rewards)
Borrowers earn: 9.18% borrow cost - 5.98% JTO rewards = 3.2% net cost
Action needed: Borrow jitoSOL to get JTO rewards

Markets with Both Deposit and Borrow Rewards

Some markets incentivize both sides: depositors AND borrowers in the same market. Here’s a real SOL market example:

{
  "id": "kamino.4oigbthMAgjTMPyw8dBxhxU59YMtvNDHqhpR3W4HAzBM",
  "token": {
    "symbol": "SOL",
    "address": "So11111111111111111111111111111111111111112",
    "decimals": 9,
    "icon": "https://raw.githubusercontent.com/solana-labs/token-list/main/assets/mainnet/So11111111111111111111111111111111111111112/logo.png"
  },
  "depositApy": 0.0695, // 6.95% total deposit return
  "baseDepositApy": 0.0596, // 5.96% natural lending yield
  "borrowApy": 0.0665, // 6.65% actual borrow cost
  "baseBorrowApy": 0.0696, // 6.96% natural borrow cost
  "rewards": [
    {
      "type": "deposit",
      "apy": 0.0098, // 0.98% BLZE for depositors
      "token": {
        "address": "BLZEEuZUBVqFhj8adcCFPJvPVCiCyVmh3hkJMrU8KuJA",
        "symbol": "BLZE",
        "decimals": 9,
        "icon": "https://solblaze.org/assets/blze.png?v=2"
      },
      "marketAction": "deposit"
    },
    {
      "type": "borrow",
      "apy": 0.0031, // 0.31% BLZE for borrowers
      "token": {
        "address": "BLZEEuZUBVqFhj8adcCFPJvPVCiCyVmh3hkJMrU8KuJA",
        "symbol": "BLZE",
        "decimals": 9,
        "icon": "https://solblaze.org/assets/blze.png?v=2"
      },
      "marketAction": "borrow"
    }
  ]
}

What This Tells You:

Depositors earn: 5.96% base + 0.98% BLZE = 6.95% total
Borrowers pay: 6.96% base - 0.31% BLZE = 6.65% net cost
Both sides win: Depositors get higher yields, borrowers get lower costs
Same reward token: Both depositors and borrowers earn BLZE tokens

Reading Reward Data

Field	What it tells you
`type`	Reward type: either `"deposit"` or `"borrow"`
`apy`	Annual percentage yield for this reward token
`token`	Token details: address, symbol, decimals, icon
`marketAction`	Your action in the market to earn this reward: mostly matches `type`

Claiming Rewards

Most protocols allow you to claim accumulated rewards at any time. Look for the claimRewards action in the market data:

{
  "actions": {
    "deposit": {
      "blinkUrl": "blink:https://kamino.dial.to/api/v0/lending/..."
    },
    "withdraw": {
      "blinkUrl": "blink:https://kamino.dial.to/api/v0/lending/..."
    },
    "claimRewards": {
      "blinkUrl": "blink:https://kamino.dial.to/api/v0/lending/..."
    }
  }
}

Positions API Rewards

The Positions API shows you the rewards you have already earned in your positions. Unlike the Markets API, which provides static information about available reward opportunities, the Positions API is wallet-specific, which means that you provide your wallet address and get back your actual accrued rewards.

What the Positions API Shows

When you query the Positions API with your wallet address, you get:

Your actual accrued rewards - The real amounts of reward tokens you’ve earned. Even if you’ve withdrawn from a position, your rewards remain visible
Nested market data - Current market information (including the reward rules from the Markets API) for convenience, so you don’t need a separate API call
Open positions - The open positions you have in the market incl. market data, etc.

The “reward” Position Type (recommended)

When calling our Positions API, you will receive active positions, e.g. positions with the type yield or lending and positions with the type reward that reflects the rewards you have earned from those positions. The reward position type is an atomic tracking system that ensures your rewards are always visible, even after the main position was closed, which is why it’s recommended to use this type over the deprecated rewards array. The Problem with the rewards array:

The rewards array is part of active positions
When you close a position (withdraw everything), the position amount becomes 0 and it no longer appears in the positions array
But you might still have unclaimed rewards from that position (for example, Kamino season rewards that aren’t available to claim yet)
Without the position in the array, those rewards would disappear from your view

The Solution with the reward position type: The reward position type ensures that each reward is tracked separately, bringing you the following benefits:

Your rewards are always visible, even after the main position is closed
You never lose track of rewards you’re entitled to claim
The system maintains a clear record of all your reward entitlements
Nested data structure allows you to easily access the parent position and the reward token details

Example Reward Position

Here’s a complete reward position example for a Kamino Allez USDC yield position. Please note that we might add more fields to the reward position in the future, so please check the API Reference for the latest details.

Reward Position Example Kamino Lend

{
  "id": "kamino.reward.2ArD5N7CBi9JHxQwPWkvUFVLbowBA4nAcDRYGDwfmhpD.FAFxVxnkzZHMCodkWyoccgUNgVScqMw2mhhQBYDFjFAF.6JpNV6DK88auwzKVizdeT4Bw3D44sam5GqjcPCJ7y176",
  "type": "reward",
  "ownerAddress": "6JpNV6DK88auwzKVizdeT4Bw3D44sam5GqjcPCJ7y176",
  "bundleId": "kamino.lend.A1USdzqDHmw5oz97AkqAGLxEQZfFjASZFuy4T6Qdvnpo",
  "token": {
    "address": "FAFxVxnkzZHMCodkWyoccgUNgVScqMw2mhhQBYDFjFAF",
    "symbol": "FAF",
    "decimals": 6,
    "icon": "https://arweave.net/kOySlhk3gkg16EZrt9WssPQW4vv1P36I51c3OX3lmEc"
  },
  "marketId": "kamino.lend.A1USdzqDHmw5oz97AkqAGLxEQZfFjASZFuy4T6Qdvnpo",
  "position": {
    "id": "kamino.lend.A1USdzqDHmw5oz97AkqAGLxEQZfFjASZFuy4T6Qdvnpo.6JpNV6DK88auwzKVizdeT4Bw3D44sam5GqjcPCJ7y176",
    "type": "yield"
  },
  "additionalData": {},
  "amount": 0.000398,
  "market": {
    "id": "kamino.lend.A1USdzqDHmw5oz97AkqAGLxEQZfFjASZFuy4T6Qdvnpo",
    "type": "yield",
    "provider": {
      "id": "kamino",
      "name": "Kamino",
      "icon": "https://imagedelivery.net/C7jfNnfrjpAYWW6YevrFDg/5cddfb2e-c98e-4734-528b-b541fb5e2b00/public"
    },
    "token": {
      "address": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
      "symbol": "USDC",
      "decimals": 6,
      "icon": "https://raw.githubusercontent.com/solana-labs/token-list/main/assets/mainnet/EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v/logo.png"
    },
    "websiteUrl": "https://kamino.com/lend/allez-usdc",
    "depositApy": 0.0539,
    "baseDepositApy": 0.0315,
    "baseDepositApy30d": 0.0733,
    "baseDepositApy90d": 0.0942,
    "baseDepositApy180d": 0.1225,
    "totalDeposit": 34280362.60412186,
    "totalDepositUsd": 34273898.7,
    "rewards": [
      // Public data from Markets API,
      // displaying the potential rewards for the market,
      // not the user's actual rewards (good to use)
      {
        "type": "deposit",
        "apy": 0.0002,
        "token": {
          "address": "HUMA1821qVDKta3u2ovmfDQeW2fSQouSKE8fkF44wvGw",
          "symbol": "HUMA",
          "decimals": 6,
          "icon": "https://meta.huma.finance/huma.svg"
        },
        "marketAction": "deposit"
      },
      {
        "type": "deposit",
        "apy": 0.0223,
        "token": {
          "address": "KMNo3nJsBXfcpJTVhZcXLW7RmTwTt4GVFE7suUBo9sS",
          "symbol": "KMNO",
          "decimals": 6,
          "icon": "https://cdn.kamino.finance/kamino.svg"
        },
        "marketAction": "deposit"
      }
    ],
    "additionalData": {
      "vaultAddress": "A1USdzqDHmw5oz97AkqAGLxEQZfFjASZFuy4T6Qdvnpo",
      "vaultSlug": "allez-usdc",
      "vaultName": "Allez USDC",
      "vaultRiskProfile": "Balanced"
    },
    "actions": {
      "deposit": {
        "blinkUrl": "blink:https://kamino.dial.to/api/v0/lend/allez-usdc/deposit"
      },
      "withdraw": {
        "blinkUrl": "blink:https://kamino.dial.to/api/v0/lend/allez-usdc/withdraw"
      },
      "claimRewards": {
        "blinkUrl": "blink:https://kamino.dial.to/api/v0/lend/allez-usdc/claim-rewards"
      }
    }
  }
}

Field Breakdown:

Field	Description
`id`	Unique identifier for the reward position containing of the protocol, product, identifier, reward token, and reward provenance
`type`	Always `"reward"` for reward positions
`token`	The reward token you’ve earned (e.g., KMNO, JTO, HUMA, FAF)
`amount`	Quantity of reward tokens accrued
`amountUsd`	USD value of your rewards (optional)
`marketId`	Which market generated this reward
`position`	Reference to the parent position (type and id) that generated this reward
`market`	Full nested market data including current APYs, available rewards, and claim actions

Accessing Reward Positions

To work with reward positions in your code, filter the positions array by type:

// Get all reward positions from the Positions API response
const rewardPositions = positions.filter((p) => p.type === "reward");

// Example: Display all rewards
rewardPositions.forEach((reward) => {
  console.log(`${reward.amount} ${reward.token.symbol}`);
  // soon: we will add the amountUsd field to the reward position
  if (reward.amountUsd) {
    console.log(`  Worth: $${reward.amount.toFixed(2)}`);
  }
});

Linking to Parent Positions

Each reward position includes a position field that references the parent position that generated it:

// Find the parent position for a reward
const reward = rewardPositions[0];
const parentPosition = positions.find((p) => p.id === reward.position.id);

if (parentPosition) {
  console.log(`This ${reward.token.symbol} reward came from:`);
  console.log(`  Position type: ${reward.position.type}`);
  console.log(`  Position amount: ${parentPosition.amount}`);
} else {
  console.log(`Parent position closed, but reward remains claimable`);
}

This is particularly useful when the parent position has been closed (withdrawn), but the rewards are still available to claim.

Nested Market Data

For your convenience, each position in the Positions API includes the current market data. This means you can display everything you need without making a separate call to the Markets API. The nested market object includes:

Current APY rates (depositApy, borrowApy, baseDepositApy, baseBorrowApy)
Available rewards (the Markets API rewards array with APY and token info)
Market details (token info, provider, website URL)
Market actions (deposit, withdraw, borrow, repay Blink URLs)

The `rewards` Array (deprecated)

This array is deprecated and will be removed in the future. Please migrate to using the reward position type instead, which provides the same data with better reliability and additional features.

The old way of tracking rewards was through a rewards array within the lending and yield type positions:

Reward Position Example Kamino Lend

{
  "id": "kamino.lend.A1USdzqDHmw5oz97AkqAGLxEQZfFjASZFuy4T6Qdvnpo.6JpNV6DK88auwzKVizdeT4Bw3D44sam5GqjcPCJ7y176",
  "type": "yield",
  "marketId": "kamino.lend.A1USdzqDHmw5oz97AkqAGLxEQZfFjASZFuy4T6Qdvnpo",
  "ownerAddress": "6JpNV6DK88auwzKVizdeT4Bw3D44sam5GqjcPCJ7y176",
  "bundleId": "kamino.lend.A1USdzqDHmw5oz97AkqAGLxEQZfFjASZFuy4T6Qdvnpo",
  "rewards": [
    {
      "tokenAddress": "FAFxVxnkzZHMCodkWyoccgUNgVScqMw2mhhQBYDFjFAF",
      "amount": 0.000398
    },
    {
      "tokenAddress": "HUMA1821qVDKta3u2ovmfDQeW2fSQouSKE8fkF44wvGw",
      "amount": 0.002389
    },
    {
      "tokenAddress": "KMNo3nJsBXfcpJTVhZcXLW7RmTwTt4GVFE7suUBo9sS",
      "amount": 0.04918834980802605
    },
    {
      "tokenAddress": "KMNo3nJsBXfcpJTVhZcXLW7RmTwTt4GVFE7suUBo9sS",
      "amount": 0.26065915278827795
    }
  ],
  "additionalData": {},
  "amount": 2.013886,
  "amountUsd": 2.01,
  "market": {
    // more market data here
  }
  // more data here (ltv, actions, etc.)
}

Why This Is Deprecated: The rewards array has a critical limitation: when you close a position (withdraw all funds), the position disappears from the array, and so do your unclaimed rewards. This is problematic because:

Some protocols have delayed reward claiming (e.g., seasonal rewards)
You could lose track of rewards you’re entitled to claim
No way to see historical rewards from closed positions

Migration to Reward Position Type: Instead of using the rewards array, use the new reward position type which solves these problems:

// ❌ Old way (deprecated) - rewards disappear when position closes
const oldRewards = positions
  .filter((p) => p.type === "yield" || p.type === "lending")
  .flatMap((p) => p.rewards || []);

// ✅ New way (recommended) - rewards persist even after position closes
const newRewards = positions.filter((p) => p.type === "reward");

Comparison:

Aspect	Deprecated `rewards` Array	New `reward` Position Type
Availability	Only on active positions	Always visible, even after position closes
Token details	Just `tokenAddress`	Full token object (symbol, icon, decimals)
Market reference	No direct link	Includes `marketId` and full nested `market` data
Claim action	Must find separately	Included in nested `market.actions.claimRewards`
Parent position	Implicit (part of position)	Explicit `position` field linking to parent

See the reward position type section for detailed examples of the recommended approach.

GETTING STARTED

Markets

Positions

​Markets API Rewards

​Understanding APY Structure

​Base APY (Natural Protocol Yields)

​Rewards (Extra Incentives)

​Total APY (What You Actually Earn)

​Example: Real Market Analysis

​Deposit Rewards

Single Token Reward

Multiple Token Rewards

​Borrow Rewards

​Markets with Both Deposit and Borrow Rewards

​Reading Reward Data

​Claiming Rewards

​Positions API Rewards

​What the Positions API Shows

​The “reward” Position Type (recommended)

​Example Reward Position

​Accessing Reward Positions

​Linking to Parent Positions

​Nested Market Data

​The rewards Array (deprecated)

Markets API Rewards

Understanding APY Structure

Base APY (Natural Protocol Yields)

Rewards (Extra Incentives)

Total APY (What You Actually Earn)

Example: Real Market Analysis

Deposit Rewards

Borrow Rewards

Markets with Both Deposit and Borrow Rewards

Reading Reward Data

Claiming Rewards

Positions API Rewards

What the Positions API Shows

The “reward” Position Type (recommended)

Example Reward Position

Accessing Reward Positions

Linking to Parent Positions

Nested Market Data

The `rewards` Array (deprecated)