{"openapi":"3.0.0","paths":{"/v1/address/{address}/portfolio":{"get":{"operationId":"getPortfolioHistory","parameters":[{"name":"address","required":true,"in":"path","description":"The wallet address","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PortfolioResponseDto"}}}}},"summary":"Returns token balance history for a given address.","tags":["Address"]}},"/health":{"get":{"operationId":"getHealth","parameters":[],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetHealthServicesResponse"}}}}},"tags":["Health"]}},"/v1/leaderboard":{"get":{"operationId":"getLeaderboard","parameters":[{"name":"season","required":false,"in":"query","description":"Season number. Defaults to current season.","schema":{"example":1,"type":"number"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LeaderboardResponse"}}}}},"summary":"Returns a list of points per user","tags":["Leaderboard"]}},"/v1/leaderboard/{address}":{"get":{"operationId":"getLeaderboardForAddress","parameters":[{"name":"address","required":true,"in":"path","description":"The address of the user","schema":{"type":"string"}},{"name":"season","required":false,"in":"query","description":"Season number. Defaults to current season.","schema":{"example":1,"type":"number"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LeaderboardResponse"}}}}},"summary":"Returns a list of points per user including given address","tags":["Leaderboard"]}},"/v1/yuty":{"get":{"operationId":"getYutyApy","parameters":[],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/YutyApyV2Response"}}}}},"summary":"Returns yUTY APY","tags":["yUty"]}},"/v1":{"get":{"operationId":"getEcosystemDetails","parameters":[],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EcosystemResponse"}}}}},"summary":"Returns ecosystem-level data for UTY and yUTY tokens","tags":["Ecosystem"]}},"/v1/uty":{"get":{"operationId":"getUtyTotalSupply","parameters":[],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UtyTotalSupplyResponse"}}}}},"summary":"Returns UTY total supply","tags":["Uty"]}},"/v1/transactions/{address}":{"get":{"description":"Returns up to 500 lifecycle rows ordered newest-first. Each request\ntargets a single chain via the required `chainId` query parameter:\n`8453` (Base, hub), `43114` (Avalanche, spoke), or `747474` (Katana, spoke).\n\nThree `kind` values: `mint` (USDC → UTY), `deposit` (UTY → yUTY), and\n`withdrawal`. yUTY withdrawals follow a cooldown → claimable → claimed\nlifecycle; UTY withdrawals are born at `claimed` (instant path).\n\nCross-chain activity (a Base claim sweep that originated from another\nchain) appears only in the spoke view. Calling per chain is the\ncanonical way to render a multi-chain history; the API does not\naggregate across chains in a single response.","operationId":"getTransactionsHistoryForAddress","parameters":[{"name":"address","required":true,"in":"path","description":"0x-prefixed 40-character wallet address (any case).","schema":{"type":"string"}},{"name":"chainId","required":true,"in":"query","description":"Supported: 8453 (Base), 43114 (Avalanche), 747474 (Katana)","schema":{"type":"number"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TransactionHistoryResponse"}}}},"400":{"description":"Returned when `address` is malformed or `chainId` is missing, not an integer, sent as an array, or not one of {8453, 43114, 747474}.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"summary":"Returns multi-chain transaction history for a given wallet address.","tags":["Transactions"]}}},"info":{"title":"YieldPoint API","description":"","version":"1.1.0","contact":{}},"tags":[],"servers":[{"url":"https://api.yieldpoint.io"}],"components":{"schemas":{"PortfolioResponseDto":{"type":"object","additionalProperties":{"type":"object","properties":{"uty":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string","description":"Date in format YYYY-MM-DD"},"timestamp":{"type":"number","description":"Unix timestamp in seconds"},"balance":{"type":"number","description":"Token balance (formatted decimal)"}},"required":["date","timestamp","balance"]}},"yuty":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string","description":"Date in format YYYY-MM-DD"},"timestamp":{"type":"number","description":"Unix timestamp in seconds"},"balance":{"type":"number","description":"Token balance (formatted decimal)"}},"required":["date","timestamp","balance"]}}},"required":["uty","yuty"]}},"GetHealthServicesResponse":{"type":"object","properties":{"status":{"type":"string","enum":["error","ok","shutting_down"]},"info":{"type":"object","additionalProperties":{"type":"object","properties":{"status":{"type":"string","enum":["up","down"]},"details":{"type":"object","additionalProperties":{}}},"required":["status"]},"nullable":true},"error":{"type":"object","additionalProperties":{"type":"object","properties":{"status":{"type":"string","enum":["up","down"]},"details":{"type":"object","additionalProperties":{}}},"required":["status"]},"nullable":true},"details":{"type":"object","additionalProperties":{"type":"object","properties":{"status":{"type":"string","enum":["up","down"]},"details":{"type":"object","additionalProperties":{}}},"required":["status"]},"nullable":true}},"required":["status"]},"LeaderboardResponse":{"type":"array","items":{"type":"object","properties":{"rank":{"type":"number"},"user":{"type":"string"},"totalPoints":{"type":"number"},"dailyRate":{"type":"number"},"daysActive":{"type":"number"},"firstActivityDate":{"type":"string"}},"required":["rank","user","totalPoints","dailyRate","daysActive","firstActivityDate"]}},"YutyApyV2Response":{"type":"object","properties":{"tokenSymbol":{"type":"string"},"address":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"},"apy":{"type":"number","nullable":true},"apy30":{"type":"number","nullable":true},"tvl":{"type":"string","nullable":true},"vaultHistory":{"type":"array","items":{"type":"object","properties":{"totalAssets":{"type":"number"},"totalSupply":{"type":"number"},"timestamp":{"type":"number"},"price":{"type":"number"},"date":{"type":"string","description":"Date in format YYYY-MM-DD"},"apy7d":{"type":"number"},"apy30d":{"type":"number"},"apy7dMovingAverage":{"type":"number"},"apy30dMovingAverage":{"type":"number"}},"required":["totalAssets","totalSupply","timestamp","price","date","apy7d","apy30d","apy7dMovingAverage","apy30dMovingAverage"]},"nullable":true}},"required":["tokenSymbol","address","apy","apy30","tvl","vaultHistory"]},"EcosystemResponse":{"type":"object","properties":{"uty":{"type":"object","properties":{"tokenSymbol":{"type":"string"},"address":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"},"totalSupply":{"type":"string","nullable":true},"tvl":{"type":"string","nullable":true}},"required":["tokenSymbol","address"]},"yuty":{"type":"object","properties":{"tokenSymbol":{"type":"string"},"address":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"},"apy":{"type":"number","nullable":true},"apy30":{"type":"number","nullable":true},"tvl":{"type":"string","nullable":true}},"required":["tokenSymbol","address"]},"cacheExpiry":{"type":"object","properties":{"timestamp":{"type":"number"},"date":{"type":"string"}},"required":["timestamp","date"]}},"required":["uty","yuty"]},"UtyTotalSupplyResponse":{"type":"object","properties":{"tokenSymbol":{"type":"string"},"address":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"},"totalSupply":{"type":"string","nullable":true,"description":"Raw wei value as a string"},"vaultHistory":{"type":"array","items":{"type":"object","properties":{"totalSupply":{"type":"number"},"date":{"type":"string","description":"Date in format YYYY-MM-DD"},"timestamp":{"type":"number","description":"Unix timestamp in seconds"}},"required":["totalSupply","date","timestamp"]},"nullable":true}},"required":["tokenSymbol","address","totalSupply","vaultHistory"]},"TransactionHistoryResponse":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Stable composite key. Mint/deposit rows: `<kind>:<chainId>:<vault>:<hash>:<eventId>`. Withdrawal lifecycle rows: `withdrawal:<chainId>:<vault>:<requestId>:<origin>` (origin is `hub` or `composer`). UTY instant withdrawal rows reuse the mint/deposit format."},"chainId":{"type":"number","description":"Chain id this row appears on. Matches the `chainId` query parameter."},"kind":{"type":"string","enum":["mint","deposit","withdrawal"],"description":"Row kind. `mint` = UTY vault deposit (USDC → UTY). `deposit` = yUTY vault deposit (UTY → yUTY). `withdrawal` = yUTY async redemption lifecycle or UTY instant redemption."},"product":{"type":"string","enum":["UTY","yUTY"]},"vault":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"},"direction":{"type":"object","properties":{"from":{"type":"string","enum":["USDC","UTY","yUTY"]},"to":{"type":"string","enum":["USDC","UTY","yUTY"]}},"required":["from","to"]},"amount":{"type":"object","properties":{"value":{"type":"string","description":"Raw integer amount as a base-10 string. Divide by 10^decimals for display."},"token":{"type":"string","enum":["USDC","UTY","yUTY"]},"address":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"},"decimals":{"type":"number"}},"required":["value","token","address","decimals"]},"status":{"type":"string","enum":["completed","locked","cooldown","claimable","claimed"],"description":"Lifecycle status. `completed` only on mint rows. `locked` only on deposit rows. `cooldown` → `claimable` → `claimed` is the yUTY withdrawal lifecycle; UTY instant withdrawals are born at `claimed`."},"hash":{"type":"string","pattern":"^0x[a-fA-F0-9]{64}$","description":"Most-recent on-chain tx hash for this row. On cross-chain rows this is the spoke-side arrival; see `hubTx` for the hub-side leg."},"blockNumber":{"type":"number"},"timestamp":{"type":"number","description":"Unix seconds of the most-recent event for this row. On withdrawal lifecycle rows this is the latest of (request, request_closed, claim) — not the original request time. See `requestedAt` for the request time."},"requestId":{"type":"number","nullable":true,"description":"Vault request id. Null on UTY instant withdrawals (no request was created). Absent on mint and deposit rows."},"requestedAt":{"type":"number","description":"Unix seconds when the redemption request was created. Required on every withdrawal row, including UTY instant (where it equals claimedAt)."},"cooldownEndsAt":{"type":"number","nullable":true,"description":"Unix seconds when the bonding period ends. Null on UTY instant withdrawals (no cooldown)."},"claimedAt":{"type":"number","nullable":true,"description":"Unix seconds when the claim settled. Null while status is cooldown or claimable."},"claimedHash":{"type":"string","pattern":"^0x[a-fA-F0-9]{64}$","nullable":true,"description":"Tx hash of the settling Withdraw event. Null while status is cooldown or claimable."},"received":{"type":"object","properties":{"value":{"type":"string","description":"Raw integer amount as a base-10 string. Divide by 10^decimals for display."},"token":{"type":"string","enum":["USDC","UTY","yUTY"]},"address":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"},"decimals":{"type":"number"}},"required":["value","token","address","decimals"],"description":"Pair amount on the output side. Populated on mint, UTY instant withdrawal, and claimed yUTY withdrawal rows. Absent on yUTY deposit rows and on cooldown/claimable withdrawal rows."},"hubTx":{"type":"string","pattern":"^0x[a-fA-F0-9]{64}$","description":"Hub-side (Base) tx hash. Populated when chainId is a spoke (43114, 747474) and the row originated cross-chain."},"hubTimestamp":{"type":"number","description":"Unix seconds of the hub-side event. Paired with hubTx on cross-chain rows."},"hubBlockNumber":{"type":"number","description":"Hub-side block number. Paired with hubTx on cross-chain rows."}},"required":["id","chainId","kind","product","vault","direction","amount","status","hash","blockNumber","timestamp"]}},"ErrorResponse":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"},"traceId":{"type":"string","nullable":true},"validation":{"type":"array","items":{"type":"string"},"nullable":true}},"required":["error","message"]}}}}