defillama-sdk 0.1.0__py3-none-any.whl

defillama_api/__init__.py

@@ -0,0 +1,71 @@
+"""DefiLlama Python SDK entry point."""
+
+from typing import Optional
+
+from .client import BaseClient, DefiLlamaConfig
+from .errors import ApiError, ApiKeyRequiredError, DefiLlamaError, NotFoundError, RateLimitError
+from .modules.account import AccountModule
+from .modules.bridges import BridgesModule
+from .modules.dat import DatModule
+from .modules.ecosystem import EcosystemModule
+from .modules.emissions import EmissionsModule
+from .modules.etfs import EtfsModule
+from .modules.fees import FeesModule
+from .modules.prices import PricesModule
+from .modules.stablecoins import StablecoinsModule
+from .modules.tvl import TvlModule
+from .modules.volumes import VolumesModule
+from .modules.yields import YieldsModule
+
+
+class DefiLlama:
+    """DefiLlama API client for accessing DeFi data."""
+
+    def __init__(self, config: Optional[DefiLlamaConfig] = None) -> None:
+        """Create a new DefiLlama client."""
+
+        self._client = BaseClient(config)
+        self.tvl = TvlModule(self._client)
+        self.prices = PricesModule(self._client)
+        self.stablecoins = StablecoinsModule(self._client)
+        self.yields = YieldsModule(self._client)
+        self.volumes = VolumesModule(self._client)
+        self.fees = FeesModule(self._client)
+        self.emissions = EmissionsModule(self._client)
+        self.bridges = BridgesModule(self._client)
+        self.ecosystem = EcosystemModule(self._client)
+        self.etfs = EtfsModule(self._client)
+        self.dat = DatModule(self._client)
+        self.account = AccountModule(self._client)
+
+    @property
+    def isPro(self) -> bool:
+        """Return True when the client has a Pro API key configured."""
+
+        return self._client.has_api_key
+
+
+__all__ = [
+    "DefiLlama",
+    "DefiLlamaConfig",
+    "ApiError",
+    "ApiKeyRequiredError",
+    "DefiLlamaError",
+    "NotFoundError",
+    "RateLimitError",
+    "TvlModule",
+    "PricesModule",
+    "StablecoinsModule",
+    "YieldsModule",
+    "VolumesModule",
+    "FeesModule",
+    "EmissionsModule",
+    "BridgesModule",
+    "EcosystemModule",
+    "EtfsModule",
+    "DatModule",
+    "AccountModule",
+]
+
+from .constants import *
+from .types import *

defillama_api/client.py

@@ -0,0 +1,157 @@
+"""HTTP client for the DefiLlama API."""
+
+from __future__ import annotations
+
+from typing import Any, Dict, Mapping, Optional, Literal, TypedDict
+
+import requests
+
+from .errors import ApiError, ApiKeyRequiredError, NotFoundError, RateLimitError
+
+
+class DefiLlamaConfig(TypedDict, total=False):
+    api_key: str
+    apiKey: str
+    timeout: int
+
+
+BaseUrl = Literal["main", "v2", "bridges", "coins", "stablecoins"]
+
+BASE_URLS: Dict[str, str] = {
+    "main": "https://api.llama.fi",
+    "v2": "https://api.llama.fi/v2",
+    "pro": "https://pro-api.llama.fi",
+    "bridges": "https://bridges.llama.fi",
+    "coins": "https://coins.llama.fi",
+    "stablecoins": "https://stablecoins.llama.fi",
+}
+
+
+class BaseClient:
+    """Low-level HTTP client used by all modules."""
+
+    def __init__(self, config: Optional[Mapping[str, Any]] = None) -> None:
+        config = config or {}
+        api_key = None
+        if "api_key" in config:
+            api_key = config.get("api_key")
+        elif "apiKey" in config:
+            api_key = config.get("apiKey")
+        self._api_key = api_key
+        timeout_ms = config.get("timeout", 30000)
+        self._timeout = timeout_ms / 1000.0
+
+    @property
+    def has_api_key(self) -> bool:
+        """Return True when a Pro API key is configured."""
+
+        return bool(self._api_key)
+
+    @property
+    def timeout(self) -> float:
+        """Return the configured request timeout in seconds."""
+
+        return self._timeout
+
+    def get_api_key(self) -> Optional[str]:
+        """Return the configured API key, if any."""
+
+        return self._api_key
+
+    def _build_url(
+        self,
+        endpoint: str,
+        requires_auth: bool,
+        base: BaseUrl = "main",
+        api_namespace: str = "api",
+    ) -> str:
+        if base == "v2":
+            if not self._api_key:
+                raise ApiKeyRequiredError(endpoint)
+            return f"{BASE_URLS['pro']}/{self._api_key}/api/v2{endpoint}"
+        if base == "bridges":
+            if not self._api_key:
+                raise ApiKeyRequiredError(endpoint)
+            return f"{BASE_URLS['pro']}/{self._api_key}/bridges{endpoint}"
+        if base == "coins":
+            return f"{BASE_URLS['coins']}{endpoint}"
+        if base == "stablecoins":
+            return f"{BASE_URLS['stablecoins']}{endpoint}"
+        if requires_auth:
+            if not self._api_key:
+                raise ApiKeyRequiredError(endpoint)
+            namespace = f"/{api_namespace}" if api_namespace else ""
+            return f"{BASE_URLS['pro']}/{self._api_key}{namespace}{endpoint}"
+        return f"{BASE_URLS['main']}{endpoint}"
+
+    def _handle_response(self, response: requests.Response, endpoint: str) -> Any:
+        if response.ok:
+            return response.json()
+        text = response.text
+        if response.status_code == 404:
+            raise NotFoundError(endpoint)
+        if response.status_code == 429:
+            retry_after = response.headers.get("Retry-After")
+            retry_value = int(retry_after) if retry_after and retry_after.isdigit() else None
+            raise RateLimitError(retry_value)
+        try:
+            error_body = response.json()
+        except ValueError:
+            error_body = text
+        raise ApiError(
+            response.status_code,
+            f"API request failed: {response.reason}",
+            error_body,
+        )
+
+    def _filter_params(self, params: Optional[Mapping[str, Any]]) -> Optional[Dict[str, Any]]:
+        if not params:
+            return None
+        filtered: Dict[str, Any] = {}
+        for key, value in params.items():
+            if value is not None:
+                filtered[key] = value
+        return filtered or None
+
+    def get(
+        self,
+        endpoint: str,
+        *,
+        params: Optional[Mapping[str, Any]] = None,
+        requires_auth: bool = False,
+        base: BaseUrl = "main",
+        api_namespace: str = "api",
+    ) -> Any:
+        """Perform a GET request and return parsed JSON."""
+
+        url = self._build_url(endpoint, requires_auth, base, api_namespace)
+        response = requests.get(
+            url,
+            params=self._filter_params(params),
+            timeout=self._timeout,
+            headers={"Accept": "application/json"},
+        )
+        return self._handle_response(response, endpoint)
+
+    def post(
+        self,
+        endpoint: str,
+        body: Any,
+        *,
+        requires_auth: bool = False,
+        base: BaseUrl = "main",
+        api_namespace: str = "api",
+    ) -> Any:
+        """Perform a POST request and return parsed JSON."""
+
+        url = self._build_url(endpoint, requires_auth, base, api_namespace)
+        response = requests.post(
+            url,
+            json=body,
+            timeout=self._timeout,
+            headers={
+                "Accept": "application/json",
+                "Content-Type": "application/json",
+            },
+        )
+        return self._handle_response(response, endpoint)

defillama_api/constants/__init__.py

@@ -0,0 +1,11 @@
+"""Constants for DefiLlama API dimensions."""
+
+from .dimensions import AdapterType, FeeDataType, VolumeDataType, DataTypeShortKeys, DataTypeShortKey
+
+__all__ = [
+    "AdapterType",
+    "FeeDataType",
+    "VolumeDataType",
+    "DataTypeShortKeys",
+    "DataTypeShortKey",
+]

defillama_api/constants/dimensions.py

@@ -0,0 +1,69 @@
+"""Dimension constants used by fees and volume endpoints."""
+
+from enum import Enum
+from typing import Dict, Literal
+
+
+class AdapterType(str, Enum):
+    DEXS = "dexs"
+    FEES = "fees"
+    AGGREGATORS = "aggregators"
+    DERIVATIVES = "derivatives"
+    AGGREGATOR_DERIVATIVES = "aggregator-derivatives"
+    OPTIONS = "options"
+    BRIDGE_AGGREGATORS = "bridge-aggregators"
+    OPEN_INTEREST = "open-interest"
+
+
+class FeeDataType(str, Enum):
+    DAILY_FEES = "dailyFees"
+    DAILY_REVENUE = "dailyRevenue"
+    DAILY_HOLDERS_REVENUE = "dailyHoldersRevenue"
+    DAILY_SUPPLY_SIDE_REVENUE = "dailySupplySideRevenue"
+    DAILY_BRIBES_REVENUE = "dailyBribesRevenue"
+    DAILY_TOKEN_TAXES = "dailyTokenTaxes"
+    DAILY_APP_FEES = "dailyAppFees"
+    DAILY_APP_REVENUE = "dailyAppRevenue"
+    DAILY_EARNINGS = "dailyEarnings"
+
+
+class VolumeDataType(str, Enum):
+    DAILY_VOLUME = "dailyVolume"
+    TOTAL_VOLUME = "totalVolume"
+    DAILY_NOTIONAL_VOLUME = "dailyNotionalVolume"
+    DAILY_PREMIUM_VOLUME = "dailyPremiumVolume"
+    DAILY_BRIDGE_VOLUME = "dailyBridgeVolume"
+    OPEN_INTEREST_AT_END = "openInterestAtEnd"
+
+
+DataTypeShortKeys: Dict[str, str] = {
+    "dailyFees": "df",
+    "dailyRevenue": "dr",
+    "dailyHoldersRevenue": "dhr",
+    "dailySupplySideRevenue": "dssr",
+    "dailyBribesRevenue": "dbr",
+    "dailyTokenTaxes": "dtt",
+    "dailyAppRevenue": "dar",
+    "dailyAppFees": "daf",
+    "dailyNotionalVolume": "dnv",
+    "dailyPremiumVolume": "dpv",
+    "openInterestAtEnd": "doi",
+    "dailyVolume": "dv",
+    "dailyBridgeVolume": "dbv",
+}
+
+DataTypeShortKey = Literal[
+    "dailyFees",
+    "dailyRevenue",
+    "dailyHoldersRevenue",
+    "dailySupplySideRevenue",
+    "dailyBribesRevenue",
+    "dailyTokenTaxes",
+    "dailyAppRevenue",
+    "dailyAppFees",
+    "dailyNotionalVolume",
+    "dailyPremiumVolume",
+    "openInterestAtEnd",
+    "dailyVolume",
+    "dailyBridgeVolume",
+]

defillama_api/errors.py

@@ -0,0 +1,41 @@
+"""Error types for the DefiLlama SDK."""
+
+from typing import Optional
+
+
+class DefiLlamaError(Exception):
+    """Base error class for DefiLlama SDK errors."""
+
+    def __init__(self, message: str) -> None:
+        super().__init__(message)
+
+
+class ApiKeyRequiredError(DefiLlamaError):
+    """Raised when a Pro API key is required for an endpoint."""
+
+    def __init__(self, endpoint: str) -> None:
+        super().__init__(f"API key required for endpoint: {endpoint}")
+
+
+class RateLimitError(DefiLlamaError):
+    """Raised when the API rate limit is exceeded."""
+
+    def __init__(self, retry_after: Optional[int] = None) -> None:
+        super().__init__("Rate limit exceeded")
+        self.retry_after = retry_after
+
+
+class NotFoundError(DefiLlamaError):
+    """Raised when a requested resource is not found."""
+
+    def __init__(self, resource: str) -> None:
+        super().__init__(f"Resource not found: {resource}")
+
+
+class ApiError(DefiLlamaError):
+    """Raised for non-success API responses."""
+
+    def __init__(self, status_code: int, message: str, response: Optional[object] = None) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+        self.response = response

defillama_api/modules/__init__.py

@@ -0,0 +1,29 @@
+"""Module exports for the DefiLlama SDK."""
+
+from .account import AccountModule
+from .bridges import BridgesModule
+from .dat import DatModule
+from .ecosystem import EcosystemModule
+from .emissions import EmissionsModule
+from .etfs import EtfsModule
+from .fees import FeesModule
+from .prices import PricesModule
+from .stablecoins import StablecoinsModule
+from .tvl import TvlModule
+from .volumes import VolumesModule
+from .yields import YieldsModule
+
+__all__ = [
+    "AccountModule",
+    "BridgesModule",
+    "DatModule",
+    "EcosystemModule",
+    "EmissionsModule",
+    "EtfsModule",
+    "FeesModule",
+    "PricesModule",
+    "StablecoinsModule",
+    "TvlModule",
+    "VolumesModule",
+    "YieldsModule",
+]

defillama_api/modules/account.py

@@ -0,0 +1,29 @@
+"""Account module implementation."""
+
+import requests
+
+from ..client import BaseClient
+from ..errors import ApiKeyRequiredError, ApiError
+from ..types.account import UsageResponse
+
+
+class AccountModule:
+    """Access API account and usage data."""
+
+    def __init__(self, client: BaseClient) -> None:
+        self._client = client
+
+    def getUsage(self) -> UsageResponse:
+        """Get API usage statistics for the configured key."""
+
+        api_key = self._client.get_api_key()
+        if not api_key:
+            raise ApiKeyRequiredError("/usage")
+        response = requests.get(
+            f"https://pro-api.llama.fi/usage/{api_key}",
+            headers={"Accept": "application/json"},
+            timeout=self._client.timeout,
+        )
+        if not response.ok:
+            raise ApiError(response.status_code, f"Failed to fetch usage: {response.reason}")
+        return response.json()

defillama_api/modules/bridges.py

@@ -0,0 +1,81 @@
+"""Bridges module implementation."""
+
+from typing import List, Optional
+from urllib.parse import quote
+
+from ..client import BaseClient
+from ..types.bridges import (
+    BridgeDayStatsResponse,
+    BridgeDetail,
+    BridgeTransaction,
+    BridgeTransactionsOptions,
+    BridgeVolumeDataPoint,
+    BridgesOptions,
+    BridgesResponse,
+)
+
+
+class BridgesModule:
+    """Access bridge volume and transaction data."""
+
+    def __init__(self, client: BaseClient) -> None:
+        self._client = client
+
+    def getAll(self, options: Optional[BridgesOptions] = None) -> BridgesResponse:
+        """Get all bridges with volume data."""
+
+        params = None
+        if options and options.get("includeChains") is not None:
+            params = {"includeChains": options.get("includeChains")}
+        return self._client.get(
+            "/bridges",
+            base="bridges",
+            params=params,
+        )
+
+    def getById(self, bridge_id: int) -> BridgeDetail:
+        """Get detailed bridge information by ID."""
+
+        return self._client.get(
+            f"/bridge/{bridge_id}",
+            base="bridges",
+        )
+
+    def getVolumeByChain(self, chain: str) -> List[BridgeVolumeDataPoint]:
+        """Get bridge volume for a chain."""
+
+        return self._client.get(
+            f"/bridgevolume/{quote(chain)}",
+            base="bridges",
+        )
+
+    def getDayStats(self, timestamp: int, chain: str) -> BridgeDayStatsResponse:
+        """Get daily bridge statistics for a chain."""
+
+        return self._client.get(
+            f"/bridgedaystats/{timestamp}/{quote(chain)}",
+            base="bridges",
+        )
+
+    def getTransactions(
+        self, bridge_id: int, options: Optional[BridgeTransactionsOptions] = None
+    ) -> List[BridgeTransaction]:
+        """Get bridge transactions."""
+
+        params = {}
+        if options:
+            if options.get("limit") is not None:
+                params["limit"] = options.get("limit")
+            if options.get("startTimestamp") is not None:
+                params["startTimestamp"] = options.get("startTimestamp")
+            if options.get("endTimestamp") is not None:
+                params["endTimestamp"] = options.get("endTimestamp")
+            if options.get("sourceChain"):
+                params["sourceChain"] = options.get("sourceChain")
+            if options.get("address"):
+                params["address"] = options.get("address")
+        return self._client.get(
+            f"/transactions/{bridge_id}",
+            base="bridges",
+            params=params or None,
+        )

defillama_api/modules/dat.py

@@ -0,0 +1,31 @@
+"""DAT module implementation."""
+
+from urllib.parse import quote
+
+from ..client import BaseClient
+from ..types.dat import DatInstitutionResponse, DatInstitutionsResponse
+
+
+class DatModule:
+    """Access Digital Asset Treasury data from DefiLlama."""
+
+    def __init__(self, client: BaseClient) -> None:
+        self._client = client
+
+    def getInstitutions(self) -> DatInstitutionsResponse:
+        """Get comprehensive DAT data for all institutions."""
+
+        return self._client.get(
+            "/dat/institutions",
+            requires_auth=True,
+            api_namespace="",
+        )
+
+    def getInstitution(self, symbol: str) -> DatInstitutionResponse:
+        """Get detailed DAT data for a specific institution."""
+
+        return self._client.get(
+            f"/dat/institutions/{quote(symbol)}",
+            requires_auth=True,
+            api_namespace="",
+        )

defillama_api/modules/ecosystem.py

@@ -0,0 +1,54 @@
+"""Ecosystem module implementation."""
+
+from ..client import BaseClient
+from ..types.ecosystem import (
+    CategoriesResponse,
+    Entity,
+    ForksResponse,
+    Hack,
+    OraclesResponse,
+    RaisesResponse,
+    Treasury,
+)
+
+
+class EcosystemModule:
+    """Access ecosystem-level data from DefiLlama."""
+
+    def __init__(self, client: BaseClient) -> None:
+        self._client = client
+
+    def getCategories(self) -> CategoriesResponse:
+        """Get TVL grouped by protocol category."""
+
+        return self._client.get("/categories", requires_auth=True)
+
+    def getForks(self) -> ForksResponse:
+        """Get protocol fork relationships and TVL."""
+
+        return self._client.get("/forks", requires_auth=True)
+
+    def getOracles(self) -> OraclesResponse:
+        """Get oracle usage data across protocols."""
+
+        return self._client.get("/oracles", requires_auth=True)
+
+    def getEntities(self) -> list[Entity]:
+        """Get entity treasury and holdings data."""
+
+        return self._client.get("/entities", requires_auth=True)
+
+    def getTreasuries(self) -> list[Treasury]:
+        """Get protocol treasury balances."""
+
+        return self._client.get("/treasuries", requires_auth=True)
+
+    def getHacks(self) -> list[Hack]:
+        """Get security incidents and exploit data."""
+
+        return self._client.get("/hacks", requires_auth=True)
+
+    def getRaises(self) -> RaisesResponse:
+        """Get funding rounds database."""
+
+        return self._client.get("/raises", requires_auth=True)

defillama_api/modules/emissions.py

@@ -0,0 +1,32 @@
+"""Emissions module implementation."""
+
+import json
+from urllib.parse import quote
+
+from ..client import BaseClient
+from ..types.emissions import EmissionDetailResponse, EmissionToken
+
+
+class EmissionsModule:
+    """Access emission and unlock schedule data."""
+
+    def __init__(self, client: BaseClient) -> None:
+        self._client = client
+
+    def getAll(self) -> list[EmissionToken]:
+        """Get all tokens with unlock schedules."""
+
+        return self._client.get("/emissions", requires_auth=True)
+
+    def getByProtocol(self, protocol: str) -> EmissionDetailResponse:
+        """Get detailed emission data for a protocol."""
+
+        response = self._client.get(
+            f"/emission/{quote(protocol)}",
+            requires_auth=True,
+        )
+        body = json.loads(response.get("body", "{}"))
+        return {
+            "body": body,
+            "lastModified": response.get("lastModified"),
+        }

defillama_api/modules/etfs.py

@@ -0,0 +1,58 @@
+"""ETFs module implementation."""
+
+from urllib.parse import quote
+
+from ..client import BaseClient
+from ..types.etfs import EtfHistoryItem, EtfOverviewItem, FdvPeriod, FdvPerformanceItem
+
+
+class EtfsModule:
+    """Access ETF data from DefiLlama."""
+
+    def __init__(self, client: BaseClient) -> None:
+        self._client = client
+
+    def getOverview(self) -> list[EtfOverviewItem]:
+        """Get Bitcoin ETF overview."""
+
+        return self._client.get(
+            "/overview",
+            requires_auth=True,
+            api_namespace="etfs",
+        )
+
+    def getOverviewEth(self) -> list[EtfOverviewItem]:
+        """Get Ethereum ETF overview."""
+
+        return self._client.get(
+            "/overviewEth",
+            requires_auth=True,
+            api_namespace="etfs",
+        )
+
+    def getHistory(self) -> list[EtfHistoryItem]:
+        """Get Bitcoin ETF flow history."""
+
+        return self._client.get(
+            "/history",
+            requires_auth=True,
+            api_namespace="etfs",
+        )
+
+    def getHistoryEth(self) -> list[EtfHistoryItem]:
+        """Get Ethereum ETF flow history."""
+
+        return self._client.get(
+            "/historyEth",
+            requires_auth=True,
+            api_namespace="etfs",
+        )
+
+    def getFdvPerformance(self, period: FdvPeriod) -> list[FdvPerformanceItem]:
+        """Get FDV performance data."""
+
+        return self._client.get(
+            f"/performance/{quote(period)}",
+            requires_auth=True,
+            api_namespace="fdv",
+        )