wallet-widget-endpoint.md

Wallet Widget Endpoint

GET /wallet/{address}

Returns FT token balance, puts/marketplace summary, and the 3 most recent user actions for the wallet widget.

No query parameters needed — aggregates across all chains automatically.

---

Response

{
  "code": 200,
  "success": true,
  "data": {
    "ftBalance": 10000.56,
    "ftBalanceUsd": 1000.056,
    "ftBalanceChangePct": 0,
    "points": 0,
    "putsData": {
      "bidCount": 4,
      "ftListed": 10000,
      "ftSold": 5000
    },
    "activity": [
      {
        "product": "lend",
        "type": "withdraw",
        "inputAssetSymbol": "USDC",
        "inputAssetAmount": 10000,
        "inputAssetAmountUsd": 10000,
        "outputAssetSymbol": "USDC",
        "outputAssetAmount": 10000,
        "outputAssetAmountUsd": 10000,
        "timestamp": "2025-02-26T00:00:00Z"
      },
      {
        "product": "ftusd",
        "type": "buy",
        "inputAssetSymbol": "USDC",
        "inputAssetAmount": 5000,
        "inputAssetAmountUsd": 5000,
        "outputAssetSymbol": "ftUSD",
        "outputAssetAmount": 5000,
        "outputAssetAmountUsd": 5000,
        "timestamp": "2025-02-25T12:00:00Z"
      },
      {
        "product": "put",
        "type": "commit",
        "inputAssetSymbol": "USDC",
        "inputAssetAmount": 2000,
        "inputAssetAmountUsd": 2000,
        "outputAssetSymbol": "USDC",
        "outputAssetAmount": 2000,
        "outputAssetAmountUsd": 2000,
        "timestamp": "2025-02-24T08:30:00Z"
      }
    ]
  }
}

---

Field Reference

Top-level

Field	Type	Description
ftBalance	number	FT token balance (human-readable, 18 decimals converted)
ftBalanceUsd	number	FT balance in USD (balance × $0.10)
ftBalanceChangePct	number	Always 0 for now (FT price is static)
points	number	Always 0 for now (placeholder)

putsData

Field	Type	Description
bidCount	int	Number of active buy offers the user has placed
ftListed	number	Total FT in the user's actively listed puts
ftSold	number	Total FT in puts the user has sold

activity[] (max 3 items, most recent first)

Field	Type	Description
product	string	One of: "lend", "ftusd", "put", "marketplace"
type	string	Action type (see table below)
inputAssetSymbol	string	Input token symbol (e.g. "USDC", "ftUSD", "FT")
inputAssetAmount	number	Input amount (human-readable float)
inputAssetAmountUsd	number	Input amount in USD
outputAssetSymbol	string	Output token symbol
outputAssetAmount	number	Output amount (human-readable float)
outputAssetAmountUsd	number	Output amount in USD
timestamp	string	RFC3339 UTC timestamp

Activity Types by Product

Product	Type	What happened
lend	supply	Deposited asset into lending pool
lend	borrow	Borrowed asset from lending pool
lend	repay	Repaid borrowed asset
lend	withdraw	Withdrew deposited asset
ftusd	buy	Minted ftUSD with collateral
ftusd	sell	Redeemed ftUSD for collateral
ftusd	stake	Staked ftUSD → sftUSD
ftusd	unstake	Unstaked sftUSD → ftUSD
ftusd	claim	Claimed FT staking rewards
put	commit	Invested collateral into a put
put	exit	Exited a put position
put	withdraw	Withdrew FT from a put
marketplace	sell	Sold a put NFT
marketplace	buy	Bought a put NFT

---

Notes

• USD pricing: Stablecoins (USDC, USDT, DAI, ftUSD, sftUSD) = 1:1 USD. FT = $0.10. Other tokens = $0.
• Empty state: New/inactive addresses return ftBalance: 0, putsData all zeros, activity: [].
• Errors: Invalid address returns 400. All other failures degrade gracefully (partial data, zeros).
• Available on dev after next deploy (merged to main as PR #305).