Earn Kit

Note: Earn Kit is coming soon. The APIs documented here are published for early integration and feedback; vault availability and production readiness will be announced ahead of general availability.

Earn Kit is a Circle SDK for DeFi lending vault earn flows. It provides typed operations for discovering vaults, fetching wallet positions, previewing deposits, withdrawals, and reward claims, and executing deposit, withdraw, and claim rewards transactions.

Installation

npm install @circle-fin/earn-kit
# or
yarn add @circle-fin/earn-kit

Install an adapter for the wallet stack you use. For EVM flows:

npm install @circle-fin/adapter-viem-v2 viem
# or
yarn add @circle-fin/adapter-viem-v2 viem

Quick Start

import { Blockchain, EarnChain, EarnKit } from '@circle-fin/earn-kit'
import { createViemAdapterFromPrivateKey } from '@circle-fin/adapter-viem-v2'

const kit = new EarnKit()
const adapter = createViemAdapterFromPrivateKey({
  privateKey: process.env.PRIVATE_KEY,
})

const quote = await kit.getDepositQuote({
  from: { adapter, chain: EarnChain.Arc_Testnet },
  vaultAddress: '0xAabbeF1D3971c710276ed41eC791BbE14CdB8E88',
  amount: '100.50',
})

console.log(`Expected shares: ${quote.expectedShares.amount}`)

const depositResult = await kit.deposit({
  from: { adapter, chain: EarnChain.Arc_Testnet },
  vaultAddress: '0xAabbeF1D3971c710276ed41eC791BbE14CdB8E88',
  amount: '100.50',
})

console.log(`Deposit submitted: ${depositResult.txHash}`)

Deposits

Same-chain deposits keep the existing approval and Earn action flow. Cross-chain deposits are selected only when to is present and to.chain differs from from.chain.

const bridgeDeposit = await kit.deposit({
  from: { adapter, chain: Blockchain.Ethereum_Sepolia },
  to: {
    chain: EarnChain.Arc_Testnet,
    recipientAddress: '0x1234567890123456789012345678901234567890',
  },
  vaultAddress: '0xAabbeF1D3971c710276ed41eC791BbE14CdB8E88',
  amount: '100.50',
})

console.log(`Bridge deposit submitted: ${bridgeDeposit.execId}`)

For cross-chain deposits, to.recipientAddress is the destination wallet that receives the vault position and from.address can be used as an optional source wallet override. The returned result contains the bridge execution ID, submit status, source chain, destination chain, vault address, amount, and prepared bundle expiry timestamp. The SDK generates the bridge execution ID and retry() resumes the same bridge execution after a failure.

Cross-chain Earn deposits currently support Ethereum Sepolia, Arbitrum Sepolia, and Base Sepolia as source chains, with Arc Testnet as the Earn destination chain.

Withdrawal Fees

Withdrawal quotes return operation fees in quote.fees. Circle withdrawal fees are tagged with type: 'circle' so integrators can show the fee preview before calling withdraw.

const quote = await kit.getWithdrawalQuote({
  from: { adapter, chain: EarnChain.Arc_Testnet },
  vaultAddress: '0xAabbeF1D3971c710276ed41eC791BbE14CdB8E88',
  amount: '50.00',
})

const circleFee = quote.fees.find((fee) => fee.type === 'circle')
if (circleFee === undefined) {
  console.log('Circle fee: 0')
} else {
  console.log(`Circle fee: ${circleFee.amount} ${circleFee.symbol}`)
}

When no Circle fee applies, including when the backend fee flag is disabled, quote.fees has no type: 'circle' entry. EarnKit formats fee amounts as human-readable decimal strings, consistent with the rest of the kit-level quote surface. Read the returned fee entry's symbol rather than assuming a fixed fee token.

Discovering Vaults

Iterate every vault available on a chain without managing pagination:

for await (const vault of kit.exploreVaultsIterator({
  chain: 'Arc_Testnet',
  sortBy: 'apy',
})) {
  console.log(`${vault.name}: ${(vault.currentApy * 100).toFixed(2)}% APY`)
}

For paged UIs that need totals, fetch one page at a time instead:

const { vaults, pagination } = await kit.exploreVaults({
  chain: 'Arc_Testnet',
  page: 1,
})
console.log(`Page 1 of ${pagination.totalPages} (${pagination.totalCount} vaults)`)

Supported Chains

Use kit.getSupportedChains() or the functional getSupportedChains(context) helper to read the supported chain definitions from configured earn providers.

Core Operations

• getVaults: fetch vault metadata for one or more vaults.
• exploreVaultsIterator: lazily iterate every vault available on a chain with optional protocol, asset, APY, and TVL filters. Pages are fetched on demand, so there is no page arithmetic to manage.
• exploreVaults: fetch a single page of vault discovery results with pagination metadata, for paged UIs.
• getPosition: fetch a wallet position for a vault.
• getDepositQuote: preview a deposit.
• getWithdrawalQuote: preview a withdrawal.
• getClaimRewardsQuote: preview claimable rewards.
• deposit: execute a deposit transaction.
• withdraw: execute a withdrawal transaction.
• claimRewards: claim rewards, or return without a transaction when none are claimable.
• getCrossChainDepositStatus: read the current bridge status of a cross-chain deposit by execId.
• waitForCrossChainDeposit: poll a cross-chain deposit until it reaches a terminal bridge state (or the wait budget elapses).

Configuration

Earn Kit works without a Kit Key. A Kit Key can be passed per operation for permissioned access and attribution:

await kit.getVaults({
  vaults: [
    {
      chain: 'Arc_Testnet',
      vaultAddress: '0xAabbeF1D3971c710276ed41eC791BbE14CdB8E88',
    },
  ],
  config: {
    kitKey: process.env.KIT_KEY,
  },
})

License

This project is licensed under the Apache 2.0 License. Contact support for details.