ftUSD Dashboard API Guide for Frontend Developers

ftusd-dashboard-guide.md

ftUSD Dashboard API Guide

This guide covers the ftUSD dashboard endpoints for displaying user positions, stats, and historical events.

Base URL

Production: https://api.flyingtulip.com (or your configured API URL)

Endpoints

1. Get ftUSD Status

Returns comprehensive ftUSD status including user balances, staking info, and historical yield data.

GET /ftusd/status?address={walletAddress}&chainId={chainId}

Parameters:

Name	Type	Required	Default	Description
address	string	Yes	-	User wallet address (0x...)
chainId	int	No	1	Chain ID (1=Ethereum, 146=Sonic)

Response:

{
  "success": true,
  "chain_id": 1,
  "address": "0x...",
  "ftusd_balance": "1000000000000000000",
  "sftusd_balance": "950000000000000000",
  "sftusd_assets": "1000000000000000000",
  "total_supply": "10000000000000000000000",
  "total_assets": "10500000000000000000000",
  "share_price": "1050000000000000000",
  "current_epoch": 5,
  "epoch_duration": 604800,
  "epoch_start": 1705708800,
  "epoch_end": 1706313600,
  "historical_yields": [
    {"epoch": 1, "yield_rate": "0.05", "timestamp": 1704499200},
    {"epoch": 2, "yield_rate": "0.052", "timestamp": 1705104000}
  ]
}

---

2. Get Dashboard Events

Returns paginated list of ftUSD events (mints, redeems, stakes, unstakes) for a user.

GET /ftusd/dashboard/events?address={walletAddress}&chainId={chainId}&limit={limit}&offset={offset}

Parameters:

Name	Type	Required	Default	Description
address	string	Yes	-	User wallet address
chainId	int	No	1	Chain ID
limit	int	No	20	Max events to return (max 100)
offset	int	No	0	Pagination offset

Response:

{
  "success": true,
  "chain_id": 1,
  "address": "0x...",
  "events": [
    {
      "type": "mint",
      "tx_hash": "0x...",
      "block_number": 12345678,
      "timestamp": 1705708800,
      "collateral_token": "0x...",
      "collateral_amount": "1000000000",
      "ftusd_amount": "1000000000000000000"
    },
    {
      "type": "stake",
      "tx_hash": "0x...",
      "block_number": 12345679,
      "timestamp": 1705708900,
      "ftusd_amount": "1000000000000000000",
      "sftusd_shares": "950000000000000000"
    }
  ],
  "total": 42,
  "limit": 20,
  "offset": 0
}

Event Types:

• mint - User minted ftUSD from collateral
• redeem - User redeemed ftUSD for collateral
• stake - User staked ftUSD for sftUSD
• unstake - User unstaked sftUSD for ftUSD

---

3. Get Contract Addresses

Returns all ftUSD-related contract addresses for a chain.

GET /ftusd/contracts?chainId={chainId}

Parameters:

Name	Type	Required	Default	Description
chainId	int	No	1	Chain ID

Response:

{
  "success": true,
  "chain_id": 1,
  "contracts": {
    "ftUSD": "0x...",
    "mintAndRedeem": "0x...",
    "sftUSD": "0x...",
    "sessionManager": "0x..."
  }
}

---

Usage Examples

React Hook Example

import { useQuery } from '@tanstack/react-query';

export function useFtUSDStatus(address: string, chainId = 1) {
  return useQuery({
    queryKey: ['ftusd-status', address, chainId],
    queryFn: async () => {
      const res = await fetch(
        `${API_URL}/ftusd/status?address=${address}&chainId=${chainId}`
      );
      if (!res.ok) throw new Error('Failed to fetch status');
      return res.json();
    },
    enabled: !!address,
  });
}

export function useFtUSDEvents(address: string, chainId = 1, limit = 20, offset = 0) {
  return useQuery({
    queryKey: ['ftusd-events', address, chainId, limit, offset],
    queryFn: async () => {
      const res = await fetch(
        `${API_URL}/ftusd/dashboard/events?address=${address}&chainId=${chainId}&limit=${limit}&offset=${offset}`
      );
      if (!res.ok) throw new Error('Failed to fetch events');
      return res.json();
    },
    enabled: !!address,
  });
}

---

Swagger Documentation

Full API documentation available at: /swagger/index.html

---

Notes

• All amounts are returned as strings to preserve precision (wei values)
• share_price is the current sftUSD share price in wei (1e18 = 1:1 ratio)
• Historical yields are sorted by epoch ascending
• Events are sorted by timestamp descending (most recent first)