{"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).\nThe query parameter filters by `requestedOnChainId` — the chain where\nthe activity was initiated.\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\nEach row carries both `requestedOnChainId` (where the activity was\ninitiated) and `claimedOnChainId` (where the claim was settled — the\nhub for \"claim all on Base\", the spoke for OFT bridge-back). These can\ndiffer: a request initiated on Avalanche can be claimed on Base, or\nbridged back to Katana. Calling per chain is the canonical way to\nrender a multi-chain history; the API does not aggregate across chains\nin 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:<vault>:<hubRequestId>` (hub vault request id is the canonical identity for both hub-direct and composer-routed redemptions). UTY instant withdrawal rows reuse the mint/deposit format."},"requestedOnChainId":{"type":"number","description":"Chain where this activity was initiated. For hub-direct redemptions and Base mints/deposits this is `8453`. For composer-routed redemptions this is the spoke chain (`43114` Avalanche or `747474` Katana) derived from the composer's RedeemRequested.dst_eid. Matches the `chainId` query parameter on the listed row."},"claimedOnChainId":{"type":"number","nullable":true,"description":"Chain where the claim landed. `8453` when the user redeemed directly on Base (receiver=user); the spoke chain when the composer bridged UTY back via OFT (receiver=composer, dst_eid → chainId). Null while the request is still in cooldown or claimable. For mint/deposit and UTY instant withdrawal rows this equals `requestedOnChainId` (atomic, no separate claim step)."},"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"]},"sent":{"type":"object","properties":{"value":{"type":"string","nullable":true,"description":"Raw integer amount as a base-10 string. Divide by 10^decimals for display. Null when the value is not yet known on-chain — e.g., the shares-burned side of a UTY cooldown row before its WithdrawalRequest struct has been read."},"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":"Input side of the swap — the token the user is giving / has given. For mint: USDC paid in. For deposit: UTY paid in. For withdrawal: shares burned (UTY for UTY-vault redemptions, yUTY for yUTY-vault redemptions). On UTY cooldown rows the `value` is null until the WithdrawalRequest struct is read on-chain by the API enrichment pass."},"received":{"type":"object","properties":{"value":{"type":"string","nullable":true,"description":"Raw integer amount as a base-10 string. Divide by 10^decimals for display. Null when the value is not yet known on-chain — e.g., the shares-burned side of a UTY cooldown row before its WithdrawalRequest struct has been read."},"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":"Output side of the swap — the token the user is receiving / has received. For mint: UTY shares minted. For deposit: yUTY shares minted. For withdrawal: asset paid out (USDC for UTY redemptions, UTY for yUTY redemptions). On in-flight withdrawal rows the `value` reflects the asset snapshot at request time; on claimed rows it reflects the actual settled amount."},"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."},"hubTx":{"type":"string","pattern":"^0x[a-fA-F0-9]{64}$","description":"Hub-side (Base) tx hash. Populated on cross-chain rows where requestedOnChainId or claimedOnChainId is a spoke (43114, 747474)."},"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","requestedOnChainId","claimedOnChainId","kind","product","vault","direction","sent","received","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"]}}}}