Earn Service Provider

The Earn Service Provider backs Earn Kit with Circle Earn service APIs. It handles vault discovery, position lookups, quote requests, signed execution payloads, cross-chain bridge deposit prepare and submit requests, typed response validation, and Earn-specific API error parsing.

Installation

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

This provider is included by default in @circle-fin/earn-kit. Import it directly when you need to customize provider construction or compose your own Earn Kit context.

Quick Start

import {
  EarnChain,
  createEarnKitContext,
  getVaults,
} from '@circle-fin/earn-kit'
import { EarnServiceProvider } from '@circle-fin/provider-earn-service'

const provider = new EarnServiceProvider()
const context = createEarnKitContext({ providers: [provider] })

const result = await getVaults(context, {
  vaults: [
    {
      chain: EarnChain.Arc_Testnet,
      vaultAddress: '0x8eB67A509616cd6A7c1B3c8C21D48FF57df3d458',
    },
  ],
})

console.log(`Found ${result.vaults.length} vaults`)

Configuration

EarnServiceProvider accepts default configuration in the constructor and per-operation configuration on each request. Per-operation values take precedence, while omitted values continue to use constructor defaults.

const provider = new EarnServiceProvider({
  baseUrl: 'https://api.circle.com',
})

await provider.getVaults({
  vaults: [
    {
      chain: 'Arc_Testnet',
      vaultAddress: '0x8eB67A509616cd6A7c1B3c8C21D48FF57df3d458',
    },
  ],
  config: {
    apiKey: process.env.CIRCLE_API_KEY,
  },
})

Supported Chains

The initial provider release supports Arc Testnet earn flows. Same-chain deposits use the existing approval and Earn action execution path.

Cross-chain deposits are available when the request has a supported EVM source chain, a supported Earn destination chain, matching testnet or mainnet environments, source token configuration, CCTP routing, and bridge adapter configuration. The provider validates those route requirements before calling the bridge prepare endpoint.

License

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