FIVA
  • FIVA Overview
    • Introduction
    • Problem & Solution
    • Importance to the Space
  • FIVA Mechanics
    • Glossary
    • Understanding the Basics
    • Protocol Components
      • SY (Standardized Yield Token)
      • Yield Stripping
      • PT (Principal Token)
      • YT (Yield Token)
      • FIVA's AMM Design
    • Fee Structure
    • P&L in FIVA
    • FAQ
  • FIVA Manual
    • Getting Started
    • Use Cases
    • PT - Fixing Yield
    • YT - Leveraged Yield Farming
    • LP - Liquidity Provision
    • Mint - Get Liquidity from Future Yields Today
    • Arbitrage Opportunities
  • FIVA Strategies
    • EVAA
      • PT - Fixed USDT Yield
      • YT - EVAA Point Farming with up to 250x Multiplier
      • LP - Enhancing Your EVAA Returns
      • Mint - Get you Future USDT Yield now
    • Ethena
      • PT - Fixed USDe Returns
      • YT - Farming Ethena Airdrop with 60x Multiplier
      • LP - Multiple Income Streams
    • Storm Trade
      • PT - Fixed Yield on SLP
      • YT - Efficient Reward & Yield Farming on Storm
      • LP - Maximizing Returns from Storm Vaults
      • Max Supply - Determination Framework for Storm SLP Market
    • Tonstakers
      • LP - Enhancing Your Tonstakers Returns
  • FIVA Rewards
    • The Points System
    • Genesis Pass Collection
  • FIVA Pioneers Campaign
  • Security
    • Risks
      • Smart Contract Risk
      • Underlying Protocol Risk
      • Oracle Risk
      • PT Risks
        • Market Risk
        • Liquidity Risk
      • YT Risks
        • Market Risk
        • Implied Leverage
        • Zero Value at Maturity
        • Liquidity Risk
      • LP Risks
        • Impermanent Loss
        • Market Risk
        • Additional Considerations for LPs
    • Audit Report - Tonbit
  • Developers
    • SDK
    • npm package
    • Integrating Fixed-Rate Staking
      • SDK - Guide for Fixed Staking
      • API - Pools Metrics Endpoint
  • Links
    • Website
    • Telegram App
    • Telegram Channel
    • Telegram Community
    • X (Twitter)
Powered by GitBook
On this page
  1. Developers
  2. Integrating Fixed-Rate Staking

API - Pools Metrics Endpoint

Description

This endpoint provides information about all active assets in the protocol or a specific asset by its SY address. For each asset, it returns data about the PT token price in USD, pool liquidity, fixed annual percentage rate (APR), and addresses of all related tokens.

When requesting a specific asset by SY address, the endpoint will return the asset even if it's matured (expired). For matured assets, the values of pt_price_usd, pool_liquidity_usd, and fixed_apr will be set to 0.

URL

GET https://api2.thefiva.com/protocol_metrics

Request Parameters

  • sy_address (optional): SY token address. If specified, only the asset with this address will be returned (active or matured).

Example Requests

  1. Get all assets:

    GET https://api2.thefiva.com/protocol_metrics
  2. Get a specific asset by SY address:

    GET https://api2.thefiva.com/protocol_metrics?sy_address=EQDi9blCcyT-k8iMpFMYY0t7mHVyiCB50ZsRgyUECJDuGvIl

Example Response

{
  "assets": [
    {
      "sy_address": "EQDi9blCcyT-k8iMpFMYY0t7mHVyiCB50ZsRgyUECJDuGvIl",
      "service": "evaa",
      "maturity_date": "2025-06-01T22:00:00Z",
      "pt_price_usd": 0.994067,
      "pool_liquidity_usd": 529344.539144,
      "fixed_apr": 16.971389,
      "jettons": {
        "underlying_jetton": {
          "master_address": "EQCxE6mUtQJKFnGfaROTKOt1lZbDiiX1kCixRv7Nw2Id_sDs",
          "decimals": 6
        },
        "sy": {
          "master_address": "EQDi9blCcyT-k8iMpFMYY0t7mHVyiCB50ZsRgyUECJDuGvIl",
          "decimals": 9
        },
        "pt": {
          "master_address": "EQBzVrYkYPHx8D_HPfQacm1xONa4XSRxl826vHkx_laP2HOe",
          "decimals": 9
        },
        "yt": {
          "master_address": "EQCwUSc2qrY5rn9BfFBG9ARAHePTUvITDl97UD0zOreWzLru",
          "decimals": 9
        },
        "lp": {
          "master_address": "EQBNlIZxIbQGQ78cXgG3VRcyl8A0kLn_6BM9kabiHHhWC4qY",
          "decimals": 9
        }
      }
    }
  ],
  "count": 4,
  "current_utc": "2025-05-09T11:17:06.044439+00:00"
}

Response Fields Explanation

The response contains the following key information:

  • assets: Array of asset objects with details about each available asset

    • sy_address: The address of the SY (Standardized Yield) token

    • service: The service provider for the asset (e.g., "evaa")

    • maturity_date: ISO-formatted date when the fixed-rate position will mature

    • pt_price_usd: Current price of PT tokens in USD

    • pool_liquidity_usd: Total liquidity in the pool in USD

    • fixed_apr: Current fixed APR (annual percentage rate) offered for this asset

    • jettons: Object containing address information for all related tokens:

      • underlying_jetton: The base asset (e.g., USDT)

      • sy: The Standardized Yield token

      • pt: Principal Token (represents the fixed-rate position)

      • yt: Yield Token

      • lp: Liquidity Provider token

  • count: Total number of assets returned

  • current_utc: Current UTC timestamp when the request was processed

Response Codes

  • 200 OK: Request successfully processed

  • 404 Not Found: Asset with the specified SY address not found

  • 500 Internal Server Error: Server error

Usage in Integration

For integration purposes, this API endpoint is especially useful for:

  1. Retrieving current fixed APRs across all available assets

  2. Getting information about pool liquidity to show available capacity

  3. Obtaining all token addresses needed for integration

  4. Calculating time remaining until maturity for active fixed-rate positions

Implementation Example

Here's an example of how to fetch data from the API in JavaScript:

async function getFivaProtocolMetrics(syAddress = null) {
  let url = 'https://api2.thefiva.com/protocol_metrics';
  
  if (syAddress) {
    url += `?sy_address=${syAddress}`;
  }
  
  try {
    const response = await fetch(url);
    
    if (!response.ok) {
      throw new Error(`API error: ${response.status}`);
    }
    
    const data = await response.json();
    return data;
  } catch (error) {
    console.error('Failed to fetch protocol metrics:', error);
    throw error;
  }
}

// Example usage:
// Get all assets
getFivaProtocolMetrics().then(data => {
  console.log(`Found ${data.count} active assets`);
  
  // Find highest APR asset
  const highestAprAsset = data.assets.reduce((highest, current) => {
    return current.fixed_apr > highest.fixed_apr ? current : highest;
  }, data.assets[0]);
  
  console.log(`Highest APR: ${highestAprAsset.fixed_apr}% for asset at ${highestAprAsset.sy_address}`);
});

// Get specific asset
getFivaProtocolMetrics('EQDi9blCcyT-k8iMpFMYY0t7mHVyiCB50ZsRgyUECJDuGvIl').then(data => {
  const asset = data.assets[0];
  console.log(`Fixed APR for USDT-EVAA: ${asset.fixed_apr}%`);
  console.log(`Maturity date: ${asset.maturity_date}`);
  console.log(`Pool liquidity: $${asset.pool_liquidity_usd.toLocaleString()}`);
});

Notes

  • For matured assets, the values of pt_price_usd, pool_liquidity_usd, and fixed_apr will be 0

  • The API should be called periodically to get updated APR and liquidity information

  • Always handle API errors gracefully in your implementation

PreviousSDK - Guide for Fixed Staking

Last updated 7 days ago

If you have questions about the integration process or need support, please contact andrei.yazepchyk@thefiva.com or join our .

community on Telegram