API Documentation

Programmatic access to Yelty's yield intelligence. Real-time data, risk scores, and protocol profiles.

Authentication

All API requests require an API key passed via the x-api-key header. Anonymous requests (no key) are allowed but rate-limited to 20 requests per day.

How to get a key

Send a POST /api/subscribe request with your payment transaction hash (USDC on Arbitrum). The response will include your API key. Free-tier keys are available by calling the endpoint without a tx hash.

Request header

x-api-key: your_api_key_here

Endpoints

GET /api/yields

Returns all yield opportunities currently tracked. Refreshed every 4 hours.

Query Parameters

chainFilter by chain name (e.g., Ethereum, Arbitrum)

minApyMinimum APY threshold (number)

maxRiskMaximum risk grade (A, B, C, D, F)

categoryFilter by category (lending, vault, pt, savings, rwa)

limitNumber of results (default 100, max 1000)

Response schema

{
  "opportunities": [
    {
      "id": "aave-v3-usdc-ethereum",
      "protocol": "Aave V3",
      "symbol": "USDC",
      "chain": "Ethereum",
      "apy": 6.2,
      "apyBase": 5.8,
      "apyReward": 0.4,
      "tvlUsd": 2100000000,
      "riskLevel": "A",
      "riskScore": 88,
      "category": "lending",
      "yieldMechanism": "lending-interest",
      "yieldExplanation": "Interest from borrowers on Aave V3...",
      "riskFactors": {
        "audit": 10,
        "timeOnMarket": 10,
        "teamTransparency": 9,
        "yieldSustainability": 8,
        "smartContractRisk": 9
      },
      "scoringSource": "profile"
    }
  ],
  "meta": {
    "total": 637,
    "lastUpdated": "2026-05-08T12:00:00Z",
    "chainsScanned": 23
  }
}

GET /api/profile?slug=aave

Returns a deep-dive protocol profile including risk analysis, yield mechanism breakdown, audit history, incident timeline, and governance structure. Available for 120+ protocols.

Response schema

{
  "slug": "aave",
  "name": "Aave V3",
  "description": "Leading decentralized lending protocol...",
  "riskGrade": "A",
  "riskScore": 88,
  "yieldMechanisms": ["lending-interest"],
  "audits": [
    { "firm": "Trail of Bits", "date": "2024-03", "scope": "V3 core" }
  ],
  "incidents": [],
  "governance": "DAO with timelock",
  "chains": ["Ethereum", "Arbitrum", "Base", "Optimism", "Polygon"],
  "links": {
    "website": "https://aave.com",
    "docs": "https://docs.aave.com",
    "github": "https://github.com/aave"
  }
}

POST /api/subscribe

Register for an API key. Provide a USDC payment transaction hash for Pro access, or call without a hash for a free-tier key.

Request body

{
  "wallet": "0xYourWalletAddress",
  "txHash": "0xPaymentTxHash",  // optional for free tier
  "plan": "pro"                  // "free" | "pro" | "bot"
}

Response

{
  "apiKey": "pro_a1b2c3d4e5f6g7h8i9j0",
  "plan": "pro",
  "expiresAt": "2026-06-08T12:00:00Z",
  "rateLimit": "unlimited"
}

Rate Limits

Tier	Limit	Window
Anonymous (no key)	20 requests	per day
Free	50 requests	per day
Pro	Unlimited	—

Rate limit headers are included in every response: X-RateLimit-Remaining, X-RateLimit-Reset.

Examples

Use the demo key demo_free_a1b2c3d4e5f6g7h8 to try the API with free-tier limits.

Get all yields

curl -s https://yelty.io/api/yields \
  -H "x-api-key: demo_free_a1b2c3d4e5f6g7h8" | jq .

Filter by chain and min APY

curl -s "https://yelty.io/api/yields?chain=Arbitrum&minApy=10" \
  -H "x-api-key: demo_free_a1b2c3d4e5f6g7h8" | jq .

Get protocol profile

curl -s "https://yelty.io/api/profile?slug=aave" \
  -H "x-api-key: demo_free_a1b2c3d4e5f6g7h8" | jq .

Subscribe (free tier)

curl -X POST https://yelty.io/api/subscribe \
  -H "Content-Type: application/json" \
  -d '{"wallet": "0xYourAddress", "plan": "free"}'

Response Fields

Complete reference for the yield opportunity object returned by GET /api/yields.

Field	Type	Description
`id`	string	Unique opportunity identifier
`protocol`	string	Protocol name (e.g., Aave V3, Pendle)
`symbol`	string	Token symbol (e.g., USDC, USDT)
`chain`	string	Chain name (e.g., Ethereum, Arbitrum)
`apy`	number	Total APY as percentage (e.g., 6.2)
`apyBase`	number	Base APY from organic yield sources
`apyReward`	number	Reward APY from token incentives
`tvlUsd`	number	Total Value Locked in USD
`riskLevel`	string	Risk grade: A, B, C, D, or F
`riskScore`	number	Numeric risk score (0-100, higher = safer)
`category`	string	Category: lending, vault, pt, savings, rwa, delta-neutral
`yieldMechanism`	string	How yield is generated (e.g., lending-interest, rwa-yield)
`yieldExplanation`	string \| null	Human-readable explanation of yield source (Pro only)
`riskFactors`	object	Detailed risk breakdown including audit, timeOnMarket, etc.
`scoringSource`	string	How score was determined: profile, heuristic, or manual

Questions? Reach out on Telegram or open an issue on GitHub.