From 3d00697788e721e1d73f5d29d11cfd1d157299d5 Mon Sep 17 00:00:00 2001
From: auralshin <anshulspartan141@gmail.com>
Date: Tue, 2 Jun 2026 18:01:54 +0530
Subject: [PATCH 1/3] feat: implement KYC flow with verification screens and
 API integration

---
 packages/widget/src/Widget.tsx                |  2 +
 .../components/atoms/icons/shield-check.tsx   | 34 +++++++
 .../molecules/kyc-iframe-modal/index.tsx      | 64 +++++++++++++
 .../molecules/kyc-iframe-modal/styles.css.ts  | 71 ++++++++++++++
 packages/widget/src/domain/types/kyc.ts       | 87 ++++++++++++++++++
 .../widget/src/hooks/api/use-kyc-status.ts    | 43 +++++++++
 .../earn-page/state/earn-page-context.tsx     | 11 ++-
 .../pages/kyc/identity-verification.page.tsx  | 92 +++++++++++++++++++
 .../widget/src/pages/kyc/kyc-gate.page.tsx    | 92 +++++++++++++++++++
 .../widget/src/providers/api/api-client.ts    | 25 ++++-
 .../src/translation/English/translations.json | 18 ++++
 .../src/translation/French/translations.json  | 18 ++++
 .../use-cases/kyc-flow/kyc-flow.test.tsx      | 61 ++++++++++++
 .../use-cases/kyc-flow/kyc-helpers.test.ts    | 54 +++++++++++
 .../widget/tests/use-cases/kyc-flow/setup.ts  | 37 ++++++++
 15 files changed, 707 insertions(+), 2 deletions(-)
 create mode 100644 packages/widget/src/components/atoms/icons/shield-check.tsx
 create mode 100644 packages/widget/src/components/molecules/kyc-iframe-modal/index.tsx
 create mode 100644 packages/widget/src/components/molecules/kyc-iframe-modal/styles.css.ts
 create mode 100644 packages/widget/src/domain/types/kyc.ts
 create mode 100644 packages/widget/src/hooks/api/use-kyc-status.ts
 create mode 100644 packages/widget/src/pages/kyc/identity-verification.page.tsx
 create mode 100644 packages/widget/src/pages/kyc/kyc-gate.page.tsx
 create mode 100644 packages/widget/tests/use-cases/kyc-flow/kyc-flow.test.tsx
 create mode 100644 packages/widget/tests/use-cases/kyc-flow/kyc-helpers.test.ts
 create mode 100644 packages/widget/tests/use-cases/kyc-flow/setup.ts

diff --git a/packages/widget/src/Widget.tsx b/packages/widget/src/Widget.tsx
index 9cacb450..b96faa41 100644
--- a/packages/widget/src/Widget.tsx
+++ b/packages/widget/src/Widget.tsx
@@ -24,6 +24,7 @@ import { AnimatedActivityPage } from "./pages/details/activity-page/activity.pag
 import { Details } from "./pages/details/details-page/details.page";
 import { AnimatedEarnPage } from "./pages/details/earn-page/earn.page";
 import { AnimatedPositionsPage } from "./pages/details/positions-page/positions.page";
+import { KycGatePage } from "./pages/kyc/kyc-gate.page";
 import { PositionDetailsPage } from "./pages/position-details";
 import { StakeReviewPage } from "./pages/review";
 import { ActionReviewPage } from "./pages/review/pages/action-review.page";
@@ -133,6 +134,7 @@ export const Widget = () => {
 
                     {/* Stake flow */}
                     <Route>
+                      <Route path="kyc" element={<KycGatePage />} />
                       <Route path="review" element={<StakeReviewPage />} />
                       <Route path="steps" element={<StakeStepsPage />} />
                       <Route path="complete" element={<StakeCompletePage />} />
diff --git a/packages/widget/src/components/atoms/icons/shield-check.tsx b/packages/widget/src/components/atoms/icons/shield-check.tsx
new file mode 100644
index 00000000..e41faae4
--- /dev/null
+++ b/packages/widget/src/components/atoms/icons/shield-check.tsx
@@ -0,0 +1,34 @@
+import { vars } from "../../../styles/theme/contract.css";
+
+export const ShieldCheckIcon = ({
+  width,
+  height,
+  color = "text",
+}: {
+  width?: number;
+  height?: number;
+  color?: Exclude<keyof (typeof vars)["color"], "connectKit">;
+}) => (
+  <svg
+    width={width ?? 48}
+    height={height ?? 48}
+    fill="none"
+    xmlns="http://www.w3.org/2000/svg"
+    viewBox="0 0 24 24"
+  >
+    <path
+      d="M12 2 4 5v6c0 5 3.4 8.27 8 10 4.6-1.73 8-5 8-10V5l-8-3Z"
+      stroke={vars.color[color]}
+      strokeWidth={1.5}
+      strokeLinecap="round"
+      strokeLinejoin="round"
+    />
+    <path
+      d="m8.75 12 2.25 2.25L15.5 9.75"
+      stroke={vars.color[color]}
+      strokeWidth={1.5}
+      strokeLinecap="round"
+      strokeLinejoin="round"
+    />
+  </svg>
+);
diff --git a/packages/widget/src/components/molecules/kyc-iframe-modal/index.tsx b/packages/widget/src/components/molecules/kyc-iframe-modal/index.tsx
new file mode 100644
index 00000000..5595d8bd
--- /dev/null
+++ b/packages/widget/src/components/molecules/kyc-iframe-modal/index.tsx
@@ -0,0 +1,64 @@
+import { Content, Overlay, Portal, Root, Title } from "@radix-ui/react-dialog";
+import { useContext } from "react";
+import { SettingsContext } from "../../../providers/settings";
+import { id } from "../../../styles/theme/ids";
+import { Box } from "../../atoms/box";
+import { XIcon } from "../../atoms/icons/x-icon";
+import { Text } from "../../atoms/typography/text";
+import { container, content, iframe, overlay } from "./styles.css";
+
+export type KycIframeModalProps = {
+  open: boolean;
+  onOpenChange: (open: boolean) => void;
+  url: string;
+  title: string;
+};
+
+export const KycIframeModal = ({
+  open,
+  onOpenChange,
+  url,
+  title,
+}: KycIframeModalProps) => {
+  const portalContainer = useContext(SettingsContext)?.portalContainer;
+
+  return (
+    <Root open={open} onOpenChange={onOpenChange}>
+      <Portal container={portalContainer}>
+        <Box className={container} data-rk={id}>
+          <Overlay onClick={() => onOpenChange(false)} className={overlay} />
+
+          <Content
+            data-testid="kyc-iframe-modal__container"
+            className={content}
+            aria-describedby={undefined}
+          >
+            <Box
+              display="flex"
+              justifyContent="space-between"
+              alignItems="center"
+              px="4"
+              py="3"
+            >
+              <Title>
+                <Text variant={{ weight: "bold", size: "large" }}>{title}</Text>
+              </Title>
+
+              <Box as="button" onClick={() => onOpenChange(false)}>
+                <XIcon />
+              </Box>
+            </Box>
+
+            <iframe
+              data-testid="kyc-iframe-modal__iframe"
+              title={title}
+              src={url}
+              allow="camera; microphone; clipboard-write"
+              className={iframe}
+            />
+          </Content>
+        </Box>
+      </Portal>
+    </Root>
+  );
+};
diff --git a/packages/widget/src/components/molecules/kyc-iframe-modal/styles.css.ts b/packages/widget/src/components/molecules/kyc-iframe-modal/styles.css.ts
new file mode 100644
index 00000000..7c3bd625
--- /dev/null
+++ b/packages/widget/src/components/molecules/kyc-iframe-modal/styles.css.ts
@@ -0,0 +1,71 @@
+import { keyframes, style } from "@vanilla-extract/css";
+import { atoms } from "../../../styles/theme/atoms.css";
+import { vars } from "../../../styles/theme/contract.css";
+import { breakpoints, minMediaQuery } from "../../../styles/tokens/breakpoints";
+
+const slideUp = keyframes({
+  "0%": { transform: "translateY(20%)" },
+  "100%": { transform: "translateY(0)" },
+});
+
+const fadeIn = keyframes({
+  "0%": { opacity: 0 },
+  "100%": { opacity: 1 },
+});
+
+export const container = style({
+  zIndex: 20,
+  display: "flex",
+  justifyContent: "center",
+  alignItems: "center",
+  position: "fixed",
+  top: 0,
+  bottom: 0,
+  left: 0,
+  right: 0,
+});
+
+export const overlay = style({
+  animation: `${fadeIn} 150ms ease`,
+  willChange: "opacity",
+  position: "absolute",
+  inset: 0,
+  background: vars.color.modalOverlayBackground,
+});
+
+export const content = style([
+  {
+    "@media": {
+      [minMediaQuery("tablet")]: {
+        width: "440px",
+        height: "640px",
+        maxHeight: "85vh",
+        bottom: "auto",
+        borderBottomLeftRadius: vars.borderRadius.baseContract["2xl"],
+        borderBottomRightRadius: vars.borderRadius.baseContract["2xl"],
+      },
+    },
+    animation: `${slideUp} 350ms cubic-bezier(.15,1.15,0.6,1.00), ${fadeIn} 150ms ease`,
+    willChange: "transform, opacity",
+  },
+  atoms({
+    width: "full",
+    background: "modalBodyBackground",
+  }),
+  {
+    display: "flex",
+    flexDirection: "column",
+    borderTopLeftRadius: vars.borderRadius.baseContract["2xl"],
+    borderTopRightRadius: vars.borderRadius.baseContract["2xl"],
+    maxWidth: `${breakpoints.tablet}px`,
+    position: "absolute",
+    height: "90vh",
+    bottom: 0,
+  },
+]);
+
+export const iframe = style({
+  flex: 1,
+  width: "100%",
+  border: "none",
+});
diff --git a/packages/widget/src/domain/types/kyc.ts b/packages/widget/src/domain/types/kyc.ts
new file mode 100644
index 00000000..f308842b
--- /dev/null
+++ b/packages/widget/src/domain/types/kyc.ts
@@ -0,0 +1,87 @@
+import type { Yield } from "./yields";
+
+// kyc contract is not in the generated client yet; mirrored from the api here
+
+export enum KycStatus {
+  NotRequired = "not_required",
+  NotStarted = "not_started",
+  Pending = "pending",
+  Approved = "approved",
+  Rejected = "rejected",
+}
+
+export enum KycMode {
+  OauthRedirect = "oauth_redirect",
+}
+
+export enum KycAccreditation {
+  Retail = "retail",
+  QualifiedPurchaser = "qualified_purchaser",
+  Accredited = "accredited",
+}
+
+export enum KycSubjectType {
+  Kyc = "KYC",
+  Kyb = "KYB",
+}
+
+export interface YieldKycEligibility {
+  countries?: string[];
+  usPersonAllowed?: boolean;
+  accreditation?: KycAccreditation;
+  subjectType?: KycSubjectType;
+}
+
+export interface YieldKycMetadata {
+  kycMode: KycMode;
+  iframeAllowed: boolean;
+  authorizeUrl?: string;
+  notes?: string;
+  eligibility?: YieldKycEligibility;
+}
+
+export type KycStatusResult = {
+  kycStatus: KycStatus;
+  kycUrl?: string;
+};
+
+type RequirementsWithKyc = {
+  readonly kycRequired?: boolean;
+  readonly kycUrl?: string;
+  readonly kyc?: YieldKycMetadata;
+};
+
+export type YieldKycRequirement = {
+  required: boolean;
+  kyc?: YieldKycMetadata;
+  legacyKycUrl?: string;
+};
+
+export const getYieldKycRequirement = (
+  yieldDto: Yield
+): YieldKycRequirement => {
+  // kyc block is not in the generated requirements type yet
+  const requirements = yieldDto.mechanics.requirements as
+    | RequirementsWithKyc
+    | undefined;
+
+  return {
+    required: !!requirements?.kycRequired || !!requirements?.kyc,
+    kyc: requirements?.kyc,
+    legacyKycUrl: requirements?.kycUrl,
+  };
+};
+
+// statuses that block entry
+export const kycNeedsVerification = (status: KycStatus): boolean =>
+  status === KycStatus.NotStarted ||
+  status === KycStatus.Pending ||
+  status === KycStatus.Rejected;
+
+// live per-address kycUrl wins over the static issuer page
+export const resolveKycUrl = (args: {
+  statusKycUrl?: string;
+  kyc?: YieldKycMetadata;
+  legacyKycUrl?: string;
+}): string | undefined =>
+  args.statusKycUrl ?? args.kyc?.authorizeUrl ?? args.legacyKycUrl;
diff --git a/packages/widget/src/hooks/api/use-kyc-status.ts b/packages/widget/src/hooks/api/use-kyc-status.ts
new file mode 100644
index 00000000..01c60ea4
--- /dev/null
+++ b/packages/widget/src/hooks/api/use-kyc-status.ts
@@ -0,0 +1,43 @@
+import { useQuery } from "@tanstack/react-query";
+import type { Maybe } from "purify-ts";
+import {
+  getYieldKycRequirement,
+  type KycStatusResult,
+} from "../../domain/types/kyc";
+import type { Yield } from "../../domain/types/yields";
+import { useApiClient } from "../../providers/api/api-client-provider";
+import { useSKWallet } from "../../providers/sk-wallet";
+
+const getKycStatusQueryKey = (yieldId: string, address: string) =>
+  ["kyc-status", yieldId, address] as const;
+
+export const useKycStatus = (
+  yieldId: string | undefined,
+  address: string | null | undefined,
+  opts?: { enabled?: boolean }
+) => {
+  const apiClient = useApiClient();
+
+  return useQuery<KycStatusResult>({
+    queryKey: getKycStatusQueryKey(yieldId ?? "", address ?? ""),
+    queryFn: ({ signal }) =>
+      apiClient.getKycStatus(yieldId as string, address as string, { signal }),
+    // per-address, so short cache
+    staleTime: 1000 * 30,
+    enabled: !!yieldId && !!address && (opts?.enabled ?? true),
+  });
+};
+
+// prefetch so the gate is resolved before the cta is clicked
+export const useKycStatusPrefetch = (selectedStake: Maybe<Yield>) => {
+  const { address, isConnected } = useSKWallet();
+
+  const yieldDto = selectedStake.extractNullable();
+  const requiresKyc = yieldDto
+    ? getYieldKycRequirement(yieldDto).required
+    : false;
+
+  return useKycStatus(yieldDto?.id, address, {
+    enabled: isConnected && requiresKyc,
+  });
+};
diff --git a/packages/widget/src/pages/details/earn-page/state/earn-page-context.tsx b/packages/widget/src/pages/details/earn-page/state/earn-page-context.tsx
index e687acee..940acb94 100644
--- a/packages/widget/src/pages/details/earn-page/state/earn-page-context.tsx
+++ b/packages/widget/src/pages/details/earn-page/state/earn-page-context.tsx
@@ -21,6 +21,7 @@ import {
   stakeTokenSameAsGasToken,
   tokenString,
 } from "../../../../domain";
+import { getYieldKycRequirement } from "../../../../domain/types/kyc";
 import { getInitSelectedValidators } from "../../../../domain/types/stake";
 import type { TokenBalanceScanResponseDto } from "../../../../domain/types/token-balance";
 import type { TronResourceType } from "../../../../domain/types/tron";
@@ -38,6 +39,7 @@ import {
   type Yield,
 } from "../../../../domain/types/yields";
 import { useDefaultTokens } from "../../../../hooks/api/use-default-tokens";
+import { useKycStatusPrefetch } from "../../../../hooks/api/use-kyc-status";
 import { useStreamMultiYields } from "../../../../hooks/api/use-multi-yields";
 import { useTokenBalancesScan } from "../../../../hooks/api/use-token-balances-scan";
 import { useTokensPrices } from "../../../../hooks/api/use-tokens-prices";
@@ -103,6 +105,9 @@ export const EarnPageContextProvider = ({ children }: PropsWithChildren) => {
   const { isConnected, isConnecting, isLedgerLiveAccountPlaceholder, chain } =
     useSKWallet();
 
+  // prefetch kyc status for the gate
+  useKycStatusPrefetch(selectedStake);
+
   const yieldType = useYieldType(selectedStake).mapOrDefault(
     (y) => y.title,
     ""
@@ -485,7 +490,11 @@ export const EarnPageContextProvider = ({ children }: PropsWithChildren) => {
           selectedValidators: val.stakeEnterRequestDto.selectedValidators,
         },
       });
-      navigate("/review");
+
+      const requiresKyc = getYieldKycRequirement(
+        val.stakeEnterRequestDto.selectedStake
+      ).required;
+      navigate(requiresKyc ? "/kyc" : "/review");
     },
   });
 
diff --git a/packages/widget/src/pages/kyc/identity-verification.page.tsx b/packages/widget/src/pages/kyc/identity-verification.page.tsx
new file mode 100644
index 00000000..aa9a4db1
--- /dev/null
+++ b/packages/widget/src/pages/kyc/identity-verification.page.tsx
@@ -0,0 +1,92 @@
+import { useMemo } from "react";
+import { useTranslation } from "react-i18next";
+import { Box } from "../../components/atoms/box";
+import { ShieldCheckIcon } from "../../components/atoms/icons/shield-check";
+import { Heading } from "../../components/atoms/typography/heading";
+import { Text } from "../../components/atoms/typography/text";
+import { KycStatus, type YieldKycMetadata } from "../../domain/types/kyc";
+import { useRegisterFooterButton } from "../components/footer-outlet/context";
+
+const copyByStatus = {
+  [KycStatus.NotStarted]: {
+    title: "kyc.not_started.title",
+    description: "kyc.not_started.description",
+    cta: "kyc.not_started.cta",
+  },
+  [KycStatus.Pending]: {
+    title: "kyc.pending.title",
+    description: "kyc.pending.description",
+    cta: "kyc.pending.cta",
+  },
+  [KycStatus.Rejected]: {
+    title: "kyc.rejected.title",
+    description: "kyc.rejected.description",
+    cta: "kyc.rejected.cta",
+  },
+} as const;
+
+type IdentityVerificationScreenProps = {
+  status: KycStatus;
+  kyc?: YieldKycMetadata;
+  // false when no verification url resolved
+  canVerify: boolean;
+  onVerify: () => void;
+};
+
+export const IdentityVerificationScreen = ({
+  status,
+  kyc,
+  canVerify,
+  onVerify,
+}: IdentityVerificationScreenProps) => {
+  const { t } = useTranslation();
+
+  const copy =
+    copyByStatus[status as keyof typeof copyByStatus] ??
+    copyByStatus[KycStatus.NotStarted];
+
+  useRegisterFooterButton(
+    useMemo(
+      () => ({
+        disabled: !canVerify,
+        isLoading: false,
+        label: t(copy.cta),
+        onClick: onVerify,
+      }),
+      [canVerify, copy.cta, onVerify, t]
+    )
+  );
+
+  return (
+    <Box
+      data-testid="kyc-verification-screen"
+      flex={1}
+      display="flex"
+      flexDirection="column"
+      alignItems="center"
+      justifyContent="center"
+      textAlign="center"
+      my="4"
+    >
+      <Box my="4">
+        <ShieldCheckIcon
+          color={status === KycStatus.Rejected ? "textDanger" : "text"}
+        />
+      </Box>
+
+      <Heading variant={{ level: "h4" }} marginBottom="4">
+        {t(copy.title)}
+      </Heading>
+
+      <Text variant={{ type: "muted", weight: "normal" }} marginBottom="4">
+        {t(copy.description)}
+      </Text>
+
+      {kyc?.notes && (
+        <Text variant={{ type: "muted", weight: "normal", size: "small" }}>
+          {kyc.notes}
+        </Text>
+      )}
+    </Box>
+  );
+};
diff --git a/packages/widget/src/pages/kyc/kyc-gate.page.tsx b/packages/widget/src/pages/kyc/kyc-gate.page.tsx
new file mode 100644
index 00000000..019af282
--- /dev/null
+++ b/packages/widget/src/pages/kyc/kyc-gate.page.tsx
@@ -0,0 +1,92 @@
+import { useSelector } from "@xstate/store/react";
+import { useCallback, useState } from "react";
+import { useTranslation } from "react-i18next";
+import { Navigate } from "react-router";
+import { Box } from "../../components/atoms/box";
+import { Spinner } from "../../components/atoms/spinner";
+import { KycIframeModal } from "../../components/molecules/kyc-iframe-modal";
+import {
+  getYieldKycRequirement,
+  KycStatus,
+  kycNeedsVerification,
+  resolveKycUrl,
+} from "../../domain/types/kyc";
+import { useKycStatus } from "../../hooks/api/use-kyc-status";
+import { AnimationPage } from "../../navigation/containers/animation-page";
+import { useEnterStakeStore } from "../../providers/enter-stake-store";
+import { useSKWallet } from "../../providers/sk-wallet";
+import { PageContainer } from "../components/page-container";
+import { IdentityVerificationScreen } from "./identity-verification.page";
+
+export const KycGatePage = () => {
+  const { t } = useTranslation();
+  const enterStore = useEnterStakeStore();
+  const { address } = useSKWallet();
+
+  const data = useSelector(enterStore, (state) => state.context.data);
+  const yieldDto = data.map((d) => d.selectedStake).extractNullable();
+
+  const statusQuery = useKycStatus(yieldDto?.id, address, {
+    enabled: !!yieldDto,
+  });
+
+  const [modalOpen, setModalOpen] = useState(false);
+  const onVerify = useCallback(() => setModalOpen(true), []);
+
+  // no flow context (direct nav) → home
+  if (!yieldDto) return <Navigate to="/" replace />;
+
+  if (statusQuery.isLoading) {
+    return (
+      <AnimationPage>
+        <PageContainer>
+          <Box
+            flex={1}
+            display="flex"
+            alignItems="center"
+            justifyContent="center"
+            my="4"
+          >
+            <Spinner />
+          </Box>
+        </PageContainer>
+      </AnimationPage>
+    );
+  }
+
+  // fail closed: missing status blocks entry
+  const status = statusQuery.data?.kycStatus ?? KycStatus.NotStarted;
+
+  if (!kycNeedsVerification(status)) {
+    return <Navigate to="/review" replace />;
+  }
+
+  const requirement = getYieldKycRequirement(yieldDto);
+  const url = resolveKycUrl({
+    statusKycUrl: statusQuery.data?.kycUrl,
+    kyc: requirement.kyc,
+    legacyKycUrl: requirement.legacyKycUrl,
+  });
+
+  return (
+    <AnimationPage>
+      <PageContainer>
+        <IdentityVerificationScreen
+          status={status}
+          kyc={requirement.kyc}
+          canVerify={!!url}
+          onVerify={onVerify}
+        />
+
+        {url && (
+          <KycIframeModal
+            open={modalOpen}
+            onOpenChange={setModalOpen}
+            url={url}
+            title={t("kyc.modal_title")}
+          />
+        )}
+      </PageContainer>
+    </AnimationPage>
+  );
+};
diff --git a/packages/widget/src/providers/api/api-client.ts b/packages/widget/src/providers/api/api-client.ts
index f441f2eb..c0d66494 100644
--- a/packages/widget/src/providers/api/api-client.ts
+++ b/packages/widget/src/providers/api/api-client.ts
@@ -3,9 +3,10 @@ import {
   FetchHttpClient,
   HttpClient,
   HttpClientRequest,
-  type HttpClientResponse,
+  HttpClientResponse,
 } from "effect/unstable/http";
 import { waitForDelayedApiRequests } from "../../common/delay-api-requests";
+import type { KycStatusResult } from "../../domain/types/kyc";
 import * as LegacyApi from "../../generated/api/legacy";
 import * as YieldApi from "../../generated/api/yield";
 import { handleGeoBlockResponse } from "../../hooks/use-geo-block";
@@ -247,8 +248,30 @@ export const createApiClient = ({
   const yieldApi = YieldApi.make(yieldHttpClient);
   const boundClients = bindApiClients({ legacyApi, runtime, yieldApi });
 
+  // not in the generated client yet; runs through the configured yield client
+  const getKycStatus = (
+    yieldId: string,
+    address: string,
+    runOptions?: RunOptions
+  ): Promise<KycStatusResult> =>
+    runtime.runPromise(
+      yieldHttpClient
+        .execute(
+          HttpClientRequest.get(`/v1/yields/${yieldId}/kyc/status`).pipe(
+            HttpClientRequest.setUrlParams({ address })
+          )
+        )
+        .pipe(
+          Effect.flatMap(HttpClientResponse.filterStatusOk),
+          Effect.flatMap((response) => response.json),
+          Effect.map((data) => data as KycStatusResult)
+        ),
+      runOptions
+    );
+
   return {
     ...boundClients,
+    getKycStatus,
     withRunOptions: (runOptions: RunOptions) =>
       bindApiClients({ legacyApi, runOptions, runtime, yieldApi }),
     dispose: () => runtime.dispose(),
diff --git a/packages/widget/src/translation/English/translations.json b/packages/widget/src/translation/English/translations.json
index d4ad99e1..c93dd18f 100644
--- a/packages/widget/src/translation/English/translations.json
+++ b/packages/widget/src/translation/English/translations.json
@@ -1,4 +1,22 @@
 {
+  "kyc": {
+    "modal_title": "Identity verification",
+    "not_started": {
+      "title": "Identity verification required",
+      "description": "This opportunity requires you to verify your identity before you can continue.",
+      "cta": "Verify identity"
+    },
+    "pending": {
+      "title": "Verification in progress",
+      "description": "Your identity verification is being reviewed. This can take a little while — you can resume with the provider if you haven't finished.",
+      "cta": "Continue verification"
+    },
+    "rejected": {
+      "title": "Verification unsuccessful",
+      "description": "We couldn't verify your identity. Please try again with the verification provider.",
+      "cta": "Retry verification"
+    }
+  },
   "shared": {
     "stake_kit": "Yield.xyz",
     "max": "Max",
diff --git a/packages/widget/src/translation/French/translations.json b/packages/widget/src/translation/French/translations.json
index 50ad0f2d..6af44cfc 100644
--- a/packages/widget/src/translation/French/translations.json
+++ b/packages/widget/src/translation/French/translations.json
@@ -1,4 +1,22 @@
 {
+  "kyc": {
+    "modal_title": "Vérification d'identité",
+    "not_started": {
+      "title": "Vérification d'identité requise",
+      "description": "Cette opportunité nécessite la vérification de votre identité avant de continuer.",
+      "cta": "Vérifier mon identité"
+    },
+    "pending": {
+      "title": "Vérification en cours",
+      "description": "Votre vérification d'identité est en cours d'examen. Cela peut prendre un moment — vous pouvez la reprendre avec le prestataire si elle n'est pas terminée.",
+      "cta": "Continuer la vérification"
+    },
+    "rejected": {
+      "title": "Vérification échouée",
+      "description": "Nous n'avons pas pu vérifier votre identité. Veuillez réessayer avec le prestataire de vérification.",
+      "cta": "Réessayer la vérification"
+    }
+  },
   "shared": {
     "stake_kit": "Yield.xyz",
     "max": "Max",
diff --git a/packages/widget/tests/use-cases/kyc-flow/kyc-flow.test.tsx b/packages/widget/tests/use-cases/kyc-flow/kyc-flow.test.tsx
new file mode 100644
index 00000000..f5e48189
--- /dev/null
+++ b/packages/widget/tests/use-cases/kyc-flow/kyc-flow.test.tsx
@@ -0,0 +1,61 @@
+import { userEvent } from "vitest/browser";
+import { formatAddress } from "../../../src/utils";
+import { describe, expect, it } from "../../utils/test-extend";
+import { renderApp } from "../../utils/test-utils";
+import { setup } from "./setup";
+
+describe("KYC gate flow", () => {
+  it("gates entry behind the verification screen and opens the issuer iframe", async ({
+    worker,
+  }) => {
+    const { customConnectors, account, kycUrl } = await setup(worker);
+
+    const app = await renderApp({
+      wagmi: {
+        __customConnectors__: customConnectors,
+        forceWalletConnectOnly: false,
+      },
+    });
+
+    await expect
+      .element(app.getByText(formatAddress(account)))
+      .toBeInTheDocument();
+
+    await app.getByTestId("select-opportunity").click();
+
+    await app
+      .getByTestId("select-modal__container")
+      .getByTestId(/^select-opportunity__item_avalanche-avax-liquid-staking/)
+      .click();
+
+    await expect
+      .poll(
+        () => app.getByTestId("select-opportunity").getByText("AVAX").length
+      )
+      .greaterThan(0);
+
+    await userEvent.click(app.getByTestId("number-input"));
+    await userEvent.keyboard("0.1");
+    await expect.element(app.getByTestId("number-input")).toHaveValue("0.1");
+
+    await expect.element(app.getByText("Stake").first()).toBeInTheDocument();
+    await userEvent.click(app.getByText("Stake").last());
+
+    // KYC required + not_started → verification screen, not /review.
+    await expect
+      .element(app.getByTestId("kyc-verification-screen"))
+      .toBeInTheDocument();
+    await expect
+      .element(app.getByText("Identity verification required").first())
+      .toBeInTheDocument();
+
+    // CTA opens the issuer KYC page in the iframe modal.
+    await userEvent.click(app.getByText("Verify identity").last());
+
+    const iframe = app.getByTestId("kyc-iframe-modal__iframe");
+    await expect.element(iframe).toBeInTheDocument();
+    await expect.element(iframe).toHaveAttribute("src", kycUrl);
+
+    app.unmount();
+  });
+});
diff --git a/packages/widget/tests/use-cases/kyc-flow/kyc-helpers.test.ts b/packages/widget/tests/use-cases/kyc-flow/kyc-helpers.test.ts
new file mode 100644
index 00000000..11007f37
--- /dev/null
+++ b/packages/widget/tests/use-cases/kyc-flow/kyc-helpers.test.ts
@@ -0,0 +1,54 @@
+import { describe, expect, it } from "vitest";
+import {
+  getYieldKycRequirement,
+  KycMode,
+  KycStatus,
+  kycNeedsVerification,
+  resolveKycUrl,
+} from "../../../src/domain/types/kyc";
+import type { Yield } from "../../../src/domain/types/yields";
+
+const yieldWith = (requirements: unknown) =>
+  ({ mechanics: { requirements } }) as unknown as Yield;
+
+const kycMeta = { kycMode: KycMode.OauthRedirect, iframeAllowed: true };
+
+describe("KYC helpers", () => {
+  it("flags requirement from legacy kycRequired and the kyc block", () => {
+    expect(getYieldKycRequirement(yieldWith(undefined)).required).toBe(false);
+    expect(
+      getYieldKycRequirement(yieldWith({ kycRequired: true })).required
+    ).toBe(true);
+    expect(getYieldKycRequirement(yieldWith({ kyc: kycMeta })).required).toBe(
+      true
+    );
+  });
+
+  it("blocks entry only for non-approved, non-exempt statuses", () => {
+    expect(kycNeedsVerification(KycStatus.NotStarted)).toBe(true);
+    expect(kycNeedsVerification(KycStatus.Pending)).toBe(true);
+    expect(kycNeedsVerification(KycStatus.Rejected)).toBe(true);
+    expect(kycNeedsVerification(KycStatus.Approved)).toBe(false);
+    expect(kycNeedsVerification(KycStatus.NotRequired)).toBe(false);
+  });
+
+  it("prefers live status url, then metadata, then legacy", () => {
+    expect(
+      resolveKycUrl({
+        statusKycUrl: "https://live",
+        kyc: { ...kycMeta, authorizeUrl: "https://meta" },
+        legacyKycUrl: "https://legacy",
+      })
+    ).toBe("https://live");
+    expect(
+      resolveKycUrl({
+        kyc: { ...kycMeta, authorizeUrl: "https://meta" },
+        legacyKycUrl: "https://legacy",
+      })
+    ).toBe("https://meta");
+    expect(resolveKycUrl({ legacyKycUrl: "https://legacy" })).toBe(
+      "https://legacy"
+    );
+    expect(resolveKycUrl({})).toBeUndefined();
+  });
+});
diff --git a/packages/widget/tests/use-cases/kyc-flow/setup.ts b/packages/widget/tests/use-cases/kyc-flow/setup.ts
new file mode 100644
index 00000000..d5557962
--- /dev/null
+++ b/packages/widget/tests/use-cases/kyc-flow/setup.ts
@@ -0,0 +1,37 @@
+import { delay, HttpResponse, http } from "msw";
+import { yieldApiRoute } from "../../mocks/api-routes";
+import type { TestWorker } from "../../utils/test-extend";
+import { setup as stakingSetup } from "../staking-flow/setup";
+
+// reuses the staking-flow setup; overrides the yield to require kyc + adds the status endpoint
+export const setup = async (worker: TestWorker) => {
+  const base = await stakingSetup(worker);
+  const kycUrl = "https://issuer.example/kyc";
+
+  // Strip the merged __fallback__ — it isn't part of the yield-api response.
+  const { __fallback__, ...apiYield } = base.yieldOp;
+  const yieldWithKyc = {
+    ...apiYield,
+    mechanics: {
+      ...apiYield.mechanics,
+      requirements: { kycRequired: true, kycUrl },
+    },
+  };
+
+  // Runtime handlers added later take precedence in msw.
+  worker.use(
+    http.get(
+      yieldApiRoute("/v1/yields/avalanche-avax-liquid-staking"),
+      async () => {
+        await delay();
+        return HttpResponse.json(yieldWithKyc);
+      }
+    ),
+    http.get(yieldApiRoute("/v1/yields/:yieldId/kyc/status"), async () => {
+      await delay();
+      return HttpResponse.json({ kycStatus: "not_started" });
+    })
+  );
+
+  return { ...base, kycUrl };
+};

From f3446700f0b0015ceb103f1e2469fb361f2db231 Mon Sep 17 00:00:00 2001
From: auralshin <anshulspartan141@gmail.com>
Date: Tue, 2 Jun 2026 18:54:42 +0530
Subject: [PATCH 2/3] fix: hygiene

---
 .../src/components/molecules/kyc-iframe-modal/index.tsx   | 2 +-
 packages/widget/src/domain/types/kyc.ts                   | 8 ++++----
 2 files changed, 5 insertions(+), 5 deletions(-)

diff --git a/packages/widget/src/components/molecules/kyc-iframe-modal/index.tsx b/packages/widget/src/components/molecules/kyc-iframe-modal/index.tsx
index 5595d8bd..0a1c0df3 100644
--- a/packages/widget/src/components/molecules/kyc-iframe-modal/index.tsx
+++ b/packages/widget/src/components/molecules/kyc-iframe-modal/index.tsx
@@ -7,7 +7,7 @@ import { XIcon } from "../../atoms/icons/x-icon";
 import { Text } from "../../atoms/typography/text";
 import { container, content, iframe, overlay } from "./styles.css";
 
-export type KycIframeModalProps = {
+type KycIframeModalProps = {
   open: boolean;
   onOpenChange: (open: boolean) => void;
   url: string;
diff --git a/packages/widget/src/domain/types/kyc.ts b/packages/widget/src/domain/types/kyc.ts
index f308842b..37fd48b2 100644
--- a/packages/widget/src/domain/types/kyc.ts
+++ b/packages/widget/src/domain/types/kyc.ts
@@ -14,18 +14,18 @@ export enum KycMode {
   OauthRedirect = "oauth_redirect",
 }
 
-export enum KycAccreditation {
+enum KycAccreditation {
   Retail = "retail",
   QualifiedPurchaser = "qualified_purchaser",
   Accredited = "accredited",
 }
 
-export enum KycSubjectType {
+enum KycSubjectType {
   Kyc = "KYC",
   Kyb = "KYB",
 }
 
-export interface YieldKycEligibility {
+interface YieldKycEligibility {
   countries?: string[];
   usPersonAllowed?: boolean;
   accreditation?: KycAccreditation;
@@ -51,7 +51,7 @@ type RequirementsWithKyc = {
   readonly kyc?: YieldKycMetadata;
 };
 
-export type YieldKycRequirement = {
+type YieldKycRequirement = {
   required: boolean;
   kyc?: YieldKycMetadata;
   legacyKycUrl?: string;

From 05862849aabca709c244ba286bfc6f5632c63c85 Mon Sep 17 00:00:00 2001
From: auralshin <anshulspartan141@gmail.com>
Date: Tue, 2 Jun 2026 19:06:19 +0530
Subject: [PATCH 3/3] feat(kyc): add translation for close button in modal and
 update KYC iframe accessibility

---
 .../src/components/molecules/kyc-iframe-modal/index.tsx   | 8 +++++++-
 packages/widget/src/translation/English/translations.json | 1 +
 packages/widget/src/translation/French/translations.json  | 1 +
 3 files changed, 9 insertions(+), 1 deletion(-)

diff --git a/packages/widget/src/components/molecules/kyc-iframe-modal/index.tsx b/packages/widget/src/components/molecules/kyc-iframe-modal/index.tsx
index 0a1c0df3..0fb6f598 100644
--- a/packages/widget/src/components/molecules/kyc-iframe-modal/index.tsx
+++ b/packages/widget/src/components/molecules/kyc-iframe-modal/index.tsx
@@ -1,5 +1,6 @@
 import { Content, Overlay, Portal, Root, Title } from "@radix-ui/react-dialog";
 import { useContext } from "react";
+import { useTranslation } from "react-i18next";
 import { SettingsContext } from "../../../providers/settings";
 import { id } from "../../../styles/theme/ids";
 import { Box } from "../../atoms/box";
@@ -21,6 +22,7 @@ export const KycIframeModal = ({
   title,
 }: KycIframeModalProps) => {
   const portalContainer = useContext(SettingsContext)?.portalContainer;
+  const { t } = useTranslation();
 
   return (
     <Root open={open} onOpenChange={onOpenChange}>
@@ -44,7 +46,11 @@ export const KycIframeModal = ({
                 <Text variant={{ weight: "bold", size: "large" }}>{title}</Text>
               </Title>
 
-              <Box as="button" onClick={() => onOpenChange(false)}>
+              <Box
+                as="button"
+                onClick={() => onOpenChange(false)}
+                aria-label={t("kyc.close")}
+              >
                 <XIcon />
               </Box>
             </Box>
diff --git a/packages/widget/src/translation/English/translations.json b/packages/widget/src/translation/English/translations.json
index c93dd18f..c81f55c4 100644
--- a/packages/widget/src/translation/English/translations.json
+++ b/packages/widget/src/translation/English/translations.json
@@ -1,6 +1,7 @@
 {
   "kyc": {
     "modal_title": "Identity verification",
+    "close": "Close",
     "not_started": {
       "title": "Identity verification required",
       "description": "This opportunity requires you to verify your identity before you can continue.",
diff --git a/packages/widget/src/translation/French/translations.json b/packages/widget/src/translation/French/translations.json
index 6af44cfc..f58e9f72 100644
--- a/packages/widget/src/translation/French/translations.json
+++ b/packages/widget/src/translation/French/translations.json
@@ -1,6 +1,7 @@
 {
   "kyc": {
     "modal_title": "Vérification d'identité",
+    "close": "Fermer",
     "not_started": {
       "title": "Vérification d'identité requise",
       "description": "Cette opportunité nécessite la vérification de votre identité avant de continuer.",