@lombard.finance/sdk 3.6.2 → 3.6.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lombard.finance/sdk",
-  "version": "3.6.2",
+  "version": "3.6.3",
   "dependencies": {
     "@lombard.finance/sdk-common": "^3.0.0",
     "viem": "^2.23.15",

package/src/index.ts

@@ -30,7 +30,16 @@ export * from './utils/satoshi';
 
 // Metrics:
 export { getLBTCStats } from './metrics/get-lbtc-stats';
-export { getRewardsInfo } from './metrics/get-rewards-info';
+
+export {
+  getPositionsSummary,
+  type PositionsSummary,
+} from './metrics/get-positions-summary';
+export { getApy, type LbtcApy } from './metrics/get-lbtc-apy';
+export {
+  getAdditionalRewards,
+  type RewardsDistribution,
+} from './metrics/get-additional-rewards';
 
 // Re-exports:
 export type { Address, EIP1193Provider } from 'viem';

package/src/metrics/get-additional-rewards.ts

@@ -0,0 +1,68 @@
+import { Address } from 'viem';
+import axios from 'axios';
+import { getApiConfig } from '../common/api-config';
+import { IEnvParam } from '../common/parameters';
+import BigNumber from 'bignumber.js';
+
+type Response = {
+  btc_distributed: { name: string; amount: number }[];
+  btc_undistributed: { name: string; amount: number }[];
+};
+
+export type RewardsDistribution = {
+  /**
+   * List of campaigns where rewards have been successfully distributed.
+   */
+  distributed: {
+    /** Name of the reward campaign. */
+    name: string;
+    /** Amount of BTC distributed for this campaign. */
+    amount: BigNumber;
+  }[];
+
+  /**
+   * List of campaigns where rewards are pending or not yet distributed.
+   */
+  undistributed: {
+    /** Name of the reward campaign. */
+    name: string;
+    /** Amount of BTC yet to be distributed. */
+    amount: BigNumber;
+  }[];
+};
+
+/**
+ * Retrieves additional rewards that have been distributed or are pending
+ * for a specific account.
+ */
+export async function getAdditionalRewards({
+  account,
+  env,
+}: {
+  account: Address;
+} & IEnvParam) {
+  if (!account) {
+    throw new Error('Missing account address');
+  }
+
+  const { baseApiUrl } = getApiConfig(env);
+
+  const url = `${baseApiUrl}/api/v1/analytics/${account}/additional-rewards`;
+  const { data } = await axios.get<Response>(url);
+
+  const distribution: RewardsDistribution = {
+    distributed: data.btc_distributed.map(d => ({
+      amount: BigNumber(d.amount),
+      name: d.name,
+    })),
+    undistributed: data.btc_undistributed.map(u => ({
+      amount: BigNumber(u.amount),
+      name: u.name,
+    })),
+  };
+
+  return distribution;
+}
+
+// url: https://bft-dev.stage.lombard.finance/api/v1/analytics/0x2513196b4fD01Ed5888d1dB49AB9a42208E9fF90/additional-rewards
+// {"btc_distributed":[{"name":"ledger", "amount":0.7691864317643695}], "btc_undistributed":[{"name":"ledger", "amount":0.5699985451505658}]}

package/src/metrics/get-lbtc-apy.ts

@@ -0,0 +1,47 @@
+import axios from 'axios';
+import { Address, zeroAddress } from 'viem';
+import BigNumber from 'bignumber.js';
+import { getApiConfig } from '../common/api-config';
+import { IEnvParam } from '../common/parameters';
+
+type Response = {
+  lbtc_base_apy: number;
+  lbtc_effective_apy: number;
+};
+
+export type LbtcApy = {
+  /**
+   * The base APY for LBTC, representing the nominal yield without any bonuses
+   * or adjustments.
+   */
+  baseApy: BigNumber;
+  /**
+   * The effective APY for LBTC, including any additional rewards,
+   * compounding effects, or protocol-specific incentives.
+   */
+  effectiveApy: BigNumber;
+};
+
+/** Returns the current APY (annual percentage yield) for LBTC. */
+export async function getApy({
+  account,
+  env,
+}: {
+  /** The optional account address. Pass it for more accurate APY data. */
+  account?: Address;
+} & IEnvParam) {
+  const { baseApiUrl } = getApiConfig(env);
+
+  const url = `${baseApiUrl}/api/v1/analytics/${account || zeroAddress}/apy`;
+  const { data } = await axios.get<Response>(url);
+
+  const apy: LbtcApy = {
+    baseApy: BigNumber(data.lbtc_base_apy),
+    effectiveApy: BigNumber(data.lbtc_effective_apy),
+  };
+
+  return apy;
+}
+
+// url: https://bft-dev.stage.lombard.finance/api/v1/analytics/0x2513196b4fD01Ed5888d1dB49AB9a42208E9fF90/apy
+// {"lbtc_base_apy":0.18849167223827507, "lbtc_effective_apy":0.6828761605761976}

package/src/metrics/get-lbtc-stats.ts

@@ -7,10 +7,6 @@ type LBTCStatsResponse = { price: number; supply: number; tvl: number }[];
 
 type LBTCHoldersResponse = number;
 
-type StakingStatsResponse = {
-  apr: number;
-};
-
 type Stats = {
   /** The BTC price  */
   price: BigNumber;
@@ -22,8 +18,6 @@ type Stats = {
   holders: BigNumber;
   /** The total (historical) number of LBTC holders */
   historicalHolders: BigNumber;
-  /** The staking APR */
-  apr: BigNumber | undefined;
 };
 
 /** Gets the Lombard's TVL. */
@@ -32,7 +26,6 @@ export async function getLBTCStats(
 ) {
   const env = parameters?.env;
   const partnerId = parameters?.partnerId;
-  const accountAddress = parameters?.accountAddress;
 
   const { bffApiUrl } = getApiConfig(env);
   if (!bffApiUrl) {
@@ -53,23 +46,12 @@ export async function getLBTCStats(
     `${bffApiUrl}/dune-api/query/getTotalLBTCUsers?partnerId=${partnerId || ''}`,
   );
 
-  let apr = undefined;
-  try {
-    const { data: stakingStats } = await axios.get<StakingStatsResponse>(
-      `${bffApiUrl}/lombard-sdk/staking-stats?partnerId=${partnerId || ''}&accountAddress=${accountAddress}&env=${env}`,
-    );
-    apr = stakingStats.apr;
-  } catch (_err) {
-    // NOOP
-  }
-
   const stats: Stats = {
     price: BigNumber(data[0].price),
     supply: BigNumber(data[0].supply),
     tvl: BigNumber(data[0].tvl),
     holders: BigNumber(holders),
     historicalHolders: BigNumber(historicalHolders),
-    apr: apr ? BigNumber(apr) : undefined,
   };
 
   return stats;

package/src/metrics/{get-rewards-info.stories.tsx → get-positions-summary.stories.tsx}

@@ -4,13 +4,13 @@ import { CodeBlock } from '../stories/components/CodeBlock';
 import useQuery from '../stories/hooks/useQuery';
 import { functionType, wagmiDecorator } from '../stories/components/decorators';
 import { ErrorBlock } from '../stories/components/error-block';
-import { getRewardsInfo } from './get-rewards-info';
+import { getPositionsSummary } from './get-positions-summary';
 import { EXAMPLE_EVM_ADDRESS } from '../stories/constants';
 import { envSelector } from '../stories/arg-types';
 import { Env } from '@lombard.finance/sdk-common';
 
 const meta = {
-  title: 'metrics/getRewardsInfo',
+  title: 'metrics/getPositionsSummary',
   component: StoryView,
   tags: ['autodocs'],
   decorators: [wagmiDecorator, functionType('api-get')],
@@ -25,11 +25,11 @@ export const WithParams: Story = {
   args: { account: EXAMPLE_EVM_ADDRESS, env: Env.stage },
 };
 
-type SignNetworkFeeProps = Parameters<typeof getRewardsInfo>[0];
+type SignNetworkFeeProps = Parameters<typeof getPositionsSummary>[0];
 
 export function StoryView(props: SignNetworkFeeProps) {
   const request = async () => {
-    return getRewardsInfo({
+    return getPositionsSummary({
       ...props,
     });
   };
@@ -46,7 +46,7 @@ export function StoryView(props: SignNetworkFeeProps) {
         onClick={refetch}
         disabled={isLoading}
         isLoading={isLoading}
-        actionName={getRewardsInfo.name}
+        actionName={getPositionsSummary.name}
       />
 
       <ErrorBlock>{error}</ErrorBlock>

package/src/metrics/get-positions-summary.ts

@@ -0,0 +1,134 @@
+import axios from 'axios';
+import BigNumber from 'bignumber.js';
+import { Address } from 'viem';
+import { getApiConfig } from '../common/api-config';
+import { IEnvParam } from '../common/parameters';
+import { Token } from '../tokens/token-addresses';
+
+type PositionAsset = 'ASSET_LBTC' | 'ASSET_UNSPECIFIED';
+type PositionType = 'BALANCE_TYPE_HOLDING' | 'BALANCE_TYPE_DEFI';
+
+type Response = {
+  btc_price_usd: { price: number; timestamp: string };
+  btc_value: number;
+  btc_pnl: number;
+  snapshot: [
+    {
+      asset: PositionAsset;
+      type: PositionType;
+      balance: number;
+      pnl: number;
+      rate: number;
+    },
+  ];
+  last_updated: string;
+};
+
+function mapRewardAssetToToken(asset: PositionAsset) {
+  switch (asset) {
+    case 'ASSET_LBTC':
+      return Token.LBTC;
+    default:
+      return undefined;
+  }
+}
+
+export type PositionsSummary = {
+  /**
+   * The current BTC price in USD, along with the timestamp
+   * when the price was last fetched.
+   */
+  btcPrice: {
+    /** The price of 1 BTC in USD. */
+    price: BigNumber;
+    /** Timestamp of the price data. */
+    timestamp: Date;
+  };
+  /**
+   * Total value of all holdings, denominated in BTC.
+   */
+  btcValue: BigNumber;
+  /**
+   * Total profit or loss across all assets, represented in BTC.
+   */
+  btcPnl: BigNumber;
+  /**
+   * A detailed snapshot of position data used in PnL calculation.
+   */
+  snapshot: {
+    /**
+     * The token associated with this position (e.g., `Token.LBTC`).
+     * Can be `undefined` if unspecified.
+     */
+    token: Token | undefined;
+    /**
+     * The classification or source of the position.
+     */
+    type: PositionType;
+    /**
+     * The quantity of the token held.
+     */
+    balance: BigNumber;
+    /**
+     * The profit or loss for this specific position, in BTC.
+     */
+    pnl: BigNumber;
+    /**
+     * The conversion rate used to determine the BTC value of the balance.
+     * `balance * rate = BTC equivalent`
+     */
+    rate: BigNumber;
+  }[];
+  /**
+   * The timestamp when the PnL data was last updated.
+   */
+  lastUpdated: Date;
+};
+
+/** Retrieves the yield positions summary for the specified account address. */
+export async function getPositionsSummary({
+  account,
+  env,
+}: { account: Address } & IEnvParam) {
+  const { baseApiUrl } = getApiConfig(env);
+
+  const url = `${baseApiUrl}/api/v1/analytics/${account}/summary`;
+  const { data } = await axios.get<Response>(url);
+
+  const info: PositionsSummary = {
+    btcPrice: {
+      price: BigNumber(data.btc_price_usd.price || 0),
+      timestamp: new Date(data.btc_price_usd.timestamp),
+    },
+    btcValue: BigNumber(data.btc_value || 0),
+    btcPnl: BigNumber(data.btc_pnl || 0),
+    snapshot: data.snapshot.map(ds => ({
+      token: mapRewardAssetToToken(ds.asset),
+      type: ds.type,
+      balance: BigNumber(ds.balance || 0),
+      pnl: BigNumber(ds.pnl || 0),
+      rate: BigNumber(ds.rate || 0),
+    })),
+    lastUpdated: new Date(data.last_updated),
+  };
+
+  return info;
+}
+
+// Response example:
+// url: https://bft-dev.stage.lombard.finance/api/v1/analytics/0x2513196b4fD01Ed5888d1dB49AB9a42208E9fF90/summary
+// {
+//   btc_price_usd: { price: 118395.552997, timestamp: '2025-07-23T11:01:59Z' },
+//   btc_value: 0.0003895271690089053,
+//   btc_pnl: 8.716900890527854e-8,
+//   snapshot: [
+//     {
+//       asset: 'ASSET_LBTC',
+//       type: 'BALANCE_TYPE_HOLDING',
+//       balance: 0.00038944,
+//       pnl: 8.716900890527854e-8,
+//       rate: 1.0002238316785776,
+//     },
+//   ],
+//   last_updated: '2025-07-23T11:38:52.516364988Z',
+// }

package/src/metrics/get-rewards-info.ts

@@ -1,72 +0,0 @@
-import axios from 'axios';
-import BigNumber from 'bignumber.js';
-import { Address } from 'viem';
-import { getApiConfig } from '../common/api-config';
-import { IEnvParam } from '../common/parameters';
-import { BlockchainIdentifier } from '../common/blockchain-identifier';
-
-type Response = {
-  btc_price_usd: { price: number; timestamp: string };
-  staked_balance: number;
-  rewards: number;
-  chain_breakdown: {
-    staked_balance: number;
-    rewards: number;
-    chain: BlockchainIdentifier;
-  }[];
-  last_updated: string;
-};
-
-/**
- * Gets the rewards info acquired by provided account address
- *
- * @experimental This function is not ready to be used in prod environment and will result with static and dummy data. Please do not rely on the data it returns.
- */
-export async function getRewardsInfo({
-  account,
-  env,
-}: { account: Address } & IEnvParam) {
-  const { baseApiUrl } = getApiConfig(env);
-
-  const url = `${baseApiUrl}/api/v1/accounts/${account}/summary`;
-  const { data } = await axios.get<Response>(url);
-
-  const info = {
-    btcPrice: {
-      price: BigNumber(data.btc_price_usd.price || 0),
-      timestamp: new Date(data.btc_price_usd.timestamp),
-    },
-    stakedBalance: BigNumber(data.staked_balance || 0),
-    totalRewards: BigNumber(data.rewards || 0),
-    chainBreakdown: data.chain_breakdown?.map(cd => ({
-      stakedBalance: BigNumber(cd.staked_balance || 0),
-      rewards: BigNumber(cd.rewards || 0),
-      chain: cd.chain,
-    })),
-    lastUpdated: new Date(data.last_updated),
-  };
-
-  return info;
-}
-
-// Response example:
-// url: https://bft-dev.stage.lombard.finance/api/v1/accounts/0x2513196b4fD01Ed5888d1dB49AB9a42208E9fF90/summary
-//
-// {
-//   btc_price_usd: { price: 118597.502311, timestamp: '2025-07-22T14:17:23Z' },
-//   staked_balance: 0.00038944,
-//   rewards: 8.716900890527854e-8,
-//   chain_breakdown: [
-//     {
-//       staked_balance: 0.00018844,
-//       rewards: 4.217884151117165e-8,
-//       chain: 'DESTINATION_BLOCKCHAIN_BSC',
-//     },
-//     {
-//       staked_balance: 0.000201,
-//       rewards: 4.4990167394106886e-8,
-//       chain: 'DESTINATION_BLOCKCHAIN_ETHEREUM',
-//     },
-//   ],
-//   last_updated: '2025-07-22T15:07:20.502595933Z',
-// }