Skip to content

Integrate yield.xyz DeFi bits (maybe) #11454

New issue
New issue
Open
Open
Integrate yield.xyz DeFi bits (maybe)#11454
Assignees
gomesalexandre
@gomesalexandre

Description

@gomesalexandre
gomesalexandre
opened on Dec 17, 2025

Overview

Placeholderish issue not to forget, see below for Claude Code spike to maybe give this a few hours go at vibe-coding this, requested API access, now we wait

Yield.xyz Integration Research & Recommendation

Executive Summary

Yield.xyz is a unified API for non-custodial DeFi yield opportunities across 70+ blockchain networks, aggregating 2,000+ opportunities including staking, restaking, liquid staking, DeFi lending, and RWA yields. One-time integration provides access to all supported protocols through a standardized interface.

Recommendation: ✅ Excellent fit for ShapeShift

  • Dramatically simpler than protocol-by-protocol integration
  • No heavy abstraction needed - can use direct react-query hooks
  • Self-custodial design aligns with ShapeShift philosophy
  • Built-in monetization via partner revenue sharing
  • Battle-tested by Ledger, Zerion, Tangem (4M+ users)

1. Platform Overview

What is Yield.xyz?

  • Unified API for non-custodial, on-chain yield opportunities across 70+ blockchain networks
  • Aggregates 2,000+ yield opportunities including staking, restaking, liquid staking, DeFi lending, RWA yields, and vaults
  • One-time integration provides access to all supported protocols through a standardized interface
  • Originally built for Omni wallet, now powers Ledger, Zerion, and Tangem (4M+ users, hundreds of millions in monthly volume)

Core Value Proposition

  • Self-custodial by design: Returns fully constructed transactions; users maintain control over signing and execution
  • Chain-agnostic: Supports both EVM and non-EVM networks (Ethereum, Cosmos, Tron, Solana, etc.)
  • No protocol-specific code needed: Single integration covers all 2,000+ opportunities
  • Monetization built-in: Partner revenue sharing through deposit, performance, and management fees

2. Supported Networks & Protocols

EVM Networks (18+)

Arbitrum, Avalanche, Base, BNB Chain, Celo, CoreDAO, Cronos, Ethereum, Gnosis, Harmony, HyperEVM, Katana, Linea, Optimism, Polygon, Sonic, Unichain, Viction

Non-EVM Networks (40+)

Cosmos ecosystem (Osmosis, Juno, etc.), Solana, Polkadot, Cardano, NEAR, Kusama, Tezos, TON, Tron, and more

DeFi Protocols

  • Lending: Aave V3, Compound V3, Morpho, Spark, Euler, Fluid, Venus, Maple
  • Liquid Staking: Lido, RocketPool, Benqi, EtherFi, KelpDAO, Renzo
  • DEXs & Liquidity: Curve, PancakeSwap V3, Uniswap V2
  • Others: Yearn V2/V3, Ethena, Drift, Kamino, Idle Finance, Gearbox, Angle, Blend

3. API Architecture & Core Concepts

Three Main API Patterns

A. Yields Discovery (GET /v1/yields)

  • Returns all available yield opportunities with metadata
  • Real-time APY, TVL, token info, validator data, fee structures
  • Filterable by network, protocol, yield type
  • Includes schema definitions for dynamic form generation

B. Actions (POST /v1/actions/{intent})

Three intent types:

  • Enter: Create positions (stake, lend, deposit)
  • Exit: Unwind positions (unstake, withdraw)
  • Manage: Post-entry operations (claim rewards, restake, redelegate)

Transaction Flow:

  1. Fetch yield schema from GET /v1/yields/{yieldId}
  2. POST to action endpoint with user inputs
  3. Receive unsigned transaction array
  4. Sign with user's wallet
  5. Broadcast to blockchain
  6. (Optional) Submit tx hash back to Yield.xyz for tracking

Smart Routing: Automatically handles token mismatches by constructing swap/bridge transactions

C. Balances (GET /v1/yields/{yieldId}/balances)

  • Real-time position tracking across lifecycle states:
    • active: Currently earning
    • entering: Pending confirmation
    • exiting: Unstaking/cooldown
    • withdrawable: Ready to claim
    • claimable: Rewards available
    • locked: Vesting/restrictions
  • Batch querying via POST /v1/yields/balances for portfolio-wide views
  • Includes passthrough tokens for manage actions

4. Monetization & Partner Revenue

Three Fee Structures (Configurable per opportunity)

Fee Type Range Mechanism When Applied
Deposit Fees 0.2% - 0.8% FeeWrapper smart contracts deduct before deposit Immediate
Performance Fees 10% - 30% Applied to realized profits during harvests Intermittent
Management Fees 1% - 5% annually Annualized rate on total AUM Via harvest cycles

Key Details:

  • Fees are fully configurable at the opportunity level
  • Deposit fees preserve DeFi composability (users receive protocol receipt assets)
  • Performance/Management fees require ERC-4626 Allocator Vaults
  • Payout addresses configured via dashboard
  • Supports validator rebates for staking opportunities

5. Technical Requirements

Authentication

  • API key required (via dashboard at dashboard.stakek.it)
  • Passed as X-API-KEY header
  • Project-based organization with geoblocking, fee config, payout wallets

Integration Options

1. Direct API (Recommended for ShapeShift)

  • REST API with JSON request/response
  • Self-hosted transaction construction and signing
  • Full control over UX/flows

2. TypeScript SDK

  • @stakekit/signers, @stakekit/api-hooks, @stakekit/common
  • Type-safe wrappers
  • Helper utilities for signing
  • React hooks for data fetching

3. Widget (Drop-in component)

  • React component or bundled version
  • Less flexible but faster to deploy
  • Perfect for POC/MVP

Signing

  • Compatible with ethers.js, wagmi, CosmJS, Solana web3.js, etc.
  • Works with browser wallets, hardware wallets, smart accounts, MPC
  • No SDK lock-in for signing - use your existing wallet infrastructure

Security

  • Shield Validation Library: Client-side transaction validation (TypeScript/Golang)
  • HyperNative Integration: Real-time simulation + OFAC/sanctions screening
  • Infrastructure: AWS + Google Cloud failover
  • Three security tiers: Baseline, Enhanced, Advanced (on-prem)

6. Pricing Model

API Access Pricing

  • Not publicly listed - contact sales model
  • Documentation mentions "beta cohort" with private Telegram/Slack channels
  • Likely enterprise/custom pricing based on volume

What We Know

  • Free to create API key and project
  • Revenue sharing fees (deposit/performance/management) go to partners, not API costs
  • ShapeShift would need to contact sales for pricing details

Action: Reach out to Yield.xyz via https://yield.xyz/contact to discuss:

  • API access costs/tiers
  • Volume-based pricing
  • Custom requirements for ShapeShift's user base

7. Compatibility with ShapeShift

✅ High Compatibility - Here's Why

Architecture Alignment:

  • ShapeShift already uses RTK Query for API integrations (see src/state/apis/portals/portalsApi.ts)
  • Existing opportunitiesSlice structure maps well to Yield.xyz yields
  • Current DeFi provider pattern (Cosmos, FOXy, THORChain Savers) can be extended

Wallet Integration:

  • ShapeShift's WalletProvider context already handles multi-wallet support
  • Existing transaction signing flows work with Yield.xyz's unsigned transactions
  • No conflicts with current wallet architecture

Chain Support:

  • ShapeShift supports many of the same chains Yield.xyz covers
  • Cross-chain yield opportunities align with ShapeShift's multi-chain philosophy

User Experience:

  • Yield.xyz's self-custodial design matches ShapeShift's ethos
  • Opportunity discovery UI can leverage existing components
  • DeFi modal patterns already established

8. Integration Approaches

Path A: Widget First (Fastest - 1-2 hours)

Perfect for POC/validation:

// That's literally it - add this to a page
import { SKWidget } from '@stakekit/widget'

<SKWidget
  apiKey={VITE_YIELD_API_KEY}
  theme={{ mode: colorMode }}
  externalProviders={{ evm: wallet?.provider }}
/>

Pros:

  • ✅ Zero dev work, works immediately
  • ✅ Perfect for validation/POC
  • ✅ Can customize theme to match ShapeShift
  • ✅ Uses your existing wallet provider

Cons:

  • ❌ Less control over UX/flows
  • ❌ Can't deeply integrate with existing UI
  • ❌ Limited customization

Path B: Direct React-Query (Simple but Custom - 1 week)

Lightweight, no heavy abstraction:

// src/hooks/useYieldOpportunities.ts
import { useQuery, useMutation } from '@tanstack/react-query'
import axios from 'axios'

const YIELD_API_BASE = 'https://api.stakek.it/v1'
const API_KEY = getConfig().VITE_YIELD_API_KEY

export const useYieldOpportunities = (filters?: { chainId?: string; type?: string }) => {
  return useQuery({
    queryKey: ['yield-opportunities', filters],
    queryFn: async () => {
      const { data } = await axios.get(`${YIELD_API_BASE}/yields`, {
        headers: { 'X-API-KEY': API_KEY },
        params: filters,
      })
      return data
    },
  })
}

export const useYieldBalance = (yieldId: string, address: string) => {
  return useQuery({
    queryKey: ['yield-balance', yieldId, address],
    queryFn: async () => {
      const { data } = await axios.get(
        `${YIELD_API_BASE}/yields/${yieldId}/balances`,
        {
          headers: { 'X-API-KEY': API_KEY },
          params: { address },
        }
      )
      return data
    },
    enabled: !!address,
  })
}

export const useEnterYield = () => {
  return useMutation({
    mutationFn: async ({ yieldId, address, arguments }) => {
      const { data } = await axios.post(
        `${YIELD_API_BASE}/actions/enter`,
        { yieldId, address, arguments },
        { headers: { 'X-API-KEY': API_KEY } }
      )
      return data
    },
  })
}

In components:

const OpportunitiesPage = () => {
  const { data: opportunities } = useYieldOpportunities({ chainId: 'eip155:1' })
  const address = useWalletAddress()
  const { data: balance } = useYieldBalance('ethereum-eth-lido-staking', address)
  const { mutate: enter } = useEnterYield()

  const handleStake = async () => {
    // 1. Get unsigned tx from Yield.xyz
    const { transactions } = await enter({ yieldId, address, arguments: { amount } })
    
    // 2. Use existing wallet/chain-adapter to sign
    const signedTx = await wallet.signTransaction(transactions[0].unsignedTransaction)
    
    // 3. Broadcast via chain adapter
    const txHash = await chainAdapter.broadcastTransaction(signedTx)
  }
}

Pros:

  • ✅ Full control over UX
  • ✅ Integrates with existing UI/patterns
  • ✅ Zero abstraction - direct API calls
  • ✅ No Redux changes needed

Cons:

  • ❌ More work than widget (but still minimal)

9. Why This Changes Everything

Old DeFi Approach (what we had)

Protocol-by-protocol integration:

  • src/features/defi/providers/cosmos/ - One protocol
  • src/features/defi/providers/foxy/ - One protocol
  • src/features/defi/providers/thorchain-savers/ - One protocol

Each with their own:

  • Context/Reducer pattern
  • Deposit/Withdraw/Claim components
  • Custom API integrations
  • Transaction construction logic
  • Maintenance burden

Yield.xyz Approach

One API for everything:

  • Single set of hooks
  • Generic enter/exit/manage flows
  • API handles transaction construction
  • We just sign and broadcast
  • Yield.xyz maintains protocol integrations

Comparison

Old Approach Yield.xyz Approach
1 protocol = 1 week of dev All protocols = 1 week of dev
Manual transaction construction API returns ready-to-sign txs
Protocol-specific UIs Generic enter/exit/manage flows
Track each protocol's changes Yield.xyz handles updates
Limited to protocols we build 2,000+ protocols included

10. Recommended Implementation Plan

Phase 1: Widget POC (Week 1)

Goal: Validate concept with minimal effort

  • Contact Yield.xyz for API key + pricing discussion
  • Create dashboard account at dashboard.stakek.it
  • Add feature flag YieldIntegration
  • Drop widget into /yield page behind feature flag
  • Customize theme to match ShapeShift branding
  • Test internally with team
  • Decision point: Is this valuable? Do users want it?

Phase 2: Custom Integration (Weeks 2-3)

Goal: Build lightweight custom implementation (if POC validates)

  • Create src/state/apis/yield/yieldApi.ts OR direct react-query hooks
  • Define TypeScript types for API responses
  • Build opportunity discovery UI
  • Create enter/exit transaction flows
  • Integrate with existing wallet/chain-adapter
  • Implement balance tracking
  • Add i18n translations
  • Test light/dark mode + mobile responsiveness

Phase 3: Polish & Optimize (Week 4+)

Goal: Production-ready experience

  • Add filtering/sorting (by APY, TVL, chain)
  • Build curated opportunity lists
  • Configure revenue fees (deposit/performance/management)
  • Set up payout wallets
  • Add analytics/tracking
  • Cross-wallet compatibility testing
  • Testnet validation
  • Deploy to production with feature flag

11. Risks & Mitigation

Potential Challenges

  1. API Pricing Unknown

    • Could be expensive at scale
    • May have rate limits
    • Mitigation: Get pricing early, negotiate if needed

  2. Transaction Complexity

    • Multi-step transactions may confuse users
    • Gas costs could be high
    • Mitigation: Clear UI, gas estimates, progressive disclosure

  3. Opportunity Overload

    • 2,000+ opportunities could overwhelm UI
    • Mitigation: Smart filtering, curated lists, search

  4. Protocol Risk

    • Yield.xyz aggregates many protocols
    • Some may have smart contract risks
    • Mitigation: Display risk indicators, use Shield validation

  5. Maintenance

    • API changes require updates
    • Mitigation: Version pinning, monitoring for deprecations

12. Resources

13. Next Steps

Immediate Actions:

  1. Contact Yield.xyz - Get pricing, discuss partnership
  2. Create API key - Set up dashboard account
  3. Widget POC - Test integration in <1 hour
  4. Team review - Validate concept internally

If approved:
5. Feature flag - Add VITE_FEATURE_YIELD_INTEGRATION
6. Phased rollout - Start with widget, iterate to custom
7. Revenue config - Set up fee structure
8. Production deploy - Roll out behind feature flag

14. Conclusion

✅ Yield.xyz is the perfect solution for bringing DeFi back to ShapeShift

Why:

  • ✅ One integration = 2,000+ opportunities (vs. manual per-protocol integration)
  • ✅ Minimal abstraction needed (react-query hooks or even just widget)
  • ✅ Self-custodial design aligns perfectly with ShapeShift philosophy
  • ✅ Built-in monetization with partner revenue sharing
  • ✅ Battle-tested infrastructure (Ledger, Zerion, Tangem)
  • ✅ Works with existing wallet/chain-adapter architecture
  • ✅ Can start with widget POC in <1 hour

Estimated Effort:

  • Widget POC: 1-2 hours
  • Custom lightweight integration: 1-2 weeks
  • Production-ready polish: 3-4 weeks total

ROI: Massive value with minimal engineering investment compared to protocol-by-protocol integration.

References and additional details

N/A

Acceptance Criteria

  1. It works
  2. It's not an ugly abstraction like the DeFi one we need to manually maintain, we can roll and forget about it once written

Need By Date

No response

Screenshots/Mockups

No response

Estimated effort

No response

Metadata

Metadata

Assignees

Labels

No labels
No labels

Type

No type

Projects

ShapeShift Dashboard

Status

Backlog

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions