Skip to content

Instantly share code, notes, and snippets.

@patcito

patcito/put-dashboard-api.md

Last active January 23, 2026 11:13
Show Gist options

  • Select an option

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

Select an option

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

PUT Dashboard API - Consolidated Endpoint

Overview

The /status/put/dashboard endpoint has been updated to consolidate all PUT dashboard data into a single request. This replaces the previous pattern where frontend had to:

  1. Fetch /tge/metrics to discover strategies
  2. Fetch /tge/metrics/series per strategy in parallel
  3. Fetch /tge/yield for yield data
  4. Process and convert all data to USD client-side

Now everything is available in one request.

Endpoint

GET /status/put/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_transactions bool true Include recent PUT activity
transaction_limit int 100 Max transactions to return (max 1000)

Example Requests

# Default (7 days of series, 100 transactions)
curl /status/put/dashboard

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

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

# Only get 10 most recent transactions
curl /status/put/dashboard?transaction_limit=10

# Minimal response (no series, no transactions)
curl /status/put/dashboard?include_series=false&include_transactions=false

Response Structure

{
  "success": true,
  "chains": [
    {
      "chainId": 146,
      "chainName": "Sonic",
      "putManager": { ... },
      "oracle": { ... },
      "collaterals": [ ... ],
      "circuitBreaker": { ... },      // NEW: chain-level CB
      "metrics": { ... },              // NEW: aggregated metrics + series
      "transactions": [ ... ]          // NEW: recent PUT activity
    }
  ],
  "lastUpdated": "2026-01-23T12:00:00Z",
  "cacheAgeMs": 0
}

New Fields Added

1. chains[].collaterals[].sharePct

Percentage of total collateral value this collateral represents.

{
  "address": "0x29219dd400f2Bf60E5a23d13Be72B486D4038894",
  "symbol": "USDC",
  "sharePct": 95.5,
  "collateralSupplyUsd": "14.00"
}

2. chains[].collaterals[].vaultInfo.strategies[] - Enhanced

Each strategy now includes:

Field Type Description
deployedUsd string USD value of deployed capital (no $ prefix)
deployedPct float Percentage of vault capital deployed to this strategy
monthlyYieldUsd string USD value of yield claimed in last 30 days 
{
  "address": "0x06C0eeafE8EA72882b24D05d509D6d1733CB4A3A",
  "name": "Flying Tulip Aave USDC",
  "deployed": "10999999",
  "deployedFormatted": "11.00",
  "deployedUsd": "10.00",
  "deployedPct": 76.14,
  "monthlyYieldUsd": "0.50"
}

3. chains[].collaterals[].circuitBreaker - Enhanced

Per-collateral circuit breaker now includes ABI-aligned fields:

Field Type Description
mainBuffer string Main buffer amount (raw)
mainBufferFormatted string Formatted main buffer
elasticBuffer string Elastic buffer amount (raw)
elasticBufferFmt string Formatted elastic buffer
lastUpdate uint64 Unix timestamp of last update
elasticWindowHrs float Elastic window in hours 
{
  "address": "0x6b0743D3aff340bcAc717320279e441d83673551",
  "active": true,
  "mainBuffer": "723383",
  "mainBufferFormatted": "0.723383",
  "elasticBuffer": "0",
  "elasticBufferFmt": "0",
  "lastUpdate": 1768860693,
  "maxWithdrawalRatePct": 5,
  "replenishmentWindowHrs": 4,
  "elasticWindowHrs": 2
}

4. chains[].circuitBreaker - NEW (Chain-level)

Aggregated circuit breaker config for the chain:

Field Type Description
address string CB contract address
active bool Whether CB is active
maxDrawRateWad string Max draw rate in WAD (ABI naming)
maxDrawRateBps uint64 Max draw rate in basis points
mainWindow uint64 Main window in seconds
mainWindowHrs float Main window in hours
elasticWindow uint64 Elastic window in seconds
elasticWindowHrs float Elastic window in hours
mainBufferUsd string Sum of main buffers in USD 
{
  "address": "0x6b0743D3aff340bcAc717320279e441d83673551",
  "active": true,
  "maxDrawRateWad": "50000000000000000",
  "maxDrawRateBps": 500,
  "mainWindow": 14400,
  "mainWindowHrs": 4,
  "elasticWindow": 7200,
  "elasticWindowHrs": 2,
  "mainBufferUsd": "723.38"
}

5. chains[].metrics - NEW

Aggregated metrics with optional series data:

Field Type Description
ftTotalPutValueUsd string Current total FT PUT value in USD
ftTotalPutValueChangePct float 24h change percentage
collateralTotalPutValueUsd string Current total collateral value in USD
collateralTotalPutValueChangePct float 24h change percentage
allTimeYieldClaimedUsd string All-time yield claimed in USD
allTimeYieldClaimedChangePct float 24h change percentage
series object Historical series data (if include_series=true) 
{
  "ftTotalPutValueUsd": "1490000000",
  "ftTotalPutValueChangePct": 2.75,
  "collateralTotalPutValueUsd": "14.57",
  "collateralTotalPutValueChangePct": 1.23,
  "allTimeYieldClaimedUsd": "12",
  "allTimeYieldClaimedChangePct": 0,
  "series": {
    "ftPutValues": [...],
    "collateralPutValues": [...],
    "cumulativeYieldClaimed": [...]
  }
}

Series Data

{
  "series": {
    "ftPutValues": [
      { "date": "2026-01-16", "valueUsd": "1430000000" },
      { "date": "2026-01-17", "valueUsd": "1440000000" }
    ],
    "collateralPutValues": [
      { "date": "2026-01-16", "valueUsd": "13.65" },
      { "date": "2026-01-17", "valueUsd": "13.64" }
    ],
    "cumulativeYieldClaimed": [
      { "date": "2026-01-12", "valueUsd": "0" },
      { "date": "2026-01-19", "valueUsd": "12" }
    ]
  }
}
  • ftPutValues: 1 record per day, up to 360 entries
  • collateralPutValues: 1 record per day, up to 360 entries
  • cumulativeYieldClaimed: 1 record per week, up to 52 entries

6. chains[].transactions[] - NEW (Recent PUT Activity)

This array contains recent on-chain events from the PutManager contract. These are the same events already being indexed in the database, now exposed via the dashboard endpoint for displaying a "Recent Activity" feed.

Event Types

Action Description Contract Event
invest User deposits collateral and receives FT tokens Invest event
divest User burns FT to reclaim collateral Divest event
withdraw User withdraws FT tokens from position WithdrawFT event
capitalDivested Capital divested from a PUT position CapitalDivest event
withdrawDivestedCapital Msig withdraws divested capital from protocol WithdrawDivest event

Fields

Field Type Description
putId string NFT ID representing the PUT position (empty for withdrawDivestedCapital)
date string ISO 8601 timestamp of the transaction
action string Event type (see table above)
collateralAddress string Address of the collateral token involved
ftAmount string Amount of FT tokens (raw, 18 decimals)
collateralAmount string Amount of collateral (raw, token decimals)
userAddress string Address of the user or msig that initiated the action
txHash string On-chain transaction hash

Example

{
  "transactions": [
    {
      "putId": "140",
      "date": "2026-01-18T19:09:51Z",
      "action": "invest",
      "collateralAddress": "0x29219dd400f2bf60e5a23d13be72b486d4038894",
      "ftAmount": "2799301820000000000",
      "collateralAmount": "280000",
      "userAddress": "0x07f963bba27f12a540374441d853d4ce648faa15",
      "txHash": "0xf4b9f9a9ec8c4d0335b49cf6c8b84b3e4cf7865efa0f6912d469395943dad508"
    },
    {
      "putId": "140",
      "date": "2026-01-18T19:10:21Z",
      "action": "divest",
      "collateralAddress": "0x29219dd400f2bf60e5a23d13be72b486d4038894",
      "ftAmount": "2799301820000000000",
      "collateralAmount": "280000",
      "userAddress": "0x07f963bba27f12a540374441d853d4ce648faa15",
      "txHash": "0x7a0963245c96138259d9ab05d50794f6f2bee604216fe36188796882e7488a00"
    }
  ]
}

Usage

Use transaction_limit to control how many transactions are returned (default 100, max 1000). Set include_transactions=false to omit entirely for faster responses.

Breaking Changes

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

Migration Guide for Frontend

Before (Multiple Requests)

// Old pattern - DO NOT USE
const metrics = await fetch('/tge/metrics');
const strategies = metrics.strategy_allocation.entries.filter(e => e.chain_id === CHAIN_ID);

const seriesQueries = strategies.map(entry => 
  fetch(`/tge/metrics/series?metric=strategy_allocation&strategy=${entry.strategy_address}&field=yield_claimed`)
);
const seriesResults = await Promise.all(seriesQueries);

// Client-side USD conversion
const yieldUsd = seriesResults.map(series => {
  const price = tokens.find(t => t.address === series.asset_address)?.price;
  return series.points.map(p => formatUnits(p.value, p.decimals) * price);
});

After (Single Request)

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

// Everything is pre-calculated
const chain = dashboard.chains.find(c => c.chainId === CHAIN_ID);

// Series data is ready to use
const ftPutValues = chain.metrics.series.ftPutValues;
const collateralValues = chain.metrics.series.collateralPutValues;
const yieldClaimed = chain.metrics.series.cumulativeYieldClaimed;

// Strategy data includes USD values
const strategies = chain.collaterals.flatMap(c => c.vaultInfo?.strategies || []);
strategies.forEach(s => {
  console.log(s.name, s.deployedUsd, s.deployedPct, s.monthlyYieldUsd);
});

// Recent activity feed
const recentActivity = chain.transactions;
recentActivity.forEach(tx => {
  console.log(tx.date, tx.action, tx.userAddress, tx.txHash);
});

Caching

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

Original Feedback - Resolution

Issue Resolution
"Too many requests to API" Single /status/put/dashboard endpoint with all data
"Data processing on FE causes side effects" All USD conversions done server-side
"CB naming inconsistent with contracts" Fields now match ABI: mainBuffer, elasticBuffer, maxDrawRateWad, etc.
"Need sharePct for collaterals" Added sharePct field
"Need deployedUsd/deployedPct for strategies" Added to each strategy
"Need monthlyYieldUsd" Added to each strategy
"Need elasticBuffer/mainBuffer" Added to per-collateral CB
"Need chain-level CB config" Added chains[].circuitBreaker
"Need metrics with series data" Added chains[].metrics with series
"Need transactions" Added chains[].transactions with all PUT events
"Historical data configurable" Added days param (default 7, max 360)

Performance Notes

  • Response is cached for 30 seconds (default params only)
  • DB indexes added for timestamp columns
  • Transactions query uses per-table LIMIT for index efficiency
  • Series queries use composite indexes on (blockchain_id, scope, recorded_at)

ftbot Commands

The Telegram bot has been updated to leverage the consolidated endpoint:

Updated Commands

Command Description
/put_dashboard Shows full dashboard with metrics, CB status, collaterals, strategies
/cb Circuit breaker status using chain-level CB data
/put_transactions [limit] Recent PUT activity (invest, divest, withdraw)
/put_metrics [days] Metrics with series data summary

New Chart Commands

Command Description
/chart_ft_value [days] Line chart of FT PUT value over time (default 7 days)
/chart_collateral_value [days] Line chart of collateral PUT value over time
/chart_yield [days] Line chart of cumulative yield claimed (default 30 days)

Charts are generated using QuickChart.io and sent as images to Telegram.

Example:

/chart_ft_value 14

Sends a 14-day chart of FT PUT value with daily data points.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment