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