feat: display 24h key price twap

Author: zeemscript

src/hooks/useKeyTwap.ts

@@ -0,0 +1,13 @@
+import { useQuery } from '@tanstack/react-query';
+import { queryKeys } from '@/lib/queryKeys';
+import { courseService } from '@/services/course.service';
+
+export function useKeyTwap(keyId: string) {
+	return useQuery({
+		queryKey: queryKeys.creators.twap(keyId),
+		queryFn: () => courseService.getKeyTwap(keyId),
+		enabled: !!keyId,
+		staleTime: 60_000,
+		retry: false,
+	});
+}

src/lib/queryKeys.ts

@@ -25,6 +25,8 @@ export const queryKeys = {
 			['creators', creatorId, 'holders'] as const,
 		activity: (creatorId: string) =>
 			['creators', creatorId, 'activity'] as const,
+		twap: (creatorId: string) =>
+			['creators', creatorId, 'twap', '24h'] as const,
 	},
 	wallet: {
 		holdings: (address: string) => ['wallet', address, 'holdings'] as const,

src/pages/CreatorDetailPage.tsx

@@ -17,6 +17,9 @@ import KeyDetailPageErrorBoundary from '@/components/common/KeyDetailPageErrorBo
 import { ApiError } from '@/services/api.service';
 import { useKeyHolders } from '@/hooks/useKeyHolders';
 import { useNavigationTiming } from '@/hooks/useNavigationTiming';
+import { useKeyTwap } from '@/hooks/useKeyTwap';
+import Skeleton from '@/components/ui/skeleton';
+import { Tooltip } from '@/components/ui/tooltip';
 
 function CreatorDetailPageContent() {
 	const { id } = useParams<{ id: string }>();
@@ -35,6 +38,7 @@ function CreatorDetailPageContent() {
 		isFetchingNextPage,
 		fetchNextPage,
 	} = useKeyHolders(id || '');
+	const { data: twap, isLoading: isTwapLoading } = useKeyTwap(id || '');
 
 	// Track stale data indicator
 	const { shouldShowBadge, handleRefetch } = useCreatorProfileStaleIndicator(
@@ -100,6 +104,9 @@ function CreatorDetailPageContent() {
 		supply: (index + 1) * 20,
 		priceXLM: priceStroops / 10_000_000,
 	}));
+	const spotPrice = resolveCreatorKeyPriceStroops(creator);
+	const twapPrice = twap?.priceStroops ?? null;
+	const twapDelta = twapPrice != null && spotPrice != null ? twapPrice - spotPrice : null;
 
 	const defaultHolders = [
 		{ id: 'h1', displayName: 'Early Adopter', keyCount: 25, stakedQuantity: 18 },
@@ -152,6 +159,25 @@ function CreatorDetailPageContent() {
 					<CreatorProfileStatRow items={statItems} />
 				</div>
 
+				<div className="rounded-2xl border border-white/10 bg-white/[0.03] px-5 py-4" data-testid="twap-price">
+					{isTwapLoading ? (
+						<div aria-label="Loading 24 hour TWAP" role="status"><Skeleton className="h-3 w-24" /><Skeleton className="mt-2 h-6 w-32" /></div>
+					) : twapPrice != null ? (
+						<div className="flex items-center justify-between gap-4">
+							<div>
+								<div className="flex items-center gap-2 text-xs font-semibold uppercase tracking-wider text-white/55">
+									<span>TWAP (24h)</span>
+									<Tooltip content="Time-weighted average key price over the last 24 hours.">
+										<button type="button" aria-label="What is 24 hour TWAP?" className="text-white/50">ⓘ</button>
+									</Tooltip>
+								</div>
+								<div className="mt-1 text-xl font-bold text-white">{formatDisplayKeyPrice(twapPrice)}</div>
+							</div>
+							{twapDelta != null && <span className={twapDelta >= 0 ? 'text-sm font-semibold text-emerald-400' : 'text-sm font-semibold text-rose-400'}>{twapDelta >= 0 ? '▲' : '▼'} {formatDisplayKeyPrice(Math.abs(twapDelta))} vs spot</span>}
+						</div>
+					) : null}
+				</div>
+
 				{/* Staking Rewards */}
 				<StakingRewardsSection
 					{...stakingStats}

src/services/course.service.ts

@@ -101,6 +101,12 @@ export interface KeyHoldersPage {
 	nextCursor: string | null;
 }
 
+export interface KeyTwap {
+	/** 24-hour time-weighted average price in stroops. */
+	priceStroops: number | null;
+	window?: string;
+}
+
 class CourseService extends BaseApiService {
 	private readonly PROFILE_CACHE_TTL = 30000; // 30 seconds
 
@@ -204,6 +210,19 @@ class CourseService extends BaseApiService {
 		}
 	}
 
+	// Get the time-weighted average price - GET /keys/:keyId/twap
+	async getKeyTwap(keyId: string, window = '24h'): Promise<KeyTwap> {
+		try {
+			const response = await this.api.get<APIResponse<KeyTwap>>(
+				`/keys/${keyId}/twap`,
+				{ params: { window } }
+			);
+			return response.data.data;
+		} catch (error) {
+			throw this.handleError(error);
+		}
+	}
+
 	// Get enrolled courses - GET /courses/enrolled
 	async getEnrolledCourses(): Promise<Course[]> {
 		try {