From 9413b3d6f7d1c7b0c04eaae1c85e844e946788fc Mon Sep 17 00:00:00 2001
From: Zainab Wahab <zainabwahab.eth@gmail.com>
Date: Sat, 26 Sep 2026 19:02:32 +0100
Subject: [PATCH] feat: add atomic swap proposal and acceptance UI

---
 src/components/common/AtomicSwapHistory.tsx   | 194 ++++++++
 .../common/AtomicSwapProposalForm.tsx         | 462 ++++++++++++++++++
 .../common/AtomicSwapProposalReview.tsx       | 287 +++++++++++
 src/hooks/useAtomicSwap.ts                    |  82 ++++
 src/lib/queryKeys.ts                          |   7 +
 src/pages/AtomicSwapCreatePage.tsx            | 198 ++++++++
 src/pages/AtomicSwapProposalPage.tsx          |  14 +
 src/pages/LandingPage.tsx                     |  13 +-
 src/pages/ProfilePage.tsx                     |  32 +-
 src/routes.tsx                                |  10 +
 src/services/atomicSwap.service.ts            | 319 ++++++++++++
 src/types/atomicSwap.ts                       |  75 +++
 12 files changed, 1690 insertions(+), 3 deletions(-)
 create mode 100644 src/components/common/AtomicSwapHistory.tsx
 create mode 100644 src/components/common/AtomicSwapProposalForm.tsx
 create mode 100644 src/components/common/AtomicSwapProposalReview.tsx
 create mode 100644 src/hooks/useAtomicSwap.ts
 create mode 100644 src/pages/AtomicSwapCreatePage.tsx
 create mode 100644 src/pages/AtomicSwapProposalPage.tsx
 create mode 100644 src/services/atomicSwap.service.ts
 create mode 100644 src/types/atomicSwap.ts

diff --git a/src/components/common/AtomicSwapHistory.tsx b/src/components/common/AtomicSwapHistory.tsx
new file mode 100644
index 00000000..0887f44b
--- /dev/null
+++ b/src/components/common/AtomicSwapHistory.tsx
@@ -0,0 +1,194 @@
+import React, { useMemo } from 'react';
+import { ArrowLeftRight, ClockIcon } from 'lucide-react';
+import { Button } from '@/components/ui/button';
+import EmptyState from '@/components/common/EmptyState';
+import { cn } from '@/lib/utils';
+import { formatRelativeTime } from '@/utils/time.utils';
+import { formatNumber } from '@/utils/numberFormat.utils';
+import type { SwapHistoryEntry } from '@/types/atomicSwap';
+import { useAtomicSwapHistory } from '@/hooks/useAtomicSwap';
+
+// ─── helpers ──────────────────────────────────────────────────────────────────
+
+function SwapTypePill() {
+  return (
+    <span className="inline-flex items-center gap-1 rounded-full bg-amber-400/10 px-2 py-0.5 text-[10px] font-semibold uppercase tracking-wide text-amber-400">
+      <ArrowLeftRight className="size-3" aria-hidden="true" />
+      Atomic Swap
+    </span>
+  );
+}
+
+// ─── skeleton loader ───────────────────────────────────────────────────────────
+
+function SkeletonRow() {
+  return (
+    <div className="flex items-center gap-4 rounded-xl border border-white/[0.06] bg-white/[0.02] p-4 animate-pulse" aria-hidden="true">
+      <div className="h-4 w-20 animate-pulse rounded bg-white/10" />
+      <div className="h-4 w-16 animate-pulse rounded bg-white/10" />
+      <div className="h-4 w-16 animate-pulse rounded bg-white/10" />
+      <div className="h-4 w-20 animate-pulse rounded bg-white/10" />
+      <div className="ml-auto h-4 w-24 animate-pulse rounded bg-white/10" />
+    </div>
+  );
+}
+
+// ─── single row ───────────────────────────────────────────────────────────────
+
+interface SwapRowProps {
+  swap: SwapHistoryEntry;
+}
+
+function SwapRow({ swap }: SwapRowProps) {
+  return (
+    <div
+      data-testid={`swap-row-${swap.id}`}
+      className={cn(
+        'flex flex-col gap-3 rounded-xl border border-white/10 bg-white/[0.02] p-4 pl-5 transition-colors hover:border-white/20 hover:bg-white/[0.04] sm:flex-row sm:items-center sm:justify-between',
+        'border-l-4 border-l-amber-400'
+      )}
+    >
+      {/* Keys exchanged */}
+      <div className="min-w-0 flex-1">
+        <div className="flex items-center gap-2">
+          <SwapTypePill />
+          <span className="truncate text-sm font-semibold text-white">
+            {swap.offeredKeyName} ↔ {swap.receivedKeyName}
+          </span>
+        </div>
+        <div className="mt-1 text-xs text-white/55">
+          Atomic swap
+        </div>
+      </div>
+
+      {/* Numeric columns */}
+      <div className="flex items-center gap-4 text-xs text-white/60 sm:gap-6">
+        <div className="flex flex-col items-end">
+          <span className="text-[10px] font-bold uppercase tracking-widest text-white/30">You gave</span>
+          <span className="font-mono text-white/80">{formatNumber(swap.offeredAmount)} {swap.offeredKeyName}</span>
+        </div>
+
+        <div className="flex flex-col items-end">
+          <span className="text-[10px] font-bold uppercase tracking-widest text-white/30">You received</span>
+          <span className="font-mono text-white/80">{formatNumber(swap.receivedAmount)} {swap.receivedKeyName}</span>
+        </div>
+
+        <div className="flex flex-col items-end">
+          <span className="text-[10px] font-bold uppercase tracking-widest text-white/30">When</span>
+          <span className="font-mono text-white/60" title={new Date(swap.timestamp).toLocaleString()}>
+            {formatRelativeTime(swap.timestamp)}
+          </span>
+        </div>
+
+        <div className="flex flex-col items-end ml-auto">
+          <span className="text-[10px] font-bold uppercase tracking-widest text-white/30">Status</span>
+          <span className={cn('font-mono font-semibold', swap.status === 'completed' ? 'text-emerald-400' : 'text-rose-400')}>
+            {swap.status}
+          </span>
+        </div>
+      </div>
+
+      {/* Expanded details */}
+      <details className="group mt-4 pt-4 border-t border-white/10 sm:hidden">
+        <summary className="flex items-center justify-between cursor-pointer list-none">
+          <span className="text-xs text-white/60">Details</span>
+          <span className="text-white/40">▼</span>
+        </summary>
+        <div className="mt-3 grid gap-2 text-xs text-white/70">
+          <div><span className="text-white/40">Proposer: </span><span className="font-mono">{swap.proposerAddress.slice(0, 8)}…{swap.proposerAddress.slice(-6)}</span></div>
+          <div><span className="text-white/40">Counterparty: </span><span className="font-mono">{swap.counterpartyAddress.slice(0, 8)}…{swap.counterpartyAddress.slice(-6)}</span></div>
+          <div><span className="text-white/40">Tx hash: </span><span className="font-mono">{swap.transactionHash}</span></div>
+        </div>
+      </details>
+    </div>
+  );
+}
+
+// ─── main component ────────────────────────────────────────────────────────────
+
+interface AtomicSwapHistoryProps {
+  walletAddress: string;
+}
+
+const AtomicSwapHistory: React.FC<AtomicSwapHistoryProps> = ({ walletAddress }) => {
+  const { data, fetchNextPage, hasNextPage, isFetchingNextPage, isLoading, isError } = useAtomicSwapHistory(walletAddress);
+
+  const swaps = useMemo(() => {
+    const seen = new Set<string>();
+    const result: SwapHistoryEntry[] = [];
+    for (const page of data?.pages ?? []) {
+      for (const swap of page.swaps) {
+        if (seen.has(swap.id)) continue;
+        seen.add(swap.id);
+        result.push(swap);
+      }
+    }
+    return result;
+  }, [data]);
+
+  if (isLoading) {
+    return (
+      <section className="space-y-2" aria-label="Loading atomic swap history" aria-busy="true">
+        {Array.from({ length: 5 }).map((_, i) => <SkeletonRow key={i} />)}
+      </section>
+    );
+  }
+
+  if (isError) {
+    return (
+      <EmptyState
+        title="Couldn't load swap history"
+        description="There was a problem fetching your atomic swaps. Please try again shortly."
+        data-testid="atomic-swap-history-error"
+      />
+    );
+  }
+
+  if (swaps.length === 0) {
+    return (
+      <EmptyState
+        title="No atomic swaps yet"
+        description="Your completed atomic swaps will appear here."
+        data-testid="atomic-swap-history-empty"
+      />
+    );
+  }
+
+  return (
+    <section aria-label="Atomic swap history">
+      {/* Column header row */}
+      <div className="mb-2 hidden items-center gap-4 px-5 text-[10px] font-bold uppercase tracking-widest text-white/30 sm:flex sm:justify-between">
+        <span className="flex-1">Exchange</span>
+        <div className="flex items-center gap-4 sm:gap-6">
+          <span className="w-20 text-right">You gave</span>
+          <span className="w-20 text-right">You received</span>
+          <span className="w-24 text-right">
+            <ClockIcon className="size-3 inline-block" aria-hidden="true" />
+            When
+          </span>
+          <span className="w-16 text-right">Status</span>
+        </div>
+      </div>
+
+      <div className="space-y-2" data-testid="atomic-swap-history-list">
+        {swaps.map(swap => <SwapRow key={swap.id} swap={swap} />)}
+      </div>
+
+      {hasNextPage && (
+        <div className="mt-6 flex justify-center">
+          <Button
+            variant="outline"
+            onClick={() => void fetchNextPage()}
+            disabled={isFetchingNextPage}
+            data-testid="atomic-swap-history-load-more"
+            className="rounded-xl border-white/15 bg-white/5 px-8 text-white/80 hover:bg-white/10 hover:text-white"
+          >
+            {isFetchingNextPage ? 'Loading…' : 'Load More'}
+          </Button>
+        </div>
+      )}
+    </section>
+  );
+};
+
+export default AtomicSwapHistory;
\ No newline at end of file
diff --git a/src/components/common/AtomicSwapProposalForm.tsx b/src/components/common/AtomicSwapProposalForm.tsx
new file mode 100644
index 00000000..28430286
--- /dev/null
+++ b/src/components/common/AtomicSwapProposalForm.tsx
@@ -0,0 +1,462 @@
+import { useEffect, useMemo, useState } from 'react';
+import { Button } from '@/components/ui/button';
+import { StableButtonContent } from '@/components/ui/stable-button-content';
+import {
+  Dialog,
+  DialogContent,
+  DialogDescription,
+  DialogFooter,
+  DialogHeader,
+  DialogTitle,
+} from '@/components/ui/dialog';
+import { cn } from '@/lib/utils';
+import { formatNumber } from '@/utils/numberFormat.utils';
+import { useWalletHoldings } from '@/hooks/useWallet';
+import { copyTextToClipboard } from '@/utils/clipboard.utils';
+import showToast from '@/utils/toast.util';
+import { useCreateAtomicSwapProposal } from '@/hooks/useAtomicSwap';
+import type { Course } from '@/services/course.service';
+
+interface AtomicSwapProposalFormProps {
+  open: boolean;
+  onOpenChange: (open: boolean) => void;
+  creators: Course[];
+  walletAddress: string;
+  isSubmitting?: boolean;
+}
+
+const MAX_EXPIRY_HOURS = 168; // 1 week
+
+export const AtomicSwapProposalForm: React.FC<AtomicSwapProposalFormProps> = ({
+  open,
+  onOpenChange,
+  creators,
+  walletAddress,
+  isSubmitting = false,
+}) => {
+  const { data: holdings = [] } = useWalletHoldings(walletAddress);
+  const createProposalMutation = useCreateAtomicSwapProposal(walletAddress);
+
+  const [offeredKeyId, setOfferedKeyId] = useState('');
+  const [offeredAmount, setOfferedAmount] = useState('1');
+  const [desiredKeyId, setDesiredKeyId] = useState('');
+  const [desiredAmount, setDesiredAmount] = useState('1');
+  const [expiryHours, setExpiryHours] = useState(24);
+  const [touched, setTouched] = useState<Record<string, boolean>>({});
+  const [generatedLink, setGeneratedLink] = useState('');
+  const [showLinkDialog, setShowLinkDialog] = useState(false);
+
+  const offeredKey = useMemo(() => creators.find(c => c.id === offeredKeyId), [creators, offeredKeyId]);
+  const desiredKey = useMemo(() => creators.find(c => c.id === desiredKeyId), [creators, desiredKeyId]);
+  const offeredHolding = useMemo(
+    () => holdings.find(h => h.creatorId === offeredKeyId)?.quantity ?? 0,
+    [holdings, offeredKeyId]
+  );
+
+  const parsedOfferedAmount = useMemo(() => Number(offeredAmount), [offeredAmount]);
+  const parsedDesiredAmount = useMemo(() => Number(desiredAmount), [desiredAmount]);
+
+  const validationErrors = useMemo((): Record<string, string> => {
+    const errors: Record<string, string> = {};
+
+    if (touched.offeredKey && !offeredKeyId) errors.offeredKey = 'Please select a key to offer';
+    if (touched.desiredKey && !desiredKeyId) errors.desiredKey = 'Please select a key you want';
+    if (touched.offeredAmount && (!offeredAmount.trim() || !Number.isFinite(parsedOfferedAmount))) {
+      errors.offeredAmount = 'Please enter a valid amount';
+    }
+    if (touched.desiredAmount && (!desiredAmount.trim() || !Number.isFinite(parsedDesiredAmount))) {
+      errors.desiredAmount = 'Please enter a valid amount';
+    }
+    if (touched.offeredAmount && parsedOfferedAmount <= 0) errors.offeredAmount = 'Amount must be greater than zero';
+    if (touched.desiredAmount && parsedDesiredAmount <= 0) errors.desiredAmount = 'Amount must be greater than zero';
+    if (touched.offeredAmount && parsedOfferedAmount > offeredHolding) {
+      errors.offeredAmount = `You only have ${formatNumber(offeredHolding)} ${offeredKey?.title ?? 'this key'}`;
+    }
+    if (touched.offeredKey && touched.desiredKey && offeredKeyId && desiredKeyId && offeredKeyId === desiredKeyId) {
+      errors.desiredKey = 'Cannot swap the same key with itself';
+    }
+    if (touched.expiryHours && (!expiryHours || expiryHours < 1 || expiryHours > MAX_EXPIRY_HOURS)) {
+      errors.expiryHours = `Expiry must be between 1 and ${MAX_EXPIRY_HOURS} hours`;
+    }
+
+    return errors;
+  }, [touched, offeredKeyId, desiredKeyId, offeredAmount, desiredAmount, parsedOfferedAmount, parsedDesiredAmount, offeredHolding, offeredKey?.title, expiryHours]);
+
+  const isFormValid = offeredKeyId && desiredKeyId && offeredAmount.trim() && desiredAmount.trim() &&
+    Number.isFinite(parsedOfferedAmount) && Number.isFinite(parsedDesiredAmount) &&
+    parsedOfferedAmount > 0 && parsedDesiredAmount > 0 &&
+    parsedOfferedAmount <= offeredHolding &&
+    offeredKeyId !== desiredKeyId &&
+    expiryHours >= 1 && expiryHours <= MAX_EXPIRY_HOURS;
+
+  const handleBlur = (field: string) => {
+    setTouched(prev => ({ ...prev, [field]: true }));
+  };
+
+  const handleSubmit = async () => {
+    setTouched({
+      offeredKey: true,
+      desiredKey: true,
+      offeredAmount: true,
+      desiredAmount: true,
+      expiryHours: true,
+    });
+
+    if (!isFormValid) return;
+
+    const proposal = await createProposalMutation.mutateAsync({
+      proposerAddress: walletAddress,
+      offeredKeyId,
+      offeredKeyName: offeredKey?.title ?? 'Unknown',
+      offeredAmount: parsedOfferedAmount,
+      desiredKeyId,
+      desiredKeyName: desiredKey?.title ?? 'Unknown',
+      desiredAmount: parsedDesiredAmount,
+      expiryHours,
+    });
+
+    if (proposal) {
+      const proposalUrl = `${window.location.origin}/swap/${proposal.id}`;
+      setGeneratedLink(proposalUrl);
+      setShowLinkDialog(true);
+      setOfferedKeyId('');
+      setOfferedAmount('1');
+      setDesiredKeyId('');
+      setDesiredAmount('1');
+      setExpiryHours(24);
+      setTouched({});
+    }
+  };
+
+  const handleCopyLink = async () => {
+    try {
+      await copyTextToClipboard(generatedLink);
+      showToast.success('Link copied');
+    } catch (error) {
+      if (error instanceof Error && error.message.includes('Clipboard API is unavailable')) {
+        showToast.error('Could not copy');
+      } else {
+        showToast.error('Copy failed');
+      }
+    }
+  };
+
+  const handleCloseLinkDialog = () => {
+    setShowLinkDialog(false);
+    setGeneratedLink('');
+    onOpenChange(false);
+  };
+
+  useEffect(() => {
+    if (!open) {
+      setOfferedKeyId('');
+      setOfferedAmount('1');
+      setDesiredKeyId('');
+      setDesiredAmount('1');
+      setExpiryHours(24);
+      setTouched({});
+      setGeneratedLink('');
+      setShowLinkDialog(false);
+    }
+  }, [open]);
+
+  const heldKeysWithQuantity = useMemo(() => {
+    return creators.filter(creator =>
+      holdings.some(h => h.creatorId === creator.id && (h.quantity ?? 0) > 0)
+    );
+  }, [creators, holdings]);
+
+  return (
+    <>
+      <Dialog open={open} onOpenChange={next => !isSubmitting && !createProposalMutation.isPending && onOpenChange(next)}>
+        <DialogContent className="max-w-lg" showCloseButton={!isSubmitting && !createProposalMutation.isPending}>
+          <DialogHeader>
+            <DialogTitle>Create Atomic Swap Proposal</DialogTitle>
+            <DialogDescription>
+              Offer your creator keys in exchange for another creator's keys. The swap executes atomically —
+              both sides transfer simultaneously or neither does.
+            </DialogDescription>
+          </DialogHeader>
+
+          <div className="space-y-6">
+            {/* Offered Side */}
+            <fieldset className="space-y-3 rounded-xl border border-white/10 bg-white/[0.03] p-4">
+              <legend className="text-sm font-semibold text-amber-300/90">You offer</legend>
+              <div className="space-y-3">
+                <div>
+                  <label htmlFor="offered-key" className="block text-xs font-medium text-white/70 mb-1.5">
+                    Key to offer
+                  </label>
+                  <select
+                    id="offered-key"
+                    value={offeredKeyId}
+                    onChange={e => setOfferedKeyId(e.target.value)}
+                    onBlur={() => handleBlur('offeredKey')}
+                    disabled={isSubmitting || createProposalMutation.isPending}
+                    className={cn(
+                      'w-full rounded-xl border bg-white/[0.04] px-3 py-2 text-white outline-none transition-colors',
+                      validationErrors.offeredKey ? 'border-red-500/60' : 'border-white/10 focus:border-amber-500/50 focus:ring-2 focus:ring-amber-500/15'
+                    )}
+                    aria-invalid={!!validationErrors.offeredKey}
+                    aria-describedby={validationErrors.offeredKey ? 'offered-key-error' : undefined}
+                  >
+                    <option value="">Select a key you own</option>
+                    {heldKeysWithQuantity.map(creator => {
+                      const holding = holdings.find(h => h.creatorId === creator.id);
+                      return (
+                        <option key={creator.id} value={creator.id}>
+                          {creator.title} ({formatNumber(holding?.quantity ?? 0)} held)
+                        </option>
+                      );
+                    })}
+                  </select>
+                  {validationErrors.offeredKey && (
+                    <p id="offered-key-error" className="mt-1 text-xs text-red-300" role="alert">
+                      {validationErrors.offeredKey}
+                    </p>
+                  )}
+                </div>
+
+                <div>
+                  <label htmlFor="offered-amount" className="block text-xs font-medium text-white/70 mb-1.5">
+                    Amount to offer
+                  </label>
+                  <input
+                    id="offered-amount"
+                    type="number"
+                    min="1"
+                    max={offeredHolding}
+                    step="1"
+                    inputMode="numeric"
+                    value={offeredAmount}
+                    onChange={e => setOfferedAmount(e.target.value)}
+                    onBlur={() => handleBlur('offeredAmount')}
+                    disabled={isSubmitting || createProposalMutation.isPending || !offeredKeyId}
+                    className={cn(
+                      'w-full rounded-xl border bg-white/[0.04] px-3 py-2 text-white outline-none transition-colors',
+                      validationErrors.offeredAmount ? 'border-red-500/60' : 'border-white/10 focus:border-amber-500/50 focus:ring-2 focus:ring-amber-500/15'
+                    )}
+                    aria-invalid={!!validationErrors.offeredAmount}
+                    aria-describedby={validationErrors.offeredAmount ? 'offered-amount-error' : undefined}
+                    placeholder={offeredKeyId ? 'Enter amount' : 'Select a key first'}
+                  />
+                  {validationErrors.offeredAmount && (
+                    <p id="offered-amount-error" className="mt-1 text-xs text-red-300" role="alert">
+                      {validationErrors.offeredAmount}
+                    </p>
+                  )}
+                  {offeredKeyId && (
+                    <p className="mt-1 text-xs text-white/50">
+                      Available: {formatNumber(offeredHolding)} {offeredKey?.title ?? 'keys'}
+                    </p>
+                  )}
+                </div>
+              </div>
+            </fieldset>
+
+            {/* Desired Side */}
+            <fieldset className="space-y-3 rounded-xl border border-white/10 bg-white/[0.03] p-4">
+              <legend className="text-sm font-semibold text-emerald-300/90">You want</legend>
+              <div className="space-y-3">
+                <div>
+                  <label htmlFor="desired-key" className="block text-xs font-medium text-white/70 mb-1.5">
+                    Key you want
+                  </label>
+                  <select
+                    id="desired-key"
+                    value={desiredKeyId}
+                    onChange={e => setDesiredKeyId(e.target.value)}
+                    onBlur={() => handleBlur('desiredKey')}
+                    disabled={isSubmitting || createProposalMutation.isPending}
+                    className={cn(
+                      'w-full rounded-xl border bg-white/[0.04] px-3 py-2 text-white outline-none transition-colors',
+                      validationErrors.desiredKey ? 'border-red-500/60' : 'border-white/10 focus:border-amber-500/50 focus:ring-2 focus:ring-amber-500/15'
+                    )}
+                    aria-invalid={!!validationErrors.desiredKey}
+                    aria-describedby={validationErrors.desiredKey ? 'desired-key-error' : undefined}
+                  >
+                    <option value="">Select a key you want</option>
+                    {creators
+                      .filter(c => c.id !== offeredKeyId)
+                      .map(creator => (
+                        <option key={creator.id} value={creator.id}>
+                          {creator.title} ({formatNumber(creator.creatorShareSupply ?? 0)} supply)
+                        </option>
+                      ))}
+                  </select>
+                  {validationErrors.desiredKey && (
+                    <p id="desired-key-error" className="mt-1 text-xs text-red-300" role="alert">
+                      {validationErrors.desiredKey}
+                    </p>
+                  )}
+                </div>
+
+                <div>
+                  <label htmlFor="desired-amount" className="block text-xs font-medium text-white/70 mb-1.5">
+                    Amount wanted
+                  </label>
+                  <input
+                    id="desired-amount"
+                    type="number"
+                    min="1"
+                    step="1"
+                    inputMode="numeric"
+                    value={desiredAmount}
+                    onChange={e => setDesiredAmount(e.target.value)}
+                    onBlur={() => handleBlur('desiredAmount')}
+                    disabled={isSubmitting || createProposalMutation.isPending || !desiredKeyId}
+                    className={cn(
+                      'w-full rounded-xl border bg-white/[0.04] px-3 py-2 text-white outline-none transition-colors',
+                      validationErrors.desiredAmount ? 'border-red-500/60' : 'border-white/10 focus:border-amber-500/50 focus:ring-2 focus:ring-amber-500/15'
+                    )}
+                    aria-invalid={!!validationErrors.desiredAmount}
+                    aria-describedby={validationErrors.desiredAmount ? 'desired-amount-error' : undefined}
+                    placeholder={desiredKeyId ? 'Enter amount' : 'Select a key first'}
+                  />
+                  {validationErrors.desiredAmount && (
+                    <p id="desired-amount-error" className="mt-1 text-xs text-red-300" role="alert">
+                      {validationErrors.desiredAmount}
+                    </p>
+                  )}
+                </div>
+              </div>
+            </fieldset>
+
+            {/* Expiry */}
+            <div className="space-y-2">
+              <label htmlFor="expiry-hours" className="block text-xs font-medium text-white/70 mb-1.5">
+                Proposal expires in (hours)
+              </label>
+              <input
+                id="expiry-hours"
+                type="number"
+                min="1"
+                max={MAX_EXPIRY_HOURS}
+                step="1"
+                inputMode="numeric"
+                value={expiryHours}
+                onChange={e => setExpiryHours(Number(e.target.value) || 1)}
+                onBlur={() => handleBlur('expiryHours')}
+                disabled={isSubmitting || createProposalMutation.isPending}
+                className={cn(
+                  'w-full rounded-xl border bg-white/[0.04] px-3 py-2 text-white outline-none transition-colors',
+                  validationErrors.expiryHours ? 'border-red-500/60' : 'border-white/10 focus:border-amber-500/50 focus:ring-2 focus:ring-amber-500/15'
+                )}
+                aria-invalid={!!validationErrors.expiryHours}
+                aria-describedby={validationErrors.expiryHours ? 'expiry-hours-error' : undefined}
+              />
+              {validationErrors.expiryHours && (
+                <p id="expiry-hours-error" className="mt-1 text-xs text-red-300" role="alert">
+                  {validationErrors.expiryHours}
+                </p>
+              )}
+              <p className="text-xs text-white/50">
+                After expiry, the proposal can no longer be accepted. Max {MAX_EXPIRY_HOURS} hours (7 days).
+              </p>
+            </div>
+
+            {/* Summary Preview */}
+            {offeredKey && desiredKey && offeredAmount && desiredAmount && (
+              <div className="rounded-xl border border-white/10 bg-white/[0.02] p-4">
+                <p className="text-xs font-semibold uppercase tracking-wide text-white/50 mb-3">Proposal summary</p>
+                <div className="flex items-center justify-between gap-4 text-sm">
+                  <div className="flex-1 text-center p-3 rounded-lg bg-amber-400/10 border border-amber-400/20">
+                    <p className="font-semibold text-amber-300">{offeredKey.title}</p>
+                    <p className="font-mono text-white/90">{formatNumber(parsedOfferedAmount)} keys</p>
+                  </div>
+                  <span className="text-white/40 shrink-0" aria-hidden="true">↔</span>
+                  <div className="flex-1 text-center p-3 rounded-lg bg-emerald-500/10 border border-emerald-500/20">
+                    <p className="font-semibold text-emerald-400">{desiredKey.title}</p>
+                    <p className="font-mono text-white/90">{formatNumber(parsedDesiredAmount)} keys</p>
+                  </div>
+                </div>
+                <p className="mt-2 text-xs text-white/50 text-center">
+                  Expires in {expiryHours} hour{expiryHours !== 1 ? 's' : ''}
+                </p>
+              </div>
+            )}
+          </div>
+
+          <DialogFooter className="sm:justify-between">
+            <Button
+              type="button"
+              variant="ghost"
+              onClick={() => onOpenChange(false)}
+              disabled={isSubmitting || createProposalMutation.isPending}
+            >
+              Cancel
+            </Button>
+            <Button
+              type="button"
+              onClick={handleSubmit}
+              disabled={!isFormValid || isSubmitting || createProposalMutation.isPending}
+              aria-busy={createProposalMutation.isPending || undefined}
+            >
+              <StableButtonContent
+                isLoading={createProposalMutation.isPending}
+                loadingLabel="Creating…"
+              >
+                Create Proposal
+              </StableButtonContent>
+            </Button>
+          </DialogFooter>
+        </DialogContent>
+      </Dialog>
+
+      {/* Generated Link Dialog */}
+      <Dialog open={showLinkDialog} onOpenChange={setShowLinkDialog}>
+        <DialogContent className="max-w-md" showCloseButton={false}>
+          <DialogHeader>
+            <DialogTitle>Proposal Created</DialogTitle>
+            <DialogDescription>
+              Share this link with your counterparty. They can review and accept the swap.
+            </DialogDescription>
+          </DialogHeader>
+          <div className="space-y-4">
+            <div className="rounded-xl border border-white/10 bg-white/[0.03] p-4">
+              <label className="block text-xs font-medium text-white/70 mb-2">Shareable link</label>
+              <div className="flex gap-2">
+                <input
+                  type="text"
+                  readOnly
+                  value={generatedLink}
+                  className="flex-1 rounded-xl border border-white/10 bg-white/[0.04] px-3 py-2 text-white outline-none font-mono text-sm truncate"
+                  aria-label="Proposal share link"
+                />
+                <Button
+                  type="button"
+                  variant="outline"
+                  onClick={handleCopyLink}
+                  className="shrink-0 rounded-xl"
+                  aria-label="Copy link to clipboard"
+                >
+                  Copy
+                </Button>
+              </div>
+            </div>
+            <p className="text-xs text-white/50 text-center">
+              This proposal expires in {expiryHours} hour{expiryHours !== 1 ? 's' : ''}.
+            </p>
+          </div>
+          <DialogFooter className="sm:justify-between">
+            <Button
+              type="button"
+              variant="ghost"
+              onClick={() => {
+                navigator.clipboard.writeText(generatedLink).catch(() => {});
+                handleCopyLink();
+              }}
+            >
+              Copy Again
+            </Button>
+            <Button type="button" onClick={handleCloseLinkDialog}>
+              Done
+            </Button>
+          </DialogFooter>
+        </DialogContent>
+      </Dialog>
+    </>
+  );
+};
+
+export default AtomicSwapProposalForm;
\ No newline at end of file
diff --git a/src/components/common/AtomicSwapProposalReview.tsx b/src/components/common/AtomicSwapProposalReview.tsx
new file mode 100644
index 00000000..55b7d62d
--- /dev/null
+++ b/src/components/common/AtomicSwapProposalReview.tsx
@@ -0,0 +1,287 @@
+import { useState } from 'react';
+import { Button } from '@/components/ui/button';
+import { StableButtonContent } from '@/components/ui/stable-button-content';
+import { AlertCircle, CheckCircle, Clock, XCircle } from 'lucide-react';
+import { useParams, useNavigate } from 'react-router';
+import { useAccount } from 'wagmi';
+import { useAtomicSwapProposal, useAcceptAtomicSwapProposal } from '@/hooks/useAtomicSwap';
+import { copyTextToClipboard } from '@/utils/clipboard.utils';
+import showToast from '@/utils/toast.util';
+import { formatRelativeTime } from '@/utils/time.utils';
+import { formatNumber } from '@/utils/numberFormat.utils';
+import { isProposalExpired, canAcceptProposal } from '@/types/atomicSwap';
+import { cn } from '@/lib/utils';
+
+export const AtomicSwapProposalReview: React.FC = () => {
+  const { proposalId } = useParams<{ proposalId: string }>();
+  const { address: connectedAddress } = useAccount();
+  const navigate = useNavigate();
+  const [copied, setCopied] = useState(false);
+
+  const { data: proposal, isLoading, isError } = useAtomicSwapProposal(proposalId ?? '');
+  const acceptMutation = useAcceptAtomicSwapProposal(connectedAddress ?? '');
+
+  const handleAccept = async () => {
+    if (!proposal || !connectedAddress) return;
+    if (!canAcceptProposal(proposal, connectedAddress)) {
+      showToast.error('Cannot accept');
+      return;
+    }
+    await acceptMutation.mutateAsync({ proposalId: proposal.id, counterpartyAddress: connectedAddress });
+  };
+
+  const handleCopyLink = async () => {
+    if (!proposal) return;
+    try {
+      await copyTextToClipboard(window.location.href);
+      setCopied(true);
+      showToast.success('Link copied');
+      setTimeout(() => setCopied(false), 2000);
+    } catch (error) {
+      if (error instanceof Error && error.message.includes('Clipboard API is unavailable')) {
+        showToast.error('Could not copy');
+      } else {
+        showToast.error('Copy failed');
+      }
+    }
+  };
+
+  const isProposer = connectedAddress && proposal?.proposerAddress === connectedAddress;
+  const isCounterparty = connectedAddress && proposal?.counterpartyAddress === connectedAddress;
+  const isExpired = proposal ? isProposalExpired(proposal) : false;
+  const isExecuted = proposal?.status === 'executed';
+  const isAccepted = proposal?.status === 'accepted';
+  const isPending = proposal?.status === 'pending';
+  const canAct = isPending && !isExpired && !isProposer && connectedAddress && canAcceptProposal(proposal, connectedAddress);
+
+  if (isLoading) {
+    return (
+      <div className="flex flex-col items-center justify-center min-h-[400px] gap-4">
+        <svg className="size-8 animate-spin text-amber-400" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2">
+          <circle className="opacity-25" cx="12" cy="12" r="10" />
+          <path className="opacity-75" d="M12 2a10 10 0 0 1 10 10" strokeLinecap="round" />
+        </svg>
+        <p className="text-white/60">Loading proposal…</p>
+      </div>
+    );
+  }
+
+  if (isError || !proposal) {
+    return (
+      <div className="flex flex-col items-center justify-center min-h-[400px] gap-4 text-center">
+        <AlertCircle className="size-12 text-red-400" aria-hidden="true" />
+        <h2 className="text-xl font-bold text-white">Proposal not found</h2>
+        <p className="text-white/60 max-w-md">
+          This proposal doesn't exist or has been removed. It may have expired or been cancelled.
+        </p>
+        <Button variant="outline" onClick={() => navigate('/')}>Back to marketplace</Button>
+      </div>
+    );
+  }
+
+  const statusConfig = {
+    pending: { icon: Clock, color: 'text-amber-400', bg: 'bg-amber-400/10 border-amber-400/20', label: 'Pending' },
+    accepted: { icon: CheckCircle, color: 'text-emerald-400', bg: 'bg-emerald-500/10 border-emerald-500/20', label: 'Accepted' },
+    executed: { icon: CheckCircle, color: 'text-emerald-400', bg: 'bg-emerald-500/10 border-emerald-500/20', label: 'Executed' },
+    expired: { icon: Clock, color: 'text-rose-400', bg: 'bg-rose-500/10 border-rose-500/20', label: 'Expired' },
+    cancelled: { icon: XCircle, color: 'text-rose-400', bg: 'bg-rose-500/10 border-rose-500/20', label: 'Cancelled' },
+  } as const;
+
+  const status = statusConfig[proposal.status];
+
+  return (
+    <section className="space-y-6" aria-labelledby="proposal-title">
+      <div className="flex flex-col gap-4 sm:flex-row sm:items-center sm:justify-between">
+        <div>
+          <h1 id="proposal-title" className="text-2xl font-bold text-white">Atomic Swap Proposal</h1>
+          <p className="text-white/60">Review the exchange details below</p>
+        </div>
+        <div className="flex items-center gap-2">
+          <span className={cn('inline-flex items-center gap-1.5 rounded-full px-3 py-1 text-sm font-semibold', status.bg, status.color)}>
+            <status.icon className="size-4" aria-hidden="true" />
+            {status.label}
+          </span>
+          <Button variant="outline" size="sm" onClick={handleCopyLink} className="rounded-xl">
+            {copied ? 'Copied!' : 'Copy link'}
+          </Button>
+        </div>
+      </div>
+
+      {/* Exchange Details */}
+      <div className="rounded-2xl border border-white/10 bg-white/[0.02] p-6">
+        <div className="grid gap-6 md:grid-cols-2">
+          {/* You Receive */}
+          <div className={cn('relative rounded-xl p-5 border-2', 'border-emerald-500/30 bg-emerald-500/5')}>
+            <div className="absolute -top-3 left-4 px-2 bg-emerald-500/5 text-emerald-400 text-xs font-bold uppercase tracking-wide">
+              You receive
+            </div>
+            <div className="space-y-3">
+              <div className="flex items-center gap-3">
+                <div className="size-12 shrink-0 rounded-xl bg-emerald-500/10 flex items-center justify-center">
+                  <CheckCircle className="size-6 text-emerald-400" aria-hidden="true" />
+                </div>
+                <div>
+                  <p className="font-semibold text-white">{proposal.desiredKeyName}</p>
+                  <p className="text-sm text-white/60">Desired key</p>
+                </div>
+              </div>
+              <div className="pt-2 border-t border-emerald-500/20">
+                <p className="text-xs text-white/50">Amount</p>
+                <p className="font-mono text-2xl font-bold text-emerald-300 tabular-nums">{formatNumber(proposal.desiredAmount)} keys</p>
+              </div>
+            </div>
+          </div>
+
+          {/* You Give */}
+          <div className={cn('relative rounded-xl p-5 border-2', 'border-amber-400/30 bg-amber-400/5')}>
+            <div className="absolute -top-3 left-4 px-2 bg-amber-400/5 text-amber-400 text-xs font-bold uppercase tracking-wide">
+              You give
+            </div>
+            <div className="space-y-3">
+              <div className="flex items-center gap-3">
+                <div className="size-12 shrink-0 rounded-xl bg-amber-400/10 flex items-center justify-center">
+                  <AlertCircle className="size-6 text-amber-400" aria-hidden="true" />
+                </div>
+                <div>
+                  <p className="font-semibold text-white">{proposal.offeredKeyName}</p>
+                  <p className="text-sm text-white/60">Offered by proposer</p>
+                </div>
+              </div>
+              <div className="pt-2 border-t border-amber-400/20">
+                <p className="text-xs text-white/50">Amount</p>
+                <p className="font-mono text-2xl font-bold text-amber-300 tabular-nums">{formatNumber(proposal.offeredAmount)} keys</p>
+              </div>
+            </div>
+          </div>
+        </div>
+      </div>
+
+      {/* Proposer Info */}
+      <div className="rounded-xl border border-white/10 bg-white/[0.03] p-4">
+        <p className="text-xs font-semibold uppercase tracking-wide text-white/50 mb-3">Proposal details</p>
+        <dl className="grid gap-3 sm:grid-cols-2">
+          <div>
+            <dt className="text-xs text-white/50">Proposer</dt>
+            <dd className="font-mono text-sm text-white/90 truncate">{proposal.proposerAddress.slice(0, 8)}…{proposal.proposerAddress.slice(-6)}</dd>
+          </div>
+          <div>
+            <dt className="text-xs text-white/50">Created</dt>
+            <dd className="font-mono text-sm text-white/90">{formatRelativeTime(proposal.createdAt)}</dd>
+          </div>
+          <div>
+            <dt className="text-xs text-white/50">Expires</dt>
+            <dd className="font-mono text-sm text-white/90">{formatRelativeTime(proposal.expiresAt)}</dd>
+          </div>
+          <div>
+            <dt className="text-xs text-white/50">Proposal ID</dt>
+            <dd className="font-mono text-sm text-white/70 truncate">{proposal.id}</dd>
+          </div>
+          {proposal.executedAt && (
+            <div className="sm:col-span-2">
+              <dt className="text-xs text-white/50">Executed</dt>
+              <dd className="font-mono text-sm text-white/90">{formatRelativeTime(proposal.executedAt)}</dd>
+            </div>
+          )}
+          {proposal.transactionHash && (
+            <div className="sm:col-span-2">
+              <dt className="text-xs text-white/50">Transaction</dt>
+              <dd className="font-mono text-sm text-white/70 truncate">{proposal.transactionHash}</dd>
+            </div>
+          )}
+        </dl>
+      </div>
+
+      {/* Action / Status */}
+      <div className="rounded-xl border border-white/10 bg-white/[0.03] p-4">
+        {isExpired && (
+          <div className="flex items-center gap-3 p-4 rounded-lg bg-rose-500/10 border border-rose-500/20">
+            <Clock className="size-6 text-rose-400 shrink-0" aria-hidden="true" />
+            <div>
+              <p className="font-semibold text-rose-300">This proposal has expired</p>
+              <p className="text-sm text-white/60">
+                It expired {formatRelativeTime(proposal.expiresAt)} and can no longer be accepted.
+              </p>
+            </div>
+          </div>
+        )}
+
+        {isExecuted && (
+          <div className="flex items-center gap-3 p-4 rounded-lg bg-emerald-500/10 border border-emerald-500/20">
+            <CheckCircle className="size-6 text-emerald-400 shrink-0" aria-hidden="true" />
+            <div>
+              <p className="font-semibold text-emerald-300">Swap executed</p>
+              <p className="text-sm text-white/60">
+                This atomic swap was completed {formatRelativeTime(proposal.executedAt!)}.
+                {proposal.transactionHash && (
+                  <span className="ml-2 font-mono text-xs text-white/50">Tx: {proposal.transactionHash.slice(0, 10)}…</span>
+                )}
+              </p>
+            </div>
+          </div>
+        )}
+
+        {isAccepted && !isExecuted && (
+          <div className="flex items-center gap-3 p-4 rounded-lg bg-amber-400/10 border border-amber-400/20">
+            <Clock className="size-6 text-amber-400 shrink-0" aria-hidden="true" />
+            <div>
+              <p className="font-semibold text-amber-300">Proposal accepted</p>
+              <p className="text-sm text-white/60">Waiting for on-chain confirmation…</p>
+            </div>
+          </div>
+        )}
+
+        {canAct && (
+          <div className="space-y-3">
+            <p className="text-sm text-white/70">
+              You're connected as <span className="font-mono">{connectedAddress!.slice(0, 8)}…{connectedAddress!.slice(-6)}</span>.
+              Accept this proposal to execute the atomic swap.
+            </p>
+            <Button
+              onClick={handleAccept}
+              disabled={acceptMutation.isPending}
+              className="w-full rounded-xl"
+              size="lg"
+            >
+              <StableButtonContent
+                isLoading={acceptMutation.isPending}
+                loadingLabel="Submitting swap…"
+              >
+                Accept & Execute Swap
+              </StableButtonContent>
+            </Button>
+            <p className="text-xs text-white/50 text-center">
+              This will submit an atomic transaction — both transfers succeed or neither does.
+            </p>
+          </div>
+        )}
+
+        {isProposer && isPending && !isExpired && (
+          <div className="text-center text-white/60">
+            <p>You created this proposal. Share the link above with your counterparty.</p>
+            <p className="text-xs mt-1">Expires {formatRelativeTime(proposal.expiresAt)}</p>
+          </div>
+        )}
+
+        {isProposer && (isExpired || isExecuted) && (
+          <Button variant="outline" onClick={() => navigate('/')} className="w-full rounded-xl">
+            Back to marketplace
+          </Button>
+        )}
+
+        {isCounterparty && isExecuted && (
+          <Button variant="outline" onClick={() => navigate('/')} className="w-full rounded-xl">
+            Back to marketplace
+          </Button>
+        )}
+
+        {!connectedAddress && isPending && !isExpired && !isProposer && (
+          <div className="text-center text-white/60">
+            <p>Connect your wallet to accept this proposal.</p>
+          </div>
+        )}
+      </div>
+    </section>
+  );
+};
+
+export default AtomicSwapProposalReview;
\ No newline at end of file
diff --git a/src/hooks/useAtomicSwap.ts b/src/hooks/useAtomicSwap.ts
new file mode 100644
index 00000000..6555229c
--- /dev/null
+++ b/src/hooks/useAtomicSwap.ts
@@ -0,0 +1,82 @@
+import { useInfiniteQuery, useMutation, useQuery, useQueryClient } from '@tanstack/react-query';
+import { queryKeys } from '@/lib/queryKeys';
+import showToast from '@/utils/toast.util';
+import type { AtomicSwapProposal } from '@/types/atomicSwap';
+import {
+  createAtomicSwapProposal,
+  fetchAtomicSwapProposal,
+  acceptAtomicSwapProposal,
+  fetchUserAtomicSwapProposals,
+  fetchAtomicSwapHistory,
+} from '@/services/atomicSwap.service';
+
+export function useCreateAtomicSwapProposal(address: string) {
+  const queryClient = useQueryClient();
+
+  return useMutation({
+    mutationKey: ['atomic-swap', 'create', address],
+    mutationFn: async (params: Parameters<typeof createAtomicSwapProposal>[0]) => {
+      return createAtomicSwapProposal(params);
+    },
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: queryKeys.wallet.holdings(address) });
+      queryClient.invalidateQueries({ queryKey: ['atomic-swap', 'proposals', address] });
+      showToast.success('Proposal created');
+    },
+    onError: (error) => {
+      showToast.error(error instanceof Error ? error.message : 'Failed to create proposal');
+    },
+  });
+}
+
+export function useAtomicSwapProposal(proposalId: string, enabled = true) {
+  return useQuery<AtomicSwapProposal | null>({
+    queryKey: ['atomic-swap', 'proposal', proposalId],
+    queryFn: () => fetchAtomicSwapProposal({ proposalId }),
+    enabled: enabled && !!proposalId,
+    staleTime: 15_000,
+    refetchInterval: 30_000,
+  });
+}
+
+export function useAcceptAtomicSwapProposal(address: string) {
+  const queryClient = useQueryClient();
+
+  return useMutation({
+    mutationKey: ['atomic-swap', 'accept', address],
+    mutationFn: async (params: Parameters<typeof acceptAtomicSwapProposal>[0]) => {
+      return acceptAtomicSwapProposal(params);
+    },
+    onSuccess: (data, variables) => {
+      queryClient.setQueryData(['atomic-swap', 'proposal', variables.proposalId], data.proposal);
+      queryClient.invalidateQueries({ queryKey: ['atomic-swap', 'proposals', address] });
+      queryClient.invalidateQueries({ queryKey: ['atomic-swap', 'history', address] });
+      queryClient.invalidateQueries({ queryKey: queryKeys.wallet.holdings(address) });
+      queryClient.invalidateQueries({ queryKey: queryKeys.creators.all });
+      showToast.transactionSuccess('Swap completed', 'Atomic swap executed successfully');
+    },
+    onError: (error) => {
+      showToast.error(error instanceof Error ? error.message : 'Failed to accept proposal');
+    },
+  });
+}
+
+export function useUserAtomicSwapProposals(address: string, status?: AtomicSwapProposal['status']) {
+  return useQuery<AtomicSwapProposal[]>({
+    queryKey: ['atomic-swap', 'proposals', address, status ?? 'all'],
+    queryFn: () => fetchUserAtomicSwapProposals({ address, status }),
+    enabled: !!address,
+    staleTime: 30_000,
+  });
+}
+
+export function useAtomicSwapHistory(address: string) {
+  return useInfiniteQuery({
+    queryKey: ['atomic-swap', 'history', address],
+    queryFn: ({ pageParam }) => fetchAtomicSwapHistory({ address, cursor: pageParam as string | null | undefined }),
+    initialPageParam: null as string | null,
+    getNextPageParam: (lastPage) => lastPage.nextCursor ?? undefined,
+    enabled: !!address,
+    staleTime: 30_000,
+  });
+}
\ No newline at end of file
diff --git a/src/lib/queryKeys.ts b/src/lib/queryKeys.ts
index fa3def57..9eae2df5 100644
--- a/src/lib/queryKeys.ts
+++ b/src/lib/queryKeys.ts
@@ -43,4 +43,11 @@ export const queryKeys = {
 	admin: {
 		oracleCallers: () => ['admin', 'oracle', 'callers'] as const,
 	},
+	atomicSwap: {
+		all: () => ['atomic-swap'] as const,
+		proposal: (proposalId: string) => ['atomic-swap', 'proposal', proposalId] as const,
+		proposals: (address: string, status?: string) =>
+			['atomic-swap', 'proposals', address, status ?? 'all'] as const,
+		history: (address: string) => ['atomic-swap', 'history', address] as const,
+	},
 } as const;
diff --git a/src/pages/AtomicSwapCreatePage.tsx b/src/pages/AtomicSwapCreatePage.tsx
new file mode 100644
index 00000000..cc80aa0a
--- /dev/null
+++ b/src/pages/AtomicSwapCreatePage.tsx
@@ -0,0 +1,198 @@
+import { useCallback, useEffect, useMemo, useState } from 'react';
+import { useAccount } from 'wagmi';
+import { courseService, type Course } from '@/services/course.service';
+import { useWalletHoldings } from '@/hooks/useWallet';
+import { AtomicSwapProposalForm } from '@/components/common/AtomicSwapProposalForm';
+import { Button } from '@/components/ui/button';
+import { ArrowLeft } from 'lucide-react';
+import showToast from '@/utils/toast.util';
+import SectionDivider from '@/components/common/SectionDivider';
+import MarketplaceSection from '@/components/common/MarketplaceSection';
+import SectionHeading from '@/components/common/SectionHeading';
+import { calculatePortfolioValue, sortHoldingsByTotalValue } from '@/utils/portfolioValue.utils';
+import { formatPortfolioValueDisplay, getPortfolioValueHelperText } from '@/utils/portfolioValue.utils';
+import PortfolioHoldingRow from '@/components/common/PortfolioHoldingRow';
+import HoldingsEmptyState from '@/components/common/HoldingsEmptyState';
+import CreatorSkeleton from '@/components/common/CreatorSkeleton';
+import { useNetworkMismatch } from '@/hooks/useNetworkMismatch';
+
+const DEMO_WALLET_ADDRESS = 'demo-wallet-address';
+
+export default function AtomicSwapCreatePage() {
+  const { address: connectedAddress } = useAccount();
+  const activeWalletAddress = connectedAddress || DEMO_WALLET_ADDRESS;
+  const { isMismatch: isNetworkMismatch } = useNetworkMismatch();
+
+  const [creators, setCreators] = useState<Course[]>([]);
+  const [isLoading, setIsLoading] = useState(true);
+  const [formOpen, setFormOpen] = useState(false);
+
+  const { data: cachedHoldings = [] } = useWalletHoldings(activeWalletAddress);
+
+  useEffect(() => {
+    const fetchCreators = async () => {
+      setIsLoading(true);
+      try {
+        const data = await courseService.getCourses();
+        if (data && data.length > 0) {
+          setCreators(data);
+        }
+      } catch {
+        showToast.error('Unable to load creators. Check your connection and try again.');
+      } finally {
+        setIsLoading(false);
+      }
+    };
+    fetchCreators();
+  }, []);
+
+  const heldKeyPositions = useMemo(
+    () =>
+      sortHoldingsByTotalValue(
+        creators.map(creator => {
+          const cached = cachedHoldings.find(h => h.creatorId === creator.id);
+          return {
+            creatorId: creator.id,
+            quantity: cached?.quantity ?? 0,
+            priceStroops: creator.priceStroops,
+            price: creator.price,
+            pending: cached?.pending ?? false,
+            unclaimedDividend: cached?.unclaimedDividend ?? 0,
+          };
+        })
+      ),
+    [creators, cachedHoldings]
+  );
+
+  const portfolioValue = useMemo(() => calculatePortfolioValue(heldKeyPositions), [heldKeyPositions]);
+  const portfolioValueDisplay = formatPortfolioValueDisplay(portfolioValue);
+  const portfolioValueHelperText = getPortfolioValueHelperText(portfolioValue);
+
+  const hasHoldings = heldKeyPositions.some(p => p.quantity && p.quantity > 0);
+
+  const handleOpenForm = useCallback(() => {
+    if (!hasHoldings) {
+      showToast.error('No holdings');
+      return;
+    }
+    setFormOpen(true);
+  }, [hasHoldings]);
+
+  return (
+    <div className="relative min-h-screen overflow-x-hidden bg-[linear-gradient(160deg,#08111f_0%,#10213b_45%,#f0b14d_160%)] px-6 pt-12 pb-28 md:px-12 md:pb-12">
+      <div className="absolute left-[-4rem] top-[10%] size-72 rounded-full bg-amber-300/20 blur-[100px]" />
+      <div className="absolute bottom-[8%] right-[-3rem] size-72 rounded-full bg-emerald-300/15 blur-[100px]" />
+      <div className="absolute inset-0 bg-[radial-gradient(circle_at_top,rgba(255,186,73,0.1),transparent_40%),radial-gradient(circle_at_bottom_left,rgba(74,222,128,0.08),transparent_35%)]" />
+      <div className="relative z-10 mx-auto max-w-7xl">
+        <MarketplaceSection as="header" spacing="major" className="text-center">
+          <div className="flex items-center justify-between mb-6">
+            <Button variant="ghost" size="sm" onClick={() => window.history.back()} className="rounded-xl">
+              <ArrowLeft className="size-4 mr-1" />
+              Back
+            </Button>
+            <div />
+          </div>
+          <p className="mb-3 text-sm font-bold uppercase tracking-[0.25em] text-amber-400/80">Direct Key Exchange</p>
+          <h1 className="mb-4 font-grotesque text-[clamp(2rem,6vw,3.5rem)] font-extrabold leading-[1.1] tracking-tight text-white">
+            Atomic Swap Proposals
+          </h1>
+          <p className="max-w-2xl mx-auto text-white/60">
+            Create trustless, atomic key exchange proposals. Both sides of the swap execute simultaneously —
+            or neither does. Share a link with your counterparty to complete the exchange.
+          </p>
+        </MarketplaceSection>
+
+        <main>
+          <SectionDivider title="Your holdings" spacing="relaxed" />
+          <MarketplaceSection spacing="default" className="marketplace-card-surface rounded-[2rem] border p-6 md:p-8">
+            <div className="grid gap-6 md:grid-cols-[1fr_auto] md:items-center">
+              <div>
+                <p className="mb-2 text-xs font-bold uppercase tracking-[0.24em] text-amber-300/80">Portfolio value</p>
+                <div className="flex items-center gap-2 font-grotesque text-2xl font-black text-white md:text-3xl">
+                  {portfolioValueDisplay}
+                </div>
+                <p className="mt-2 text-xs leading-relaxed text-white/55">{portfolioValueHelperText}</p>
+              </div>
+            </div>
+
+            {isLoading ? (
+              <CreatorSkeleton className="mt-6" />
+            ) : !hasHoldings ? (
+              <HoldingsEmptyState className="mt-6" />
+            ) : (
+              <div className="mt-6 grid gap-3 sm:grid-cols-1 md:grid-cols-2 lg:grid-cols-3">
+                {heldKeyPositions
+                  .filter(position => position.quantity && position.quantity > 0)
+                  .map(position => {
+                    const creator = creators.find(item => item.id === position.creatorId);
+                    return (
+                      <PortfolioHoldingRow
+                        key={position.creatorId}
+                        position={position}
+                        creator={creator}
+                        isNetworkMismatch={isNetworkMismatch}
+                      />
+                    );
+                  })}
+              </div>
+            )}
+          </MarketplaceSection>
+
+          <SectionDivider title="Create proposal" spacing="relaxed" />
+          <MarketplaceSection spacing="default" className="marketplace-card-surface rounded-[2rem] border p-6 md:p-8">
+            <SectionHeading
+              title="New atomic swap proposal"
+              supportingText="Select a key you own to offer and a key you want in return. Set the amounts and expiry, then share the generated link with your counterparty."
+              className="mb-6"
+            />
+
+            {!hasHoldings ? (
+              <div className="text-center py-12">
+                <div className="mx-auto mb-4 size-16 rounded-full bg-amber-400/10 flex items-center justify-center">
+                  <svg className="size-8 text-amber-400" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="1.5">
+                    <path d="M12 22c5.523 0 10-4.477 10-10S17.523 2 12 2 2 6.477 2 12s4.477 10 10 10z" />
+                    <path d="M12 6v6l4 2" />
+                  </svg>
+                </div>
+                <h3 className="text-lg font-semibold text-white mb-2">No keys to swap</h3>
+                <p className="text-white/60 max-w-xs mx-auto">You need to own at least one creator key before you can create an atomic swap proposal.</p>
+              </div>
+            ) : (
+              <div className="space-y-4">
+                <AtomicSwapProposalForm
+                  open={formOpen}
+                  onOpenChange={setFormOpen}
+                  creators={creators}
+                  walletAddress={activeWalletAddress}
+                  isSubmitting={isNetworkMismatch}
+                />
+                <Button
+                  onClick={handleOpenForm}
+                  disabled={isNetworkMismatch || !hasHoldings}
+                  className="w-full sm:w-auto rounded-xl"
+                  size="lg"
+                >
+                  <svg className="size-4 mr-2" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2">
+                    <path d="M12 5v14M5 12h14" />
+                  </svg>
+                  Create Swap Proposal
+                </Button>
+                <p className="text-xs text-white/50 text-center sm:text-left">
+                  The counterparty will need to connect their wallet and accept the proposal to execute the atomic swap.
+                </p>
+              </div>
+            )}
+          </MarketplaceSection>
+        </main>
+      </div>
+
+      <AtomicSwapProposalForm
+        open={formOpen}
+        onOpenChange={setFormOpen}
+        creators={creators}
+        walletAddress={activeWalletAddress}
+        isSubmitting={isNetworkMismatch}
+      />
+    </div>
+  );
+}
\ No newline at end of file
diff --git a/src/pages/AtomicSwapProposalPage.tsx b/src/pages/AtomicSwapProposalPage.tsx
new file mode 100644
index 00000000..dcb8d648
--- /dev/null
+++ b/src/pages/AtomicSwapProposalPage.tsx
@@ -0,0 +1,14 @@
+import { AtomicSwapProposalReview } from '@/components/common/AtomicSwapProposalReview';
+
+export default function AtomicSwapProposalPage() {
+  return (
+    <div className="relative min-h-screen overflow-x-hidden bg-[linear-gradient(160deg,#08111f_0%,#10213b_45%,#f0b14d_160%)] px-6 pt-12 pb-28 md:px-12 md:pb-12">
+      <div className="absolute left-[-4rem] top-[10%] size-72 rounded-full bg-amber-300/20 blur-[100px]" />
+      <div className="absolute bottom-[8%] right-[-3rem] size-72 rounded-full bg-emerald-300/15 blur-[100px]" />
+      <div className="absolute inset-0 bg-[radial-gradient(circle_at_top,rgba(255,186,73,0.1),transparent_40%),radial-gradient(circle_at_bottom_left,rgba(74,222,128,0.08),transparent_35%)]" />
+      <div className="relative z-10 mx-auto max-w-3xl">
+        <AtomicSwapProposalReview />
+      </div>
+    </div>
+  );
+}
\ No newline at end of file
diff --git a/src/pages/LandingPage.tsx b/src/pages/LandingPage.tsx
index 9712237d..db5628ba 100644
--- a/src/pages/LandingPage.tsx
+++ b/src/pages/LandingPage.tsx
@@ -72,7 +72,7 @@ import { usePrefersReducedMotion } from '@/hooks/usePrefersReducedMotion';
 import { useNavigationTiming } from '@/hooks/useNavigationTiming';
 import { CREATOR_LIST_SORT_LAYOUT_TRANSITION } from '@/utils/creatorListSortTransition';
 import { creatorListKey } from '@/utils/creatorListKey.utils';
-import { Check, ChevronDown, Copy, RefreshCw } from 'lucide-react';
+import { Check, ChevronDown, Copy, RefreshCw, ArrowLeftRight } from 'lucide-react';
 import ClearedFiltersEmptyState from '@/components/common/ClearedFiltersEmptyState';
 import CreatorListPagination from '@/components/common/CreatorListPagination';
 import CreatorListGroupSeparator from '@/components/common/CreatorListGroupSeparator';
@@ -1467,6 +1467,17 @@ function LandingPage() {
 								</span>
 							</div>
 						</div>
+						<div className="md:col-span-2 mt-4 flex justify-end">
+							<Button
+								variant="outline"
+								onClick={() => window.location.href = '/swap/create'}
+								disabled={heldKeyPositions.filter(p => p.quantity && p.quantity > 0).length === 0}
+								className="rounded-xl border-white/15 bg-white/5 text-white/80 hover:bg-white/10 hover:text-white"
+							>
+								<ArrowLeftRight className="size-4 mr-2" aria-hidden="true" />
+								Create Atomic Swap
+							</Button>
+						</div>
 						{isLoading ? (
 							<CreatorHoldingsListSkeleton className="mt-6" />
 						) : heldKeyPositions.filter(
diff --git a/src/pages/ProfilePage.tsx b/src/pages/ProfilePage.tsx
index f54e39aa..9d7d6628 100644
--- a/src/pages/ProfilePage.tsx
+++ b/src/pages/ProfilePage.tsx
@@ -1,13 +1,16 @@
 import { useState } from 'react';
-import { BarChart2, Clock } from 'lucide-react';
+import { BarChart2, Clock, ArrowLeftRight } from 'lucide-react';
 import ReferralLinkPanel from '@/components/common/ReferralLinkPanel';
 import TradeHistoryTable from '@/components/common/TradeHistoryTable';
+import AtomicSwapHistory from '@/components/common/AtomicSwapHistory';
 import { ProfileTabPillGroup } from '@/components/common/ProfileTabPill';
 import { useProfileStore } from '@/hooks/useProfileStore';
+import { useAccount } from 'wagmi';
 
 const TABS = [
 	{ label: 'Holdings', value: 'holdings', icon: <BarChart2 /> },
 	{ label: 'Trade History', value: 'trade-history', icon: <Clock /> },
+	{ label: 'Atomic Swaps', value: 'atomic-swaps', icon: <ArrowLeftRight /> },
 ];
 
 // Mock wallet address – in a real app this would come from the wallet provider.
@@ -23,6 +26,8 @@ const keys = [
 
 export default function ProfilePage() {
 	const profile = useProfileStore(state => state.profile);
+	const { address: connectedAddress } = useAccount();
+	const walletAddress = connectedAddress || DEMO_WALLET;
 	const [activeTab, setActiveTab] = useState('holdings');
 
 	return (
@@ -73,7 +78,30 @@ export default function ProfilePage() {
 								</p>
 							</div>
 
-							<TradeHistoryTable walletAddress={DEMO_WALLET} />
+							<TradeHistoryTable walletAddress={walletAddress} />
+						</div>
+					</section>
+				)}
+
+				{/* Atomic swap history panel */}
+				{activeTab === 'atomic-swaps' && (
+					<section
+						id="profile-panel-atomic-swaps"
+						role="tabpanel"
+						aria-labelledby="profile-tab-atomic-swaps"
+						data-testid="portfolio-atomic-swaps-panel"
+					>
+						<div className="rounded-2xl border border-white/10 bg-white/[0.02] p-6 md:p-8">
+							<div className="mb-6">
+								<h2 className="font-grotesque text-2xl font-bold text-white">
+									Atomic Swap History
+								</h2>
+								<p className="mt-1 text-sm text-white/65">
+									Completed direct key exchanges with counterparties
+								</p>
+							</div>
+
+							<AtomicSwapHistory walletAddress={walletAddress} />
 						</div>
 					</section>
 				)}
diff --git a/src/routes.tsx b/src/routes.tsx
index 395c43df..fe856169 100644
--- a/src/routes.tsx
+++ b/src/routes.tsx
@@ -7,6 +7,8 @@ import NotificationsPage from './pages/NotificationsPage';
 import LeaderboardPage from './pages/LeaderboardPage';
 import ProfilePage from './pages/ProfilePage';
 import FollowingPage from './pages/FollowingPage';
+import AtomicSwapCreatePage from './pages/AtomicSwapCreatePage';
+import AtomicSwapProposalPage from './pages/AtomicSwapProposalPage';
 
 export const routes = [
 	{
@@ -53,6 +55,14 @@ export const routes = [
 		path: '/admin/dashboard',
 		element: <AdminDashboardPage />,
 	},
+	{
+		path: '/swap/create',
+		element: <AtomicSwapCreatePage />,
+	},
+	{
+		path: '/swap/:proposalId',
+		element: <AtomicSwapProposalPage />,
+	},
 	{
 		path: '*',
 		element: <NotFoundPage />,
diff --git a/src/services/atomicSwap.service.ts b/src/services/atomicSwap.service.ts
new file mode 100644
index 00000000..57ccdd1c
--- /dev/null
+++ b/src/services/atomicSwap.service.ts
@@ -0,0 +1,319 @@
+import { BaseApiService, type APIResponse } from './api.service';
+import { cacheManager } from '@/utils/cache.utils';
+import type {
+  AtomicSwapProposal,
+  CreateProposalInput,
+  ProposalValidationResult,
+  SwapHistoryEntry,
+} from '@/types/atomicSwap';
+import { generateProposalId, calculateExpiryTimestamp, isProposalExpired } from '@/types/atomicSwap';
+
+const PROPOSAL_CACHE_PREFIX = 'atomic_swap_proposal_';
+const PROPOSALS_LIST_CACHE_PREFIX = 'atomic_swap_proposals_';
+const PROPOSAL_CACHE_TTL_MS = 30_000;
+
+export interface CreateProposalParams {
+  proposerAddress: string;
+  offeredKeyId: string;
+  offeredKeyName: string;
+  offeredAmount: number;
+  desiredKeyId: string;
+  desiredKeyName: string;
+  desiredAmount: number;
+  expiryHours?: number;
+}
+
+export interface GetProposalParams {
+  proposalId: string;
+}
+
+export interface AcceptProposalParams {
+  proposalId: string;
+  counterpartyAddress: string;
+}
+
+export interface GetUserProposalsParams {
+  address: string;
+  status?: AtomicSwapProposal['status'];
+}
+
+export interface GetSwapHistoryParams {
+  address: string;
+  cursor?: string | null;
+  limit?: number;
+}
+
+export interface SwapHistoryPage {
+  swaps: SwapHistoryEntry[];
+  nextCursor: string | null;
+}
+
+class AtomicSwapService extends BaseApiService {
+  async createProposal(params: CreateProposalParams): Promise<AtomicSwapProposal> {
+    const proposal: AtomicSwapProposal = {
+      id: generateProposalId(),
+      proposer: 'Current User',
+      proposerAddress: params.proposerAddress,
+      offeredKeyId: params.offeredKeyId,
+      offeredKeyName: params.offeredKeyName,
+      offeredAmount: params.offeredAmount,
+      desiredKeyId: params.desiredKeyId,
+      desiredKeyName: params.desiredKeyName,
+      desiredAmount: params.desiredAmount,
+      status: 'pending',
+      createdAt: Date.now(),
+      expiresAt: calculateExpiryTimestamp(params.expiryHours),
+    };
+
+    try {
+      const response = await this.api.post<APIResponse<AtomicSwapProposal>>(
+        '/atomic-swaps/proposals',
+        proposal
+      );
+      return response.data.data;
+    } catch {
+      // Mock implementation for development
+      // In production, this would call the actual backend
+      this.cacheProposal(proposal);
+      return proposal;
+    }
+  }
+
+  async getProposal(params: GetProposalParams): Promise<AtomicSwapProposal | null> {
+    const cacheKey = `${PROPOSAL_CACHE_PREFIX}${params.proposalId}`;
+    const cached = cacheManager.get<AtomicSwapProposal>(cacheKey);
+    if (cached) return cached;
+
+    try {
+      const response = await this.api.get<APIResponse<AtomicSwapProposal>>(
+        `/atomic-swaps/proposals/${params.proposalId}`
+      );
+      const proposal = response.data.data;
+      this.cacheProposal(proposal);
+      return proposal;
+    } catch {
+      // Mock implementation - check local storage for demo
+      const stored = this.getStoredProposal(params.proposalId);
+      return stored;
+    }
+  }
+
+  async acceptProposal(params: AcceptProposalParams): Promise<{ transactionHash: string; proposal: AtomicSwapProposal }> {
+    try {
+      const response = await this.api.post<APIResponse<{ transactionHash: string; proposal: AtomicSwapProposal }>>(
+        `/atomic-swaps/proposals/${params.proposalId}/accept`,
+        { counterpartyAddress: params.counterpartyAddress }
+      );
+      return response.data.data;
+    } catch {
+      // Mock implementation
+      const proposal = await this.getProposal({ proposalId: params.proposalId });
+      if (!proposal) throw new Error('Proposal not found');
+      if (isProposalExpired(proposal)) throw new Error('Proposal has expired');
+      if (proposal.status !== 'pending') throw new Error('Proposal is no longer actionable');
+
+      const updatedProposal: AtomicSwapProposal = {
+        ...proposal,
+        status: 'executed',
+        counterpartyAddress: params.counterpartyAddress,
+        counterparty: 'Counterparty',
+        executedAt: Date.now(),
+        transactionHash: `0x${Math.random().toString(16).slice(2, 66)}`,
+      };
+      this.cacheProposal(updatedProposal);
+      this.addToSwapHistory(updatedProposal);
+      return { transactionHash: updatedProposal.transactionHash!, proposal: updatedProposal };
+    }
+  }
+
+  async getUserProposals(params: GetUserProposalsParams): Promise<AtomicSwapProposal[]> {
+    const cacheKey = `${PROPOSALS_LIST_CACHE_PREFIX}${params.address}_${params.status ?? 'all'}`;
+    const cached = cacheManager.get<AtomicSwapProposal[]>(cacheKey);
+    if (cached) return cached;
+
+    try {
+      const response = await this.api.get<APIResponse<AtomicSwapProposal[]>>(
+        `/atomic-swaps/proposals`,
+        {
+          params: {
+            address: params.address,
+            ...(params.status ? { status: params.status } : {}),
+          },
+        }
+      );
+      const proposals = response.data.data;
+      cacheManager.set(cacheKey, proposals, PROPOSAL_CACHE_TTL_MS);
+      return proposals;
+    } catch {
+      // Mock implementation
+      return this.getStoredUserProposals(params.address, params.status);
+    }
+  }
+
+  async getSwapHistory(params: GetSwapHistoryParams): Promise<SwapHistoryPage> {
+    try {
+      const response = await this.api.get<APIResponse<SwapHistoryPage>>(
+        `/atomic-swaps/history/${params.address}`,
+        {
+          params: {
+            ...(params.cursor ? { cursor: params.cursor } : {}),
+            ...(params.limit ? { limit: params.limit } : {}),
+          },
+        }
+      );
+      return response.data.data;
+    } catch {
+      // Mock implementation
+      return this.getStoredSwapHistory(params.address, params.cursor, params.limit);
+    }
+  }
+
+  private cacheProposal(proposal: AtomicSwapProposal): void {
+    const cacheKey = `${PROPOSAL_CACHE_PREFIX}${proposal.id}`;
+    cacheManager.set(cacheKey, proposal, PROPOSAL_CACHE_TTL_MS);
+  }
+
+  private getStoredProposal(proposalId: string): AtomicSwapProposal | null {
+    if (typeof window === 'undefined') return null;
+    try {
+      const stored = localStorage.getItem(`atomic_swap_proposal_${proposalId}`);
+      return stored ? JSON.parse(stored) : null;
+    } catch {
+      return null;
+    }
+  }
+
+  private getStoredUserProposals(address: string, status?: AtomicSwapProposal['status']): AtomicSwapProposal[] {
+    if (typeof window === 'undefined') return [];
+    try {
+      const allKeys = Object.keys(localStorage);
+      const proposalKeys = allKeys.filter(k => k.startsWith('atomic_swap_proposal_'));
+      const proposals: AtomicSwapProposal[] = [];
+      for (const key of proposalKeys) {
+        const stored = localStorage.getItem(key);
+        if (stored) {
+          const proposal = JSON.parse(stored) as AtomicSwapProposal;
+          if (
+            (proposal.proposerAddress === address || proposal.counterpartyAddress === address) &&
+            (!status || proposal.status === status)
+          ) {
+            proposals.push(proposal);
+          }
+        }
+      }
+      return proposals.sort((a, b) => b.createdAt - a.createdAt);
+    } catch {
+      return [];
+    }
+  }
+
+  private addToSwapHistory(proposal: AtomicSwapProposal): void {
+    if (typeof window === 'undefined') return;
+    try {
+      const historyKey = `atomic_swap_history_${proposal.proposerAddress}`;
+      const existing = localStorage.getItem(historyKey);
+      const history: SwapHistoryEntry[] = existing ? JSON.parse(existing) : [];
+
+      const entry: SwapHistoryEntry = {
+        id: `swap_hist_${Date.now()}_${Math.random().toString(36).slice(2, 9)}`,
+        type: 'atomic-swap',
+        proposer: proposal.proposer,
+        proposerAddress: proposal.proposerAddress,
+        counterparty: proposal.counterparty ?? 'Unknown',
+        counterpartyAddress: proposal.counterpartyAddress ?? '',
+        offeredKeyId: proposal.offeredKeyId,
+        offeredKeyName: proposal.offeredKeyName,
+        offeredAmount: proposal.offeredAmount,
+        receivedKeyId: proposal.desiredKeyId,
+        receivedKeyName: proposal.desiredKeyName,
+        receivedAmount: proposal.desiredAmount,
+        timestamp: proposal.executedAt ?? Date.now(),
+        transactionHash: proposal.transactionHash ?? '',
+        status: 'completed',
+      };
+
+      history.unshift(entry);
+      localStorage.setItem(historyKey, JSON.stringify(history.slice(0, 100)));
+    } catch {
+      // Ignore storage errors
+    }
+  }
+
+  private getStoredSwapHistory(
+    address: string,
+    cursor: string | null | undefined,
+    limit = 20
+  ): SwapHistoryPage {
+    if (typeof window === 'undefined') return { swaps: [], nextCursor: null };
+    try {
+      const historyKey = `atomic_swap_history_${address}`;
+      const stored = localStorage.getItem(historyKey);
+      const allSwaps: SwapHistoryEntry[] = stored ? JSON.parse(stored) : [];
+
+      let startIndex = 0;
+      if (cursor) {
+        const cursorIndex = allSwaps.findIndex(s => s.id === cursor);
+        if (cursorIndex !== -1) startIndex = cursorIndex + 1;
+      }
+
+      const pageSwaps = allSwaps.slice(startIndex, startIndex + limit);
+      const nextCursor = startIndex + limit < allSwaps.length ? pageSwaps[pageSwaps.length - 1].id : null;
+
+      return { swaps: pageSwaps, nextCursor };
+    } catch {
+      return { swaps: [], nextCursor: null };
+    }
+  }
+
+  validateProposal(input: CreateProposalInput, userHoldings: Record<string, number>): ProposalValidationResult {
+    const errors: string[] = [];
+
+    if (!input.offeredKeyId) errors.push('Offered key is required');
+    if (!input.desiredKeyId) errors.push('Desired key is required');
+    if (!Number.isFinite(input.offeredAmount) || input.offeredAmount <= 0) {
+      errors.push('Offered amount must be greater than zero');
+    }
+    if (!Number.isFinite(input.desiredAmount) || input.desiredAmount <= 0) {
+      errors.push('Desired amount must be greater than zero');
+    }
+    if (input.offeredKeyId === input.desiredKeyId) {
+      errors.push('Cannot create a swap with the same key on both sides');
+    }
+
+    const availableHolding = userHoldings[input.offeredKeyId] ?? 0;
+    if (input.offeredAmount > availableHolding) {
+      errors.push(`Insufficient holdings: you have ${availableHolding} ${input.offeredKeyName} keys`);
+    }
+
+    return { valid: errors.length === 0, errors };
+  }
+}
+
+export const atomicSwapService = new AtomicSwapService();
+
+export async function createAtomicSwapProposal(params: CreateProposalParams): Promise<AtomicSwapProposal> {
+  return atomicSwapService.createProposal(params);
+}
+
+export async function fetchAtomicSwapProposal(params: GetProposalParams): Promise<AtomicSwapProposal | null> {
+  return atomicSwapService.getProposal(params);
+}
+
+export async function acceptAtomicSwapProposal(params: AcceptProposalParams): Promise<{ transactionHash: string; proposal: AtomicSwapProposal }> {
+  return atomicSwapService.acceptProposal(params);
+}
+
+export async function fetchUserAtomicSwapProposals(params: GetUserProposalsParams): Promise<AtomicSwapProposal[]> {
+  return atomicSwapService.getUserProposals(params);
+}
+
+export async function fetchAtomicSwapHistory(params: GetSwapHistoryParams): Promise<SwapHistoryPage> {
+  return atomicSwapService.getSwapHistory(params);
+}
+
+export function validateAtomicSwapProposal(
+  input: CreateProposalInput,
+  userHoldings: Record<string, number>
+): ProposalValidationResult {
+  return atomicSwapService.validateProposal(input, userHoldings);
+}
\ No newline at end of file
diff --git a/src/types/atomicSwap.ts b/src/types/atomicSwap.ts
new file mode 100644
index 00000000..c41e0d27
--- /dev/null
+++ b/src/types/atomicSwap.ts
@@ -0,0 +1,75 @@
+export type ProposalStatus = 'pending' | 'accepted' | 'expired' | 'executed' | 'cancelled';
+
+export interface AtomicSwapProposal {
+  id: string;
+  proposer: string;
+  proposerAddress: string;
+  offeredKeyId: string;
+  offeredKeyName: string;
+  offeredAmount: number;
+  desiredKeyId: string;
+  desiredKeyName: string;
+  desiredAmount: number;
+  status: ProposalStatus;
+  createdAt: number;
+  expiresAt: number;
+  executedAt?: number;
+  counterparty?: string;
+  counterpartyAddress?: string;
+  transactionHash?: string;
+}
+
+export interface CreateProposalInput {
+  offeredKeyId: string;
+  offeredKeyName: string;
+  offeredAmount: number;
+  desiredKeyId: string;
+  desiredKeyName: string;
+  desiredAmount: number;
+  expiryHours?: number;
+}
+
+export interface ProposalValidationResult {
+  valid: boolean;
+  errors: string[];
+}
+
+export interface SwapHistoryEntry {
+  id: string;
+  type: 'atomic-swap';
+  proposer: string;
+  proposerAddress: string;
+  counterparty: string;
+  counterpartyAddress: string;
+  offeredKeyId: string;
+  offeredKeyName: string;
+  offeredAmount: number;
+  receivedKeyId: string;
+  receivedKeyName: string;
+  receivedAmount: number;
+  timestamp: number;
+  transactionHash: string;
+  status: 'completed' | 'failed';
+}
+
+export const PROPOSAL_EXPIRY_HOURS = 24;
+export const PROPOSAL_ID_PREFIX = 'swap_';
+
+export function generateProposalId(): string {
+  return `${PROPOSAL_ID_PREFIX}${Date.now()}_${Math.random().toString(36).slice(2, 11)}`;
+}
+
+export function calculateExpiryTimestamp(hours: number = PROPOSAL_EXPIRY_HOURS): number {
+  return Date.now() + hours * 60 * 60 * 1000;
+}
+
+export function isProposalExpired(proposal: AtomicSwapProposal): boolean {
+  return Date.now() > proposal.expiresAt;
+}
+
+export function canAcceptProposal(proposal: AtomicSwapProposal, userAddress: string): boolean {
+  if (proposal.status !== 'pending') return false;
+  if (isProposalExpired(proposal)) return false;
+  if (proposal.proposerAddress === userAddress) return false;
+  return true;
+}
\ No newline at end of file