Skip to content

Instantly share code, notes, and snippets.

@patcito

patcito/ftusd-dashboard-api.md

Created January 23, 2026 12:26
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save patcito/35f47596b57e16db1cc031ef2de9317e to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save patcito/35f47596b57e16db1cc031ef2de9317e to your computer and use it in GitHub Desktop.
Download ZIP
ftUSD Dashboard API - Consolidated Endpoint Documentation
Raw
ftusd-dashboard-api.md

ftUSD Dashboard API - Consolidated Endpoint

Overview

The /status/ftusd/dashboard endpoint has been updated to consolidate all ftUSD dashboard data into a single request. This provides:

  1. Chain-specific contract data (ftUSD token, MintAndRedeem, StakingVault)
  2. Per-chain metrics with 24h change percentages
  3. Historical series data (supply, price, backing, APY)
  4. Recent events (mints, redeems, staking activity)

Everything is available in one request with configurable query parameters.

Endpoint

GET /status/ftusd/dashboard

Query Parameters

Parameter Type Default Description
days int 7 Number of days for series data (max 360)
include_series bool true Include historical series data
include_events bool true Include recent events
event_limit int 100 Max events to return (max 1000)

Example Requests

# Default (7 days of series, 100 events)
curl /status/ftusd/dashboard

# 30 days of series data
curl /status/ftusd/dashboard?days=30

# Skip series data for faster response
curl /status/ftusd/dashboard?include_series=false

# Only get 10 most recent events
curl /status/ftusd/dashboard?event_limit=10

# Minimal response (no series, no events)
curl /status/ftusd/dashboard?include_series=false&include_events=false

Response Structure

{
  "success": true,
  "chains": [
    {
      "chainId": 146,
      "chainName": "Sonic",
      "ftUSD": { ... },
      "mintAndRedeem": { ... },
      "stakingVault": { ... },
      "metrics": { ... },
      "events": [ ... ]
    }
  ],
  "lastUpdated": "2026-01-23T12:00:00Z",
  "cacheAgeMs": 0
}

Field Details

1. chains[].ftUSD - Token Data

Basic ftUSD token information.

{
  "address": "0x6a6aBD87c670f367106d8549664943885175015c",
  "totalSupply": "96866",
  "name": "Flying Tulip USD",
  "symbol": "ftUSD",
  "decimals": 6
}

2. chains[].mintAndRedeem - Mint/Redeem Contract

Full MintAndRedeem contract state including collaterals with circuit breakers.

{
  "address": "0x07F015877025Fc5D00928596e12dE0ADADc32130",
  "paused": false,
  "pauser": "0xddd8...",
  "owner": "0xddd8...",
  "oracle": "0xfDF3...",
  "collateralCount": 2,
  "totalFtUSDMinted": "96866",
  "totalFtUSDBurned": "0",
  "outstandingFtUSD": "96866",
  "assetsUSD": "96869",
  "collaterals": [
    {
      "address": "0x29219dd400f2Bf60E5a23d13Be72B486D4038894",
      "symbol": "USDC",
      "name": "USDC",
      "decimals": 6,
      "enabled": true,
      "mintFeeBps": 0,
      "redeemFeeBps": 0,
      "collateralAssets": "96900",
      "yieldWrapper": "0xB30E...",
      "circuitBreaker": {
        "address": "0xD81b...",
        "active": true,
        "maxWithdrawalRatePct": 5,
        "replenishmentWindowHrs": 4,
        "mainUtilizationBps": 0,
        "totalCapacity": "11117",
        "totalCapacityFormatted": "0.0111",
        "maxCapacity": "4845",
        "maxCapacityFormatted": "0.0048",
        "secondsUntilFullReplenishment": 0,
        "replenishmentTimeFormatted": "0:00:00"
      }
    }
  ]
}

3. chains[].stakingVault - Staking Data (Enhanced)

EpochRewardsVault (sftUSD) data with exchange rate and decimals.

Field Type Description
address string sftUSD contract address
paused bool Whether staking is paused
totalAssets string Total ftUSD assets in vault
totalSupply string Total sftUSD supply
totalStaked string Total ftUSD staked
currentEpoch uint32 Current reward epoch
exchangeRate string sftUSD to ftUSD exchange rate (scaled to 1e18)
rateDecimals int NEW: Decimals for exchange rate (always 18) 
{
  "address": "0xFd3052db8F567500023aC582Ed719e0ee3516Fa0",
  "paused": false,
  "owner": "0xddd8...",
  "totalAssets": "50000",
  "totalSupply": "50000",
  "totalStaked": "50000",
  "totalStakeTime": "2590260000",
  "currentEpoch": 0,
  "exchangeRate": "1000000000000000000",
  "rateDecimals": 18
}

4. chains[].metrics - NEW (Aggregated Metrics)

Per-chain metrics with 24h change percentages and decimal information for client formatting.

Field Type Description
totalSupply string ftUSD total supply (raw)
totalSupplyUsd string ftUSD total supply in USD
totalSupplyChangePct float NEW: 24h change percentage (rounded to 2 decimals)
supplyDecimals int NEW: Decimals for supply values
totalBacking string Total backing value (raw)
totalBackingUsd string Total backing in USD
totalBackingChangePct float NEW: 24h backing change percentage
backingUsdDecimals int NEW: Decimals for backing USD values
backingRatioBps int Backing ratio in basis points
priceUsd string Current ftUSD price
priceDecimals int NEW: Decimals for price (typically 8)
totalStaked string NEW: Total sftUSD staked (from StakingVault)
totalStakedUsd string NEW: Total staked in USD
apy object APY data for various periods
series object Historical series data (if include_series=true) 
{
  "totalSupply": "96866",
  "totalSupplyUsd": "96866",
  "totalSupplyChangePct": 29.37,
  "supplyDecimals": 6,
  "totalBacking": "9686996",
  "totalBackingUsd": "9686996",
  "totalBackingChangePct": 29.36,
  "backingUsdDecimals": 8,
  "backingRatioBps": 10000,
  "priceUsd": "100000000",
  "priceDecimals": 8,
  "totalStaked": "50000",
  "totalStakedUsd": "50000",
  "apy": {
    "current": 5.25,
    "week": 5.25,
    "month": 4.80,
    "threeMonth": 4.50,
    "sixMonth": 4.25,
    "year": 4.00,
    "allTime": 3.75
  },
  "series": { ... }
}

APY Data

Field Type Description
current float Current trailing 7-day APY
week float 1 week APY
month float 1 month APY
threeMonth float 3 month APY
sixMonth float 6 month APY
year float 1 year APY
allTime float All-time APY

Series Data

{
  "series": {
    "supply": [
      { "date": "2026-01-22T00:00:00Z", "valueUsd": "74876" },
      { "date": "2026-01-23T00:00:00Z", "valueUsd": "96866" }
    ],
    "price": [
      { "date": "2026-01-22T00:00:00Z", "valueUsd": "100000000" },
      { "date": "2026-01-23T00:00:00Z", "valueUsd": "100000000" }
    ],
    "backing": [
      { "date": "2026-01-22T00:00:00Z", "valueUsd": "7487678" },
      { "date": "2026-01-23T00:00:00Z", "valueUsd": "9686996" }
    ],
    "apy": [
      { "date": "2026-01-22T00:00:00Z", "apy": 5.10 },
      { "date": "2026-01-23T00:00:00Z", "apy": 5.25 }
    ]
  }
}
  • supply: Daily ftUSD supply values
  • price: Daily ftUSD price values
  • backing: Daily total backing values
  • apy: Daily trailing 7-day APY values

5. chains[].events[] - NEW (Recent Activity)

Recent ftUSD protocol events (mints, redeems, staking activity).

Event Types

EventType Description
mint User minted ftUSD with collateral
redeem User redeemed ftUSD for collateral
stake User staked ftUSD for sftUSD
unstake User unstaked sftUSD for ftUSD
claim User claimed staking rewards

Fields

Field Type Description
eventType string Type of event (see table above)
transactionHash string On-chain transaction hash
timestamp int64 Unix timestamp
date string ISO 8601 formatted date
amount string Amount of ftUSD involved (raw)
feeAmount string Fee amount if applicable
userAddress string Address of the user 
{
  "events": [
    {
      "eventType": "mint",
      "transactionHash": "0xdcfee4e026c614aee5666fe0219ddccaf4aee1dd4cf771c0f8c8e029d32d1979",
      "timestamp": 1769166280,
      "date": "2026-01-23T11:04:40Z",
      "amount": "9996",
      "feeAmount": "0",
      "userAddress": "0xbbc6344b27dea8df7a15d8000b88c242d3a6a974"
    },
    {
      "eventType": "mint",
      "transactionHash": "0x6fcc64e0cf3173f965374a1a0a7e7cf161a8f57c2e82212e3e6b77a2f302ee23",
      "timestamp": 1769166066,
      "date": "2026-01-23T11:01:06Z",
      "amount": "999",
      "feeAmount": "0",
      "userAddress": "0xbbc6344b27dea8df7a15d8000b88c242d3a6a974"
    }
  ]
}

Breaking Changes

None. All existing fields are preserved. New fields are additive.

Migration Guide for Frontend

Before (Multiple Requests or Missing Data)

// Old pattern - status only, no metrics or history
const status = await fetch('/status/ftusd');

// Had to make separate calls or compute client-side
const supply = await fetch('/ftusd/supply');
const backing = await fetch('/ftusd/backing');
// ... compute 24h changes manually

After (Single Request)

// New pattern - USE THIS
const dashboard = await fetch('/status/ftusd/dashboard?days=30');

const chain = dashboard.chains.find(c => c.chainId === CHAIN_ID);

// Metrics with 24h changes are pre-calculated
const metrics = chain.metrics;
console.log('Supply:', metrics.totalSupply, `(${metrics.totalSupplyChangePct}% 24h)`);
console.log('Backing:', metrics.totalBackingUsd, `(${metrics.totalBackingChangePct}% 24h)`);
console.log('Staked:', metrics.totalStaked);

// Decimals available for client-side formatting
const supplyFormatted = formatUnits(metrics.totalSupply, metrics.supplyDecimals);
const priceFormatted = formatUnits(metrics.priceUsd, metrics.priceDecimals);

// Series data ready to use
const supplySeries = metrics.series.supply;
const apySeries = metrics.series.apy;

// Recent activity feed
const recentActivity = chain.events;
recentActivity.forEach(e => {
  console.log(e.date, e.eventType, e.amount, e.userAddress);
});

// Staking vault with exchange rate
const vault = chain.stakingVault;
const rate = formatUnits(vault.exchangeRate, vault.rateDecimals); // Use rateDecimals (18)

Caching

The endpoint has a 30-second cache for default parameters. Custom parameters bypass the cache.

Summary of New Fields

Location Field Description
metrics totalSupplyChangePct 24h supply change % (rounded to 2 decimals)
metrics supplyDecimals Decimals for supply values
metrics totalBackingChangePct 24h backing change %
metrics backingUsdDecimals Decimals for backing values
metrics priceDecimals Decimals for price values
metrics totalStaked Total staked from StakingVault
metrics totalStakedUsd Total staked in USD
metrics series Historical series data
stakingVault rateDecimals Exchange rate decimals (18)
chains[] events Recent protocol events

Related Endpoints

Endpoint Description
/status/ftusd Basic pause status (lightweight)
/status/ftusd/dashboard Full dashboard with all data (this endpoint)
/status/ftusd/collaterals/{chainId} Detailed collateral info for a chain

Performance Notes

  • Response is cached for 30 seconds (default params only)
  • Series data is fetched once per request, not per-chain (optimized)
  • Events query uses indexed timestamp columns
  • Stable ordering by ChainID ensures consistent responses
  • Boolean parsing uses strconv.ParseBool for robust handling ("true", "1", "yes", etc.)
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment