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
  • Getting Started with the SDK
  • Client Initialization
  • Implementing Core Fixed Staking Functions
  • Understanding Minimum Amount Out and Slippage Protection
  • Complete Integration Example
  • Testing Your Integration
  1. Developers
  2. Integrating Fixed-Rate Staking

SDK - Guide for Fixed Staking

This guide provides a detailed walkthrough of integrating FIVA's fixed staking functionality into your platform using our SDK. We'll cover the full implementation process with code examples and best practices.

Getting Started with the SDK

First, install the FIVA SDK in your project:

npm install @fiva/sdk
# or
yarn add @fiva/sdk
# or
pnpm install @fiva/sdk

Client Initialization

The first step is to initialize the FIVA client with your wallet connector, TON client, and the SY address for the asset you want to work with:

import { FivaClient } from '@fiva/sdk';
import { Address, TonClient4 } from '@ton/ton';

// Initialize TON client
const tonClient = new TonClient4({ 
  endpoint: 'https://mainnet-v4.tonhubapi.com' 
});

// Initialize FIVA client for USDT-EVAA fixed staking
const fivaClient = new FivaClient({ 
  connector, // Your wallet connector
  tonClient,
  syAddress: Address.parse('EQDi9blCcyT-k8iMpFMYY0t7mHVyiCB50ZsRgyUECJDuGvIl') // USDT-EVAA SY address
});

You can find all supported SY addresses at:

Implementing Core Fixed Staking Functions

Let's implement the three core functions needed for fixed staking:

1. Stake (Fixed Yield)

This function allows users to lock in current rates by swapping their asset for PT tokens:

import { FivaAsset } from '@fiva/sdk';

async function stakeWithFixedYield(amount, userWalletAddress) {
  const queryId = Date.now();
  
  // Get expected PT amount to display to user
  const expectedPtOut = await fivaClient.getExpectedSwapAmountOut(
    FivaAsset.Underlying, 
    FivaAsset.PT, 
    amount
  );
  
  // Set minimum output with slippage protection
  // This is crucial for protecting users from price movements
  const minPtOut = (expectedPtOut * 99n) / 100n; // 1% slippage tolerance
  
  // Execute the stake transaction
  const result = await fivaClient.swapAssetForPt(
    amount,
    queryId,
    minPtOut,
    userWalletAddress // Optional: recipient address (defaults to sender)
  );
  
  return result;
}

When presenting this to users, you should frame it as "Fixed Staking" with a guaranteed return at maturity.

2. Unstake Before Maturity

This function allows users to exit their position early:

async function unstakeBeforeMaturity(ptAmount, userWalletAddress) {
  const queryId = Date.now();
  
  // Get expected asset amount to display to user
  const expectedAssetOut = await fivaClient.getExpectedSwapAmountOut(
    FivaAsset.PT, 
    FivaAsset.Underlying, 
    ptAmount
  );
  
  // Set minimum output with slippage protection
  const minAssetOut = (expectedAssetOut * 99n) / 100n; // 1% slippage tolerance
  
  // Execute the unstake transaction
  const result = await fivaClient.swapPtForAsset(
    ptAmount,
    queryId,
    minAssetOut,
    userWalletAddress // Optional: recipient address
  );
  
  return result;
}

When presenting this option to users, make it clear that early unstaking will return an amount determined by current market conditions, which may differ from the initially promised fixed rate.

3. Unstake After Maturity

This function allows users to redeem their PT tokens after maturity:

async function unstakeAfterMaturity(ptAmount, userWalletAddress) {
  const queryId = Date.now();
  
  // Execute the redeem transaction
  const result = await fivaClient.sendRedeemPT(
    ptAmount,
    queryId,
    userWalletAddress // Optional: recipient address
  );
  
  return result;
}

This function should be presented as "Claim" or "Withdraw" after the maturity date is reached.

Understanding Minimum Amount Out and Slippage Protection

Slippage protection is a critical aspect of any on-chain transaction, and it's especially important for fixed staking operations where users expect predictable outcomes.

What is minAmountOut?

In the SDK functions swapAssetForPt and swapPtForAsset, the minPtOut and minAssetOut parameters represent the minimum amount of tokens the user is willing to accept from the transaction. If the actual output would be less than this minimum (due to price movements or other factors), the transaction will revert.

Implementing Slippage Protection

There are two main approaches to implementing slippage protection:

  1. Fixed Percentage (as shown in examples):

    // 1% slippage tolerance
    const minAmountOut = (expectedAmountOut * 99n) / 100n;
  2. User-Configurable:

    // Allow users to set their own slippage tolerance (e.g., 0.5%, 1%, 2%)
    function calculateMinAmountOut(expectedAmountOut, slippagePercentage) {
      // slippagePercentage is a number like 0.5, 1, 2
      const slippageFactor = 100 - slippagePercentage;
      return (expectedAmountOut * BigInt(slippageFactor * 100)) / 10000n;
    }
    
    // Usage:
    const minAmountOut = calculateMinAmountOut(expectedAmountOut, userSelectedSlippage);

Importance of Slippage Protection

Without appropriate slippage protection:

  • Transactions may execute at unfavorable rates during periods of high volatility

  • Users may receive significantly less than expected, especially in pools with lower liquidity

  • Front-running attacks become possible in some scenarios

Important Note: If the transaction would result in receiving less than the specified minAmountOut, the entire transaction will be reverted. This protects users from unexpected outcomes and ensures they always get at least what they specified or nothing at all (allowing them to try again).

Complete Integration Example

Here's a comprehensive example that ties everything together:

import { FivaAsset, FivaClient } from '@fiva/sdk';
import { Address, toNano, TonClient4 } from '@ton/ton';

// Asset constants
const USDT_EVAA_SY = Address.parse('EQDi9blCcyT-k8iMpFMYY0t7mHVyiCB50ZsRgyUECJDuGvIl');
const USDT_PRECISION = 1_000_000; // 6 decimals
const FIVA_JETTON_PRECISION = 1_000_000_000; // 9 decimals

class FixedStakingIntegration {
  constructor(connector, endpoint = 'https://mainnet-v4.tonhubapi.com') {
    this.tonClient = new TonClient4({ endpoint });
    this.fivaClient = new FivaClient({ 
      connector, 
      tonClient: this.tonClient, 
      syAddress: USDT_EVAA_SY 
    });
  }
  
  // Get current fixed staking rate and maturity info
  async getFixedStakingInfo() {
    const index = await this.fivaClient.getIndex();
    const maturityTimestamp = await this.fivaClient.getMaturityTimestamp();
    const currentTime = Math.floor(Date.now() / 1000);
    const secondsToMaturity = maturityTimestamp - currentTime;
    const daysToMaturity = secondsToMaturity / (60 * 60 * 24);
    
    // Calculate APY based on current swap rate
    const oneUsdtAmount = 1_000_000n; // 1 USDT
    const expectedPtOut = await this.fivaClient.getExpectedSwapAmountOut(
      FivaAsset.Underlying, 
      FivaAsset.PT, 
      oneUsdtAmount
    );
    
    // Calculate APY (simplified)
    const ptToAssetRatio = Number(expectedPtOut) / Number(oneUsdtAmount);
    const annualizedReturn = (1 / ptToAssetRatio - 1) * (365 / daysToMaturity) * 100;
    
    return {
      fixedAPY: annualizedReturn.toFixed(2),
      daysToMaturity: Math.floor(daysToMaturity),
      maturityDate: new Date(maturityTimestamp * 1000).toLocaleDateString(),
      hasMatured: currentTime >= maturityTimestamp
    };
  }
  
  // Stake with fixed yield
  async stakeWithFixedYield(amountUsdt, slippagePercentage = 1) {
    const queryId = Date.now();
    const amount = BigInt(amountUsdt * USDT_PRECISION);
    
    const expectedPtOut = await this.fivaClient.getExpectedSwapAmountOut(
      FivaAsset.Underlying, 
      FivaAsset.PT, 
      amount
    );
    
    // Calculate minimum output based on slippage
    const slippageFactor = 100 - slippagePercentage;
    const minPtOut = (expectedPtOut * BigInt(slippageFactor)) / 100n;
    
    return await this.fivaClient.swapAssetForPt(amount, queryId, minPtOut);
  }
  
  // Unstake before maturity
  async unstakeBeforeMaturity(ptAmount, slippagePercentage = 1) {
    const queryId = Date.now();
    const amount = BigInt(ptAmount * FIVA_JETTON_PRECISION);
    
    const expectedAssetOut = await this.fivaClient.getExpectedSwapAmountOut(
      FivaAsset.PT, 
      FivaAsset.Underlying, 
      amount
    );
    
    // Calculate minimum output based on slippage
    const slippageFactor = 100 - slippagePercentage;
    const minAssetOut = (expectedAssetOut * BigInt(slippageFactor)) / 100n;
    
    return await this.fivaClient.swapPtForAsset(amount, queryId, minAssetOut);
  }
  
  // Unstake after maturity
  async unstakeAfterMaturity(ptAmount) {
    const queryId = Date.now();
    const amount = BigInt(ptAmount * FIVA_JETTON_PRECISION);
    
    return await this.fivaClient.sendRedeemPT(amount, queryId);
  }
  
  // Get user's PT balance
  async getUserPtBalance(userAddress) {
    return await this.fivaClient.getPtBalance(userAddress);
  }
  
  // Check if maturity date has passed
  async hasMatured() {
    const maturityTimestamp = await this.fivaClient.getMaturityTimestamp();
    const currentTime = Math.floor(Date.now() / 1000);
    return currentTime >= maturityTimestamp;
  }
}

Testing Your Integration

Before going live, we recommend testing your integration in our testnet environment:

  • Use testnet SY addresses from our repository

  • Test all three functions with small amounts

  • Verify APY calculations match expected values

  • Test the full lifecycle including maturity redemption

PreviousIntegrating Fixed-Rate StakingNextAPI - Pools Metrics Endpoint

Last updated 10 hours ago

Mainnet:

Testnet:

You can also check available pools and APYs in the FIVA application:

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

https://raw.githubusercontent.com/Fiva-protocol/assets/refs/heads/main/mainnet_SY.json
https://raw.githubusercontent.com/Fiva-protocol/assets/refs/heads/main/testnet_SY.json
https://app.thefiva.com/fixed-yield
community on Telegram