API Documentation

Public read-only endpoints for the Fraudsworth Stats dashboard. All responses are JSON.

Base URL: https://www.fraudsworth.fyi

No authentication required for read endpoints

Admin and backfill endpoints that require Bearer authentication are not listed here.

Prices & Market Data

GET/api/solana/pool-state

Live CRIME, FRAUD, and PROFIT token prices in SOL and USD with market caps and percent changes.

Param	Type	Required	Description
period	string	no	"1h" \| "24h" \| "7d" (default "24h"). Lookback window for percent change.

Example response

{
  "crime": { "priceSol": 0.000012, "priceUsd": 0.0018, "marketCapUsd": 1800, "percentChange": 5.2 },
  "fraud": { "priceSol": 0.000011, "priceUsd": 0.0016, "marketCapUsd": 1600, "percentChange": -2.1 },
  "profit": { "priceSol": 0.000023, "priceUsd": 0.0034, "marketCapUsd": 68000, "percentChange": 3.4 },
  "solUsdPrice": 148.50,
  "period": "24h",
  "fetchedAt": "2026-03-29T12:00:00.000Z"
}

GET/api/sol-price

Current SOL/USD price from CoinGecko.

Example response

{ "price": 148.50 }

GET/api/profit/history

Historical PROFIT market cap time-series from pre-computed snapshots.

Param	Type	Required	Description
period	string	no	"1h" \| "6h" \| "24h" \| "7d" \| "30d" \| "all" (default "24h").

Example response

{
  "points": [
    { "time": 1711699200, "mcUsd": 68000, "mcSol": 458 },
    { "time": 1711702800, "mcUsd": 69200, "mcSol": 466 }
  ]
}

Epoch State

GET/api/solana/epoch-state

Current epoch number, phase, cheap side, per-token tax rates, countdown, flip detection, and Carnage status.

Example response

{
  "epochNumber": 482,
  "phase": "TRADING",
  "cheapSide": 0,
  "cheapSideLabel": "CRIME",
  "crimeBuyTaxBps": 200,
  "crimeSellTaxBps": 500,
  "fraudBuyTaxBps": 500,
  "fraudSellTaxBps": 200,
  "countdownSeconds": 842,
  "flipped": false,
  "carnagePending": false,
  "carnageTarget": null,
  "carnageAction": null,
  "fetchedAt": "2026-03-29T12:00:00.000Z",
  "slot": 312000000
}

Staking

GET/api/staking/state

Live staking pool state: total staked PROFIT, escrow SOL balance, pending rewards, locked/unlocked breakdown.

Example response

{
  "totalStaked": "5000000000000",
  "totalStakedHuman": 5000000,
  "stakedPercent": 25.0,
  "escrowSol": 12.5,
  "totalDistributedSol": 45.2,
  "totalClaimedSol": 38.1,
  "pendingRewardsSol": 0.8,
  "lockedProfit": 2000000,
  "unlockedProfit": 3000000,
  "lockedCount": 42,
  "unlockedCount": 85,
  "fetchedAt": "2026-03-29T12:00:00.000Z"
}

GET/api/staking/apy

Computed staking APY from on-chain rewardsPerTokenStored deltas, with per-period reward rates.

Example response

{
  "apy": 142.5,
  "insufficientData": false,
  "dataPoints": 1200,
  "periodDays": 7.0,
  "rewardRates": {
    "lastEpochSol": 0.0001,
    "last24hSol": 0.0008,
    "last7dSol": 0.005,
    "last30dSol": 0.02
  },
  "computedAt": "2026-03-29T12:00:00.000Z"
}

GET/api/staking/snapshots

Historical stake pool snapshots (totalStaked, rewardsPerTokenStored, etc.) for charting.

Param	Type	Required	Description
period	string	no	"7d" \| "30d" \| "90d" \| "all" (default "7d"). Shorthand for time range.
from	ISO 8601	no	Start date (ignored if period is set).
to	ISO 8601	no	End date (defaults to now).
limit	number	no	Max rows returned (default 2000, max 5000).

Example response

{
  "snapshots": [
    {
      "capturedAt": "2026-03-22T00:00:00.000Z",
      "totalStaked": "5000000000000",
      "totalStakedHuman": 5000000,
      "rewardsPerTokenStored": "1234567890",
      "pendingRewards": "800000000",
      "lastUpdateEpoch": 480
    }
  ],
  "count": 336,
  "from": "2026-03-22T00:00:00.000Z",
  "to": "2026-03-29T12:00:00.000Z"
}

Analytics

GET/api/analytics/summary

All-time hero metrics: total SOL volume, unique wallets, total tax collected, protocol revenue.

Example response

{
  "totalVolumeSol": 1234.56,
  "uniqueWallets": 892,
  "totalTaxCollectedSol": 45.2,
  "protocolRevenueSol": 45.2,
  "solUsdPrice": 148.50
}

GET/api/analytics/volume

Time-series buy/sell SOL volume. Epoch-bucketed for 24h/7d, day-bucketed for 30d/all.

Param	Type	Required	Description
period	string	no	"24h" \| "7d" \| "30d" \| "all" (default "7d").

Example response

{
  "data": [
    { "label": "54", "buySol": 12.5, "sellSol": 8.3, "txCount": 42 }
  ],
  "period": "7d"
}

GET/api/analytics/wallets

Per-period new wallet counts with cumulative running total.

Param	Type	Required	Description
period	string	no	"24h" \| "7d" \| "30d" \| "all" (default "7d").

Example response

{
  "data": [
    { "label": "54", "newWallets": 12, "cumulativeWallets": 340 }
  ],
  "totalUniqueAllTime": 892,
  "period": "7d"
}

GET/api/analytics/tax

Per-period buy-tax and sell-tax SOL collected using epoch-specific tax rates.

Param	Type	Required	Description
period	string	no	"24h" \| "7d" \| "30d" \| "all" (default "7d").

Example response

{
  "data": [
    { "label": "54", "buyTaxSol": 0.25, "sellTaxSol": 0.18 }
  ],
  "period": "7d"
}

GET/api/analytics/tax-distribution

Histogram of transaction counts and SOL volume grouped by effective tax rate bracket.

Param	Type	Required	Description
period	string	no	"24h" \| "7d" \| "30d" \| "all" (default "7d").

Example response

{
  "data": [
    { "taxRateBps": 200, "taxRatePercent": "2.00%", "buyCount": 50, "sellCount": 30, "buySol": 5.2, "sellSol": 3.1 }
  ],
  "period": "7d"
}

GET/api/analytics/claims

Daily SOL claimed by stakers, computed from stake pool totalClaimed deltas.

Param	Type	Required	Description
period	string	no	"24h" \| "7d" \| "30d" \| "all" (default "30d").

Example response

{
  "data": [
    { "label": "2026-03-28", "claimedSol": 1.25 }
  ],
  "period": "30d"
}

GET/api/analytics/revenue

Per-period and cumulative protocol revenue (total tax collected).

Param	Type	Required	Description
period	string	no	"24h" \| "7d" \| "30d" \| "all" (default "7d").

Example response

{
  "data": [
    { "label": "54", "periodRevenueSol": 0.43, "cumulativeRevenueSol": 12.5 }
  ],
  "period": "7d"
}

Liquidity

GET/api/liquidity/current

Live SOL balance, token balance, TVL, and cumulative LP fees for CRIME and FRAUD pools.

Example response

{
  "crime": { "solHuman": 45.2, "tokenHuman": 3500000, "tvlUsd": 13400 },
  "fraud": { "solHuman": 42.8, "tokenHuman": 3200000, "tvlUsd": 12700 },
  "totalFeeSol": 12.5,
  "solUsdPrice": 148.50,
  "fetchedAt": "2026-03-29T12:00:00.000Z"
}

GET/api/liquidity/history

Historical SOL reserve series for both CRIME and FRAUD pools.

Param	Type	Required	Description
period	string	no	"7d" \| "30d" \| "all" (default "30d").

Example response

{
  "crime": [
    { "capturedAt": "2026-03-22T00:00:00.000Z", "reserveSolHuman": 45.2 }
  ],
  "fraud": [
    { "capturedAt": "2026-03-22T00:00:00.000Z", "reserveSolHuman": 42.8 }
  ]
}

GET/api/liquidity/fees

Daily and cumulative LP fee accumulation per pool (1% of swap volume).

Param	Type	Required	Description
period	string	no	"7d" \| "30d" \| "all" (default "30d").

Example response

{
  "crime": [
    { "day": "2026-03-28 00:00:00", "dailyFeeSol": 0.12, "cumFeeSol": 6.8 }
  ],
  "fraud": [
    { "day": "2026-03-28 00:00:00", "dailyFeeSol": 0.10, "cumFeeSol": 5.7 }
  ]
}

Holders

GET/api/holders/leaderboard

Top 50 PROFIT stakers ranked by SOL earned, with SNS domain resolution and rank changes.

Example response

{
  "wallets": [
    {
      "rank": 1,
      "wallet": "ABC1...xyz9",
      "domain": "degen.sol",
      "solEarned": "5000000000",
      "profitStaked": "1000000000000",
      "rankChange": 2
    }
  ],
  "total": 127,
  "updatedAt": "2026-03-29T12:00:00.000Z"
}

GET/api/holders/distribution

Holder distribution: top-10 donut chart data and size-bracket counts for a given token.

Param	Type	Required	Description
token	string	yes	"CRIME" \| "FRAUD" \| "PROFIT".

Example response

{
  "token": "PROFIT",
  "holderCount": 340,
  "donut": [
    { "name": "#1 (ABC1...xyz9)", "value": 8.5 }
  ],
  "brackets": [
    { "bracket": "200K+", "count": 5 },
    { "bracket": "20K-200K", "count": 28 }
  ],
  "whaleCount": 5,
  "totalSupply": 20000000
}

GET/api/holders/trends

Holder count and whale count over time, with significant whale movement events and optional individual whale balance lines.

Param	Type	Required	Description
token	string	yes	"CRIME" \| "FRAUD" \| "PROFIT".
period	string	no	"7d" \| "30d" \| "90d" \| "all" (default "30d").
whales	string	no	"aggregate" \| "individual" (default "aggregate"). When "individual", includes top-5 whale balance lines.

Example response

{
  "token": "PROFIT",
  "period": "30d",
  "data": [
    { "capturedAt": "2026-03-22T00:00:00.000Z", "holderCount": 320, "whaleCount": 4 }
  ],
  "whaleEvents": [
    { "capturedAt": "2026-03-25T00:00:00.000Z", "label": "Whale +1.2M PROFIT", "direction": "in" }
  ]
}

Portfolio

GET/api/portfolio/{address}

Full portfolio breakdown for a wallet: live holdings, staking position, per-token PnL (realised + unrealised), and current prices. Results are cached for 30 minutes.

Param	Type	Required	Description
address	string (path)	yes	Solana wallet address (base58).
force	boolean	no	"true" to bypass the 30-minute cache.

Example response

{
  "holdings": { "crime": 500000, "fraud": 350000, "profit": 100000 },
  "staking": {
    "stakedBalance": "100000000000",
    "rewardsEarned": "500000000",
    "totalClaimed": "1200000000",
    "pendingEstimate": "150000000",
    "lastClaimTs": 1711699200
  },
  "pnl": {
    "crime": { "realisedPnlLamports": "500000000", "unrealisedPnlLamports": "200000000", "totalBuySol": 5.0, "totalSellSol": 5.5 },
    "fraud": { "...": "..." },
    "profit": { "...": "..." }
  },
  "prices": {
    "crimePriceSol": 0.000012,
    "fraudPriceSol": 0.000011,
    "profitPriceSol": 0.000023,
    "solUsdPrice": 148.50
  },
  "computedAt": "2026-03-29T12:00:00.000Z",
  "backfillComplete": true
}

Circulating Supply

GET/api/supply/current

Live circulating supply breakdown for CRIME, FRAUD, and PROFIT tokens. Circulating = total supply minus conversion vault balance minus burns. Staking does not affect circulating supply.

Example response

{
  "crime": {
    "totalSupply": 1000000000,
    "vaultBalance": 724000000,
    "burned": 5800000,
    "circulating": 270200000,
    "maxCirculating": 744200000,
    "circulatingPct": 27.0,
    "vaultBalancePct": 72.4,
    "burnedPct": 0.58
  },
  "fraud": { "..." : "..." },
  "profit": {
    "totalSupply": 20000000,
    "vaultBalance": 10400000,
    "burned": 0,
    "circulating": 9600000,
    "maxCirculating": 14873027,
    "circulatingPct": 48.0,
    "vaultBalancePct": 52.0,
    "burnedPct": 0
  },
  "ecosystemMaxCirculating": 14873027,
  "vaultSource": "Conversion vault: 8vFpSBnCVt8dfX57FKrsGwy39TEo1TjVzrj9QYGxCkcD",
  "fetchedAt": "2026-04-03T12:00:00.000Z"
}

GET/api/supply/history

Historical supply data: cumulative burns over time for CRIME/FRAUD and PROFIT staking over time.

Param	Type	Required	Description
period	string	no	"7d" \| "30d" \| "90d" \| "all" (default "30d"). Time range for historical data.

Example response

{
  "burns": [
    {
      "date": "2026-03-01",
      "crimeBurnedCumulative": 1500000,
      "fraudBurnedCumulative": 1200000,
      "crimeCirculating": 748500000,
      "fraudCirculating": 748800000
    }
  ],
  "staking": [
    { "date": "2026-03-01", "profitStaked": 3200000, "profitCirculating": 11800000 }
  ],
  "vaultLocked": { "crime": 250000000, "fraud": 250000000, "profit": 5000000 },
  "period": "30d"
}

Wallet

GET/api/wallet/{address}

Wallet profile: SNS domain, token holdings, staking position with leaderboard rank, and recent trade history (last 50 swaps).

Param	Type	Required	Description
address	string (path)	yes	Solana wallet address (base58).

Example response

{
  "wallet": "ABC1...xyz9",
  "domain": "degen.sol",
  "holdings": { "crime": 500000, "fraud": 350000, "profit": 100000 },
  "staking": {
    "stakedBalance": "100000000000",
    "totalClaimed": "1200000000",
    "rewardsEarned": "500000000",
    "rank": 12,
    "totalStakers": 127
  },
  "trades": [
    {
      "txSignature": "5abc...",
      "occurredAt": "2026-03-28T15:30:00.000Z",
      "token": "CRIME",
      "side": "buy",
      "tokenAmount": "500000000000",
      "solAmount": "1500000000",
      "epoch": 480
    }
  ]
}

All timestamps are ISO 8601 UTC. Lamport values are raw (1 SOL = 1e9 lamports). Epoch numbers in analytics labels have the display offset applied (on-chain epoch minus 428).