From f5eb6c0e4522175f7c2b863e7ec67ebc6afe9ea4 Mon Sep 17 00:00:00 2001
From: GianM <gian@quantum3labs.com>
Date: Sat, 16 May 2026 18:29:45 +0700
Subject: [PATCH 1/5] Release: X402/CDP bazaar deposit + llms.txt docs to
 production (#262)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* docs: add llms.txt intro page for AI agents (#256)

Add a GitBook-friendly page introducing PolyPay's llms.txt support so
non-technical readers can discover the feature and link AI agents to
the live playbook.

- New page docs/llms-txt-for-agents.md covering what llms.txt is, the
  live endpoint, the five integration flows it documents, two ways to
  wire an agent up, and compatibility notes.
- Add the page to docs/SUMMARY.md between x402 and Architecture.
- Fix stale api.polypay.xyz references in docs/x402-deposits.md to the
  real api.polypay.pro host.

* feat(x402): add Coinbase CDP bazaar deposit route for agentic.market listing (#260)

Adds a second x402 deposit endpoint /x402/bazaar/deposit/:multisig that
routes through Coinbase CDP facilitator instead of PayAI, so the resource
gets indexed in CDP discovery and surfaces on agentic.market.

The default /x402/deposit/:multisig path keeps using PayAI (better rate
limits, simpler auth) — no UI change. CDP path activates implicitly when
CDP_API_KEY_ID is set; otherwise it returns a clear config error.

CDP requires Ed25519 JWT signed per-request (2-min TTL), so the service
now lazy-imports @coinbase/x402 createAuthHeader to produce the
Authorization header. Payment requirements for the CDP path also embed a
declareDiscoveryExtension-shaped extensions.bazaar block (strict JSON
Schema), without which CDP would settle but not index.

Includes scripts/bazaar-bootstrap.ts to produce the first real settlement
that triggers CDP indexing — bootstrap must run against a deployed
backend (the resource URL ends up in the catalog).

Refs #259

---------

Co-authored-by: BoHsuu <115441679+Huygon764@users.noreply.github.com>

From ceb386b27f177d42c73171f93d64e3f69719153b Mon Sep 17 00:00:00 2001
From: BoHsuu <115441679+Huygon764@users.noreply.github.com>
Date: Tue, 19 May 2026 22:11:01 +0700
Subject: [PATCH 2/5] fix(x402): index CDP bazaar resource on settle + 402 on
 unpaid crawl (#272)

Two independent reasons the deposit endpoint was never cataloged in the
CDP x402 Bazaar, both confirmed against @x402/extensions/bazaar source:

- processDeposit threw 400 when X-PAYMENT was missing. The CDP Bazaar
  crawls the endpoint with the bazaar-extension input (no payment) and
  only indexes resources that answer 402. Now returns 402 + the
  PaymentRequired body (canonical x402 unpaid response).

- extractDiscoveryInfo reads the bazaar extension from
  paymentPayload.extensions["bazaar"] for v2; the CDP settle payload
  sent extensions:{}. Attach the discovery extension (and resource
  description/mimeType) to the v2 payload so settlement catalogs it.

Also add routeTemplate so the multisig-address path segment normalizes
to /:multisigAddress, and align schema.required with the SDK
(createBodyDiscoveryExtension) so info validates under Ajv 2020.
---
 packages/backend/src/x402/x402.service.ts | 66 +++++++++++++++++------
 1 file changed, 50 insertions(+), 16 deletions(-)

diff --git a/packages/backend/src/x402/x402.service.ts b/packages/backend/src/x402/x402.service.ts
index ea195480..8ef3b953 100644
--- a/packages/backend/src/x402/x402.service.ts
+++ b/packages/backend/src/x402/x402.service.ts
@@ -149,8 +149,20 @@ export class X402Service {
     facilitator: Facilitator = Facilitator.PayAI,
   ): Promise<X402DepositResponse> {
     if (facilitator === Facilitator.CDP) this.assertCdpEnabled();
+    // No payment yet: respond with 402 + PaymentRequired body (canonical x402).
+    // The client retries with X-PAYMENT. This is also what the CDP Bazaar
+    // crawler expects — it POSTs the bazaar-extension input without a payment
+    // and requires a 402 to index the resource; a 400 here blocks indexing.
     if (!paymentHeader) {
-      throw new BadRequestException('Missing X-PAYMENT header');
+      const body = await this.buildDiscoveryResponse(
+        multisigAddress,
+        resourceUrl,
+        facilitator,
+      );
+      throw new HttpException(
+        body as unknown as Record<string, unknown>,
+        HttpStatus.PAYMENT_REQUIRED,
+      );
     }
     const account = await this.assertAccount(multisigAddress);
     const payload = decodeXPaymentHeader(paymentHeader);
@@ -201,15 +213,19 @@ export class X402Service {
           resourceUrl,
           signedAmount,
         );
+        // extractDiscoveryInfo (facilitator.ts) reads the bazaar extension from
+        // paymentPayload.extensions["bazaar"] for v2 — it is NOT read from the
+        // 402 response or paymentRequirements. A v1 X-PAYMENT (UI / bootstrap)
+        // carries no extensions, so we attach the same declaration here.
         const v2Payload: V2PaymentPayload = {
           x402Version: 2,
-          resource: { url: resourceUrl },
+          resource: this.buildV2Resource(resourceUrl, account.address),
           accepted: v2Requirements,
           payload: {
             authorization: payload.payload.authorization,
             signature: payload.payload.signature,
           },
-          extensions: {},
+          extensions: { bazaar: this.buildCdpBazaarExtension(resourceUrl) },
         };
         await this.cdpVerify(v2Payload, v2Requirements);
         const txHash = await this.cdpSettle(v2Payload, v2Requirements);
@@ -492,6 +508,20 @@ export class X402Service {
     };
   }
 
+  // extractDiscoveryInfo (SDK @x402/extensions/bazaar) reads resource.description
+  // and resource.mimeType into the catalog entry, so the same resource object is
+  // used for both the 402 response and the settle payload to avoid drift.
+  private buildV2Resource(resourceUrl: string, payTo: string): V2ResourceInfo {
+    return {
+      url: resourceUrl,
+      description:
+        `Gasless USDC deposit to PolyPay multisig ${payTo}. Sign EIP-3009 ` +
+        `transferWithAuthorization for any amount in [${MIN_DEPOSIT}, ${MAX_DEPOSIT}] ` +
+        `(6-decimals USDC).`,
+      mimeType: 'application/json',
+    };
+  }
+
   private buildV2PaymentRequired(
     chainId: number,
     payTo: string,
@@ -500,14 +530,7 @@ export class X402Service {
   ): V2PaymentRequired {
     return {
       x402Version: 2,
-      resource: {
-        url: resourceUrl,
-        description:
-          `Gasless USDC deposit to PolyPay multisig ${payTo}. Sign EIP-3009 ` +
-          `transferWithAuthorization for any amount in [${MIN_DEPOSIT}, ${MAX_DEPOSIT}] ` +
-          `(6-decimals USDC).`,
-        mimeType: 'application/json',
-      },
+      resource: this.buildV2Resource(resourceUrl, payTo),
       accepts: [
         this.buildV2PaymentRequirementsLeaf(
           chainId,
@@ -516,14 +539,24 @@ export class X402Service {
           amount,
         ),
       ],
-      extensions: { bazaar: this.buildCdpBazaarExtension() },
+      extensions: { bazaar: this.buildCdpBazaarExtension(resourceUrl) },
     };
   }
 
   // Mirrors @x402/extensions/bazaar createBodyDiscoveryExtension(...) output
-  // for a POST endpoint with a JSON body. Shape verified byte-equal against
-  // the SDK and validateDiscoveryExtension() = true in offline tests.
-  private buildCdpBazaarExtension(): Record<string, unknown> {
+  // for a POST endpoint with a JSON body. `info` is validated against `schema`
+  // by the facilitator's validateDiscoveryExtension (Ajv 2020); a mismatch
+  // makes extractDiscoveryInfo skip the resource.
+  //
+  // routeTemplate: the resource path ends in a high-cardinality multisig
+  // address. extractDiscoveryInfo (facilitator.ts) reads bazaarExtension.
+  // routeTemplate (sibling of info/schema) and uses it as the canonical
+  // catalog path, so we replace the address segment with :multisigAddress.
+  private buildCdpBazaarExtension(
+    resourceUrl: string,
+  ): Record<string, unknown> {
+    const path = new URL(resourceUrl).pathname;
+    const routeTemplate = path.replace(/\/[^/]+$/, '/:multisigAddress');
     const inputBodyExample = { memo: 'optional payment memo' };
     const inputBodySchema = {
       type: 'object',
@@ -542,6 +575,7 @@ export class X402Service {
       status: 'SETTLED',
     };
     return {
+      routeTemplate,
       info: {
         input: {
           type: 'http',
@@ -566,7 +600,7 @@ export class X402Service {
               },
               body: inputBodySchema,
             },
-            required: ['type', 'bodyType', 'body'],
+            required: ['type', 'method', 'bodyType', 'body'],
             additionalProperties: false,
           },
           output: {

From 452698f0dd04122b0cfa7f162cea424d873539f5 Mon Sep 17 00:00:00 2001
From: BoHsuu <115441679+Huygon764@users.noreply.github.com>
Date: Thu, 21 May 2026 10:23:10 +0700
Subject: [PATCH 3/5] fix(zkverify): update Horizen testnet zkVerify contract
 address (#274)

---
 packages/shared/src/contracts/contracts-config.ts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/shared/src/contracts/contracts-config.ts b/packages/shared/src/contracts/contracts-config.ts
index d48fc81c..8213ab1a 100644
--- a/packages/shared/src/contracts/contracts-config.ts
+++ b/packages/shared/src/contracts/contracts-config.ts
@@ -1,7 +1,7 @@
 export const CONTRACT_CONFIG_BY_CHAIN_ID = {
   2651420: {
     // Horizen testnet
-    zkVerifyAddress: "0xCC02D0A54F3184dF4c88811E5b9FAb7ff8131e4a",
+    zkVerifyAddress: "0x3098A6974649478f0133046e44105AA84e868C21",
     vkHash:
       "0xb3c5381523a496996868370791ec7ae490be7e2c996296fb67708daed8a6ea38",
     poseidonT3Address: "0x3333333C0A88F9BE4fd23ed0536F9B6c427e3B93",

From 2fbdc1ab005f29a25919ae892785173371241b92 Mon Sep 17 00:00:00 2001
From: BoHsuu <115441679+Huygon764@users.noreply.github.com>
Date: Thu, 21 May 2026 12:33:10 +0700
Subject: [PATCH 4/5] chore(backend): horizen testnet wipe script + e2e fixes
 (#275)

* chore(backend): horizen testnet wipe script + e2e fixes after chainId require

- Add scripts/wipe-horizen-testnet.ts (yarn wipe:horizen-testnet) to drop
  all chainId 2651420 accounts + their transactions/votes/signers/contacts
  /reserved-nonces. Used after the Horizen testnet zkVerify address swap
  to clear stale state on staging. Safety: refuses when APP_NETWORK=mainnet,
  unlinks batch_items.contactId before cascading account deletes,
  --dry-run prints counts without touching data.

- Pass chainId in e2e + staging-e2e test utilities for reserveNonce and
  createTransaction calls. The endpoints started requiring chainId after
  the (address, chainId) account key rollout; the tests still sent the
  legacy shape and got 400.

- stagingExecuteTransaction: fall back to polling GET /transactions/:txId
  when the initial POST hangs up (socket reset by edge / proxy idle
  timeout) instead of bubbling a cryptic ECONNRESET. Server already
  persists txHash right after on-chain submission so the poll is safe.

* chore(docker): include backend scripts/ in runner image for Cloud Run Jobs
---
 docker/backend.Dockerfile                     |   3 +
 packages/backend/package.json                 |   3 +-
 .../backend/scripts/wipe-horizen-testnet.ts   | 158 ++++++++++++++++++
 .../backend/test/e2e/transaction.e2e-spec.ts  |   4 +
 .../test/e2e/transaction.staging.e2e-spec.ts  |   4 +
 .../backend/test/utils/staging-api.util.ts    |  66 ++++++--
 .../backend/test/utils/transaction.util.ts    |   4 +-
 7 files changed, 230 insertions(+), 12 deletions(-)
 create mode 100644 packages/backend/scripts/wipe-horizen-testnet.ts

diff --git a/docker/backend.Dockerfile b/docker/backend.Dockerfile
index c058cddb..7a30e705 100644
--- a/docker/backend.Dockerfile
+++ b/docker/backend.Dockerfile
@@ -91,6 +91,9 @@ COPY --chown=nestjs:nodejs --from=builder /app/packages/backend/prisma.config.ts
 # Copy assets folder
 COPY --chown=nestjs:nodejs --from=builder /app/packages/backend/assets ./packages/backend/assets
 
+# Copy one-off maintenance scripts (run via `yarn <script>` from Cloud Run Jobs).
+COPY --chown=nestjs:nodejs --from=builder /app/packages/backend/scripts ./packages/backend/scripts
+
 USER nestjs
 
 WORKDIR /app/packages/backend
diff --git a/packages/backend/package.json b/packages/backend/package.json
index 0f0cb36a..6dd4c310 100644
--- a/packages/backend/package.json
+++ b/packages/backend/package.json
@@ -19,7 +19,8 @@
     "test:debug": "node --inspect-brk -r tsconfig-paths/register -r ts-node/register node_modules/.bin/jest --runInBand",
     "test:e2e": "jest --config ./test/jest-e2e.json",
     "test:e2e:staging": "jest --config ./test/jest-staging-e2e.json",
-    "report": "ts-node scripts/generate-analytics-report.ts"
+    "report": "ts-node scripts/generate-analytics-report.ts",
+    "wipe:horizen-testnet": "tsx scripts/wipe-horizen-testnet.ts"
   },
   "dependencies": {
     "@aztec/bb.js": "0.84.0",
diff --git a/packages/backend/scripts/wipe-horizen-testnet.ts b/packages/backend/scripts/wipe-horizen-testnet.ts
new file mode 100644
index 00000000..4592a102
--- /dev/null
+++ b/packages/backend/scripts/wipe-horizen-testnet.ts
@@ -0,0 +1,158 @@
+/**
+ * One-off cleanup: wipe all PolyPay data tied to Horizen testnet
+ * (chainId 2651420) so accounts created against the old zkVerify contract
+ * stop showing up after the contract address migration.
+ *
+ * Run: yarn wipe:horizen-testnet
+ * GCP job command: cd packages/backend && yarn install --frozen-lockfile && yarn wipe:horizen-testnet
+ *
+ * Safety:
+ *  - Refuses to run when APP_NETWORK=mainnet (wrong environment).
+ *  - Wraps deletions in a single Prisma transaction; either all rows go
+ *    or none do, so a partial run can't leave the DB in a half-wiped state.
+ *  - User accounts, login_history, notifications, and batch_items are
+ *    intentionally preserved — they're not tied to a specific chain and
+ *    deleting them would log users out / drop unrelated state.
+ */
+import 'dotenv/config';
+import { PrismaPg } from '@prisma/adapter-pg';
+import { PrismaClient } from '../src/generated/prisma/client';
+
+const HORIZEN_TESTNET_CHAIN_ID = 2651420;
+const DRY_RUN = process.argv.includes('--dry-run');
+
+async function main() {
+  if (process.env.APP_NETWORK === 'mainnet') {
+    throw new Error(
+      'Refusing to run: APP_NETWORK=mainnet. This script only targets Horizen testnet data.',
+    );
+  }
+
+  const connectionString = process.env.DATABASE_URL;
+  if (!connectionString) {
+    throw new Error('DATABASE_URL is not set');
+  }
+  const adapter = new PrismaPg({ connectionString });
+  const prisma = new PrismaClient({ adapter });
+  const chainId = HORIZEN_TESTNET_CHAIN_ID;
+
+  console.log(
+    `[wipe-horizen-testnet] mode=${DRY_RUN ? 'DRY-RUN' : 'DELETE'} chainId=${chainId}`,
+  );
+
+  try {
+    const accounts = await prisma.account.findMany({
+      where: { chainId },
+      select: { id: true },
+    });
+    const accountIds = accounts.map((a) => a.id);
+
+    const contacts = accountIds.length
+      ? await prisma.contact.findMany({
+          where: { accountId: { in: accountIds } },
+          select: { id: true },
+        })
+      : [];
+    const contactIds = contacts.map((c) => c.id);
+
+    const txIds = (
+      await prisma.transaction.findMany({
+        where: { chainId },
+        select: { txId: true },
+      })
+    ).map((t) => t.txId);
+
+    const voteCount = txIds.length
+      ? await prisma.vote.count({ where: { txId: { in: txIds } } })
+      : 0;
+    const signerCount = accountIds.length
+      ? await prisma.accountSigner.count({
+          where: { accountId: { in: accountIds } },
+        })
+      : 0;
+    const reservedNonceCount = await prisma.reservedNonce.count({
+      where: { chainId },
+    });
+    const batchItemRefCount = contactIds.length
+      ? await prisma.batchItem.count({
+          where: { contactId: { in: contactIds } },
+        })
+      : 0;
+
+    console.log('[wipe-horizen-testnet] candidates', {
+      accounts: accountIds.length,
+      contacts: contactIds.length,
+      transactions: txIds.length,
+      votes: voteCount,
+      account_signers: signerCount,
+      reserved_nonces: reservedNonceCount,
+      batch_items_to_unlink: batchItemRefCount,
+    });
+
+    if (DRY_RUN) {
+      console.log('[wipe-horizen-testnet] dry-run, no rows deleted.');
+      return;
+    }
+
+    if (accountIds.length === 0 && txIds.length === 0 && reservedNonceCount === 0) {
+      console.log('[wipe-horizen-testnet] nothing to delete, exiting.');
+      return;
+    }
+
+    await prisma.$transaction(async (tx) => {
+      // BatchItem.contact has no onDelete cascade — Postgres will reject the
+      // Account delete (which cascades Contact) if any batch item still
+      // points to a contact we're about to remove. Null the link first.
+      if (contactIds.length) {
+        const { count } = await tx.batchItem.updateMany({
+          where: { contactId: { in: contactIds } },
+          data: { contactId: null },
+        });
+        console.log(`[wipe] unlinked batch_items.contactId: ${count}`);
+      }
+
+      if (txIds.length) {
+        const { count } = await tx.vote.deleteMany({
+          where: { txId: { in: txIds } },
+        });
+        console.log(`[wipe] deleted votes: ${count}`);
+      }
+
+      {
+        const { count } = await tx.transaction.deleteMany({
+          where: { chainId },
+        });
+        console.log(`[wipe] deleted transactions: ${count}`);
+      }
+
+      if (accountIds.length) {
+        const { count } = await tx.accountSigner.deleteMany({
+          where: { accountId: { in: accountIds } },
+        });
+        console.log(`[wipe] deleted account_signers: ${count}`);
+      }
+
+      {
+        const { count } = await tx.reservedNonce.deleteMany({
+          where: { chainId },
+        });
+        console.log(`[wipe] deleted reserved_nonces: ${count}`);
+      }
+
+      // Account deletion cascades Contact, ContactGroup, ContactGroupEntry.
+      {
+        const { count } = await tx.account.deleteMany({ where: { chainId } });
+        console.log(`[wipe] deleted accounts (cascades contacts/groups): ${count}`);
+      }
+    });
+
+    console.log('[wipe-horizen-testnet] done.');
+  } finally {
+    await prisma.$disconnect();
+  }
+}
+
+main().catch((err) => {
+  console.error('[wipe-horizen-testnet] fatal', err);
+  process.exit(1);
+});
diff --git a/packages/backend/test/e2e/transaction.e2e-spec.ts b/packages/backend/test/e2e/transaction.e2e-spec.ts
index 195c13c4..c4259344 100644
--- a/packages/backend/test/e2e/transaction.e2e-spec.ts
+++ b/packages/backend/test/e2e/transaction.e2e-spec.ts
@@ -111,6 +111,7 @@ describe('Transaction E2E', () => {
         const { nonce } = await apiReserveNonce(
           tokensA.accessToken,
           accountAddress,
+          TEST_CHAIN_ID,
         );
 
         const { to, value, callData } = buildSingleTransferParams(
@@ -131,6 +132,7 @@ describe('Transaction E2E', () => {
           nonce,
           type: TxType.TRANSFER,
           accountAddress,
+          chainId: TEST_CHAIN_ID,
           to: TEST_RECIPIENT,
           value: amount.amountString,
           threshold: TEST_THRESHOLD,
@@ -176,6 +178,7 @@ describe('Transaction E2E', () => {
       const { nonce: batchNonce } = await apiReserveNonce(
         tokensA.accessToken,
         accountAddress,
+        TEST_CHAIN_ID,
       );
 
       const batchVotePayloadA = await generateVotePayload(
@@ -193,6 +196,7 @@ describe('Transaction E2E', () => {
           nonce: batchNonce,
           type: TxType.BATCH,
           accountAddress,
+          chainId: TEST_CHAIN_ID,
           to: accountAddress,
           value: '0',
           threshold: TEST_THRESHOLD,
diff --git a/packages/backend/test/e2e/transaction.staging.e2e-spec.ts b/packages/backend/test/e2e/transaction.staging.e2e-spec.ts
index d905164f..7b1621eb 100644
--- a/packages/backend/test/e2e/transaction.staging.e2e-spec.ts
+++ b/packages/backend/test/e2e/transaction.staging.e2e-spec.ts
@@ -133,6 +133,7 @@ describe('Transaction Staging E2E', () => {
         const { nonce } = await stagingReserveNonce(
           tokensA.accessToken,
           accountAddress,
+          TEST_CHAIN_ID,
         );
 
         const { to, value, callData } = buildSingleTransferParams(
@@ -153,6 +154,7 @@ describe('Transaction Staging E2E', () => {
           nonce,
           type: TxType.TRANSFER,
           accountAddress,
+          chainId: TEST_CHAIN_ID,
           to: TEST_RECIPIENT,
           value: amount.amountString,
           threshold: TEST_THRESHOLD,
@@ -198,6 +200,7 @@ describe('Transaction Staging E2E', () => {
       const { nonce: batchNonce } = await stagingReserveNonce(
         tokensA.accessToken,
         accountAddress,
+        TEST_CHAIN_ID,
       );
 
       const batchVotePayloadA = await generateVotePayload(
@@ -215,6 +218,7 @@ describe('Transaction Staging E2E', () => {
           nonce: batchNonce,
           type: TxType.BATCH,
           accountAddress,
+          chainId: TEST_CHAIN_ID,
           to: accountAddress,
           value: '0',
           threshold: TEST_THRESHOLD,
diff --git a/packages/backend/test/utils/staging-api.util.ts b/packages/backend/test/utils/staging-api.util.ts
index 968fadba..ec7f6d75 100644
--- a/packages/backend/test/utils/staging-api.util.ts
+++ b/packages/backend/test/utils/staging-api.util.ts
@@ -82,11 +82,12 @@ export async function stagingCreateBatchItem(
 export async function stagingReserveNonce(
   accessToken: string,
   accountAddress: `0x${string}`,
+  chainId: number,
 ) {
   try {
     const response = await axios.post(
       `${BASE_URL}${API_ENDPOINTS.transactions.reserveNonce}`,
-      { accountAddress },
+      { accountAddress, chainId },
       { headers: authHeaders(accessToken) },
     );
 
@@ -151,23 +152,68 @@ export async function stagingExecuteTransaction(
   accessToken: string,
   txId: string,
 ) {
+  // Execute waits for on-chain receipt + zkVerify aggregation, which on a
+  // slow testnet can run several minutes. Most managed hosts (Cloudflare,
+  // Vercel, ALB) reset idle inbound connections somewhere between 60-300s
+  // regardless of how long the server keeps working. So we treat the
+  // initial POST as fire-and-forget: swallow socket hang-ups / undefined
+  // responses, then poll the transaction's status until EXECUTED or FAILED.
+  // The executor persists txHash to DB right after on-chain submission,
+  // so the poll can hand it back without a fresh server response.
   try {
     const response = await axios.post(
       `${BASE_URL}${API_ENDPOINTS.transactions.execute(Number(txId))}`,
       undefined,
-      { headers: authHeaders(accessToken) },
+      {
+        headers: authHeaders(accessToken),
+        timeout: 10 * 60_000,
+      },
     );
-
-    return response.data as { txHash: string };
+    if (response.data?.txHash) {
+      return response.data as { txHash: string };
+    }
   } catch (error: any) {
-    if (axios.isAxiosError(error)) {
-      console.error('stagingExecuteTransaction error', {
-        status: error.response?.status,
-        data: error.response?.data,
-      });
+    const isSocketHangUp =
+      error?.code === 'ECONNRESET' ||
+      error?.message?.includes('socket hang up') ||
+      (axios.isAxiosError(error) && error.response === undefined);
+
+    if (!isSocketHangUp) {
+      if (axios.isAxiosError(error)) {
+        console.error('stagingExecuteTransaction error', {
+          status: error.response?.status,
+          data: error.response?.data,
+        });
+      }
+      throw error;
     }
-    throw error;
+
+    console.warn(
+      `stagingExecuteTransaction: initial POST hung up, falling back to polling for txId=${txId}`,
+    );
+  }
+
+  // Poll until status finalizes.
+  const POLL_INTERVAL_MS = 5_000;
+  const POLL_TIMEOUT_MS = 10 * 60_000;
+  const deadline = Date.now() + POLL_TIMEOUT_MS;
+
+  while (Date.now() < deadline) {
+    const tx = await stagingGetTransaction(accessToken, txId);
+    if (tx?.status === 'EXECUTED' && tx?.txHash) {
+      return { txHash: tx.txHash };
+    }
+    if (tx?.status === 'FAILED') {
+      throw new Error(
+        `stagingExecuteTransaction: txId ${txId} ended in FAILED status`,
+      );
+    }
+    await new Promise((r) => setTimeout(r, POLL_INTERVAL_MS));
   }
+
+  throw new Error(
+    `stagingExecuteTransaction: timed out waiting for txId ${txId} to EXECUTE`,
+  );
 }
 
 export async function stagingGetTransaction(accessToken: string, txId: string) {
diff --git a/packages/backend/test/utils/transaction.util.ts b/packages/backend/test/utils/transaction.util.ts
index 2b355662..87e46b04 100644
--- a/packages/backend/test/utils/transaction.util.ts
+++ b/packages/backend/test/utils/transaction.util.ts
@@ -14,6 +14,7 @@ export interface CreateTransactionPayload {
   nonce: number;
   type: TxType;
   accountAddress: `0x${string}`;
+  chainId: number;
   to: `0x${string}`;
   value: string;
   threshold: number;
@@ -55,13 +56,14 @@ export async function apiCreateAccount(
 export async function apiReserveNonce(
   accessToken: string,
   accountAddress: `0x${string}`,
+  chainId: number,
 ) {
   const server = getHttpServer();
 
   const response = await request(server)
     .post(API_ENDPOINTS.transactions.reserveNonce)
     .set(getAuthHeader(accessToken))
-    .send({ accountAddress })
+    .send({ accountAddress, chainId })
     .expect(201);
 
   return response.body as { nonce: number };

From d680272c4722e9b1efc1c70c111da5030513914c Mon Sep 17 00:00:00 2001
From: BoHsuu <huygon764@gmail.com>
Date: Thu, 21 May 2026 16:36:08 +0700
Subject: [PATCH 5/5] feat(stealth): private ETH transfers via Umbra on Base
 mainnet
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Send ETH privately from a PolyPay multisig on Base mainnet through the
Umbra stealth payment protocol. Recipients register their meta-address
once on app.umbra.cash; PolyPay observes the StealthKeyRegistry on
chain to know who can receive. Each send derives a one-time stealth
address client-side and routes through UmbraBatchSend so the on-chain
Announcement event lets the recipient withdraw later via app.umbra.cash.

Sender flow
- StealthToggle in Transfer: gates by chain (Base mainnet), token (ETH
  only) and recipient registration. Shows the live umbra.toll() so
  cosigners see the total cost before approving. Disables "Add to batch"
  when stealth is on — batch flow can't combine with UmbraBatchSend.
- Stealth payload (verbatim to/value/data) lands on the transactions row
  as stealthData. The executor submits it as-is and other voters use it
  to recompute the same txHash for their own ZK approval proof.
- Private badge + tooltip on the transaction row so cosigners understand
  the on-chain call routes through UmbraBatchSend rather than directly
  to the recipient.

Recipient
- No PolyPay backend involvement: app.umbra.cash handles registration.
- Sidebar CTA + ReceivePrivatelyModal: always visible on a Base-mainnet
  account context, switches between violet "Receive privately" and green
  "Private receive ready" depending on the wallet's registry status.
- When the connected wallet matches the recipient of an executed stealth
  tx, the tx row shows a green dot on the recipient pill and an Open
  Umbra button in the expanded detail.

Docs
- New docs/stealth-payments.md covering scope, flows, costs, and what
  PolyPay intentionally does not handle.
- Network support matrix in docs/zkverify-horizen-integration.md so
  per-chain feature differences live in one place.

Schema
- stealth_data TEXT column on transactions (migration
  20260521083753_add_stealth_data).
---
 docs/SUMMARY.md                               |   1 +
 docs/stealth-payments.md                      |  60 ++++++
 docs/zkverify-horizen-integration.md          |  20 ++
 .../migration.sql                             |   2 +
 packages/backend/prisma/schema.prisma         |   1 +
 .../transaction-executor.service.ts           |  19 ++
 .../src/transaction/transaction.service.ts    |  34 ++++
 .../components/Batch/BatchContainer.tsx       |  20 +-
 .../TransactionRow/AddressWithContact.tsx     |  11 +
 .../Dashboard/TransactionRow/TxDetails.tsx    |  36 +++-
 .../Dashboard/TransactionRow/TxHeader.tsx     |  47 ++++-
 .../Dashboard/TransactionRow/utils.ts         |  18 +-
 .../nextjs/components/Sidebar/Sidebar.tsx     |  39 +++-
 .../components/Transfer/StealthToggle.tsx     |  82 ++++++++
 .../components/Transfer/TransferContainer.tsx |  16 +-
 .../nextjs/components/modals/ModalLayout.tsx  |   1 +
 .../modals/ReceivePrivatelyModal.tsx          | 191 ++++++++++++++++++
 packages/nextjs/constants/features.ts         |   3 +
 packages/nextjs/constants/index.ts            |   1 +
 packages/nextjs/hooks/api/useStealthStatus.ts |  54 +++++
 .../app/transaction/useBatchTransaction.ts    |  29 ++-
 .../app/transaction/useTransactionVote.ts     |  18 ++
 .../app/transaction/useTransferTransaction.ts | 104 +++++++---
 packages/nextjs/lib/form/schemas.ts           |   2 +
 packages/nextjs/package.json                  |   2 +
 packages/nextjs/types/modal.ts                |   3 +-
 packages/nextjs/utils/stealth.ts              | 120 +++++++++++
 packages/nextjs/utils/stealthEntries.ts       |  78 +++++++
 packages/shared/src/constants/index.ts        |   1 +
 packages/shared/src/constants/umbra.ts        |  69 +++++++
 .../dto/transaction/create-transaction.dto.ts |   9 +
 packages/shared/src/types/transaction.ts      |   1 +
 yarn.lock                                     | 124 ++++++++----
 33 files changed, 1127 insertions(+), 89 deletions(-)
 create mode 100644 docs/stealth-payments.md
 create mode 100644 packages/backend/prisma/migrations/20260521083753_add_stealth_data/migration.sql
 create mode 100644 packages/nextjs/components/Transfer/StealthToggle.tsx
 create mode 100644 packages/nextjs/components/modals/ReceivePrivatelyModal.tsx
 create mode 100644 packages/nextjs/constants/features.ts
 create mode 100644 packages/nextjs/hooks/api/useStealthStatus.ts
 create mode 100644 packages/nextjs/utils/stealth.ts
 create mode 100644 packages/nextjs/utils/stealthEntries.ts
 create mode 100644 packages/shared/src/constants/umbra.ts

diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md
index 8587ed28..61d735d3 100644
--- a/docs/SUMMARY.md
+++ b/docs/SUMMARY.md
@@ -9,6 +9,7 @@
 - [ZK Authentication](zk-authentication.md)
 - [zkVerify, Horizen & Base Integration](zkverify-horizen-integration.md)
 - [Gasless USDC Deposits (x402)](x402-deposits.md)
+- [Stealth Payments (Umbra)](stealth-payments.md)
 - [PolyPay for AI Agents](llms-txt-for-agents.md)
 - [Architecture](architecture.md)
 - [Developer Documentation](developer-documentation/README.md)
diff --git a/docs/stealth-payments.md b/docs/stealth-payments.md
new file mode 100644
index 00000000..0991944d
--- /dev/null
+++ b/docs/stealth-payments.md
@@ -0,0 +1,60 @@
+# Stealth Payments (Umbra)
+
+PolyPay multisigs on Base mainnet can send **ETH privately** using the [Umbra stealth payment protocol](https://app.umbra.cash/). Each send generates a one-time stealth address on the fly, so there's no on-chain link between the sender's multisig and the recipient's real wallet. The recipient withdraws later via the Umbra app.
+
+## Scope
+
+What's supported today:
+
+- **Single transfer**, **ETH only**, **Base mainnet only**
+- Recipient must be pre-registered on the Umbra `StealthKeyRegistry` (one-time, via [app.umbra.cash](https://app.umbra.cash))
+- Sender uses the standard PolyPay Transfer flow with the "Send privately" toggle enabled
+
+What's intentionally **not** supported:
+
+| Feature | Status | Reason |
+|---|---|---|
+| Batch stealth sends | ❌ | A multisig `execute` targets a single contract per call. The current PolyPay batch flow routes through the multisig's own `batchTransfer`, which can't be combined with `UmbraBatchSend` in a single execute — we chose not to ship the alternative |
+| USDC and other ERC20 stealth | ❌ | `UmbraBatchSend` pulls ERC20 via `safeTransferFrom`, requiring the multisig to first approve `UmbraBatchSend` as spender. We didn't build the one-time approval flow |
+| Base Sepolia / Horizen | ❌ | Umbra protocol is only deployed on Base mainnet (among PolyPay's supported chains) |
+| In-app stealth key registration | ❌ | Recipients register directly via `app.umbra.cash` so PolyPay holds no relayer key for stealth |
+
+## Sender flow
+
+1. Open **Transfer** on a Base-mainnet multisig.
+2. Pick the recipient, enter the ETH amount.
+3. Tick **Send privately (stealth)**. The toggle only appears when the recipient is registered on Umbra; otherwise PolyPay shows a hint asking you to share `app.umbra.cash` with them first. A small line under the toggle displays the current Umbra protocol toll the multisig will pay on top of the amount.
+4. Submit and proceed with the normal multisig voting flow. Cosigners see a **Private** badge on the transaction so they know it routes through Umbra rather than directly to the recipient.
+5. After enough approvals, the transaction executes. If the recipient is also a PolyPay user and has their wallet connected, the transaction row shows them a hint (green dot on the recipient pill + an Open Umbra button in the expanded detail). Otherwise the recipient will need to be told separately to check `app.umbra.cash` — PolyPay does not notify them off-platform.
+
+## Recipient setup (one-time)
+
+Stealth keys are registered on the Umbra `StealthKeyRegistry` once per wallet. PolyPay does not host this flow — recipients use Umbra directly:
+
+1. Sidebar in PolyPay shows a **Receive privately** card whenever the current account is on Base mainnet and a wallet is connected. The card icon and label reflect the wallet's current state:
+   - Not registered yet — violet shield, label "Receive privately"
+   - Already registered — green shield, label "Private receive ready"
+2. Clicking opens a modal that points to [app.umbra.cash](https://app.umbra.cash) and explains the steps. PolyPay does not write to the registry; the recipient signs and submits the registration tx themselves (~$0.01 gas on Base).
+3. After registering, the recipient returns to PolyPay and clicks **I've completed setup**. PolyPay re-reads the registry on chain. The modal switches to a success state showing the wallet address (with a copy button to share with senders), and the sidebar card flips to the green "Private receive ready" state so the user always has a one-click handle to revisit their setup.
+
+## Recipient withdrawal
+
+PolyPay does not implement stealth withdrawal — recipients use Umbra. There are two ways to get to the right place:
+
+- **From PolyPay** — if the connected wallet matches the recipient address of an executed stealth transaction, the transaction row shows a small green dot on the recipient pill. Expanding the row reveals an **Open Umbra ↗** button that opens `app.umbra.cash` directly.
+- **From anywhere else** — just visit [app.umbra.cash](https://app.umbra.cash). PolyPay isn't required to withdraw.
+
+Either way, the flow on Umbra is:
+
+1. Connect the same wallet that was used during setup.
+2. Sign once — Umbra's app scans the `Announcement` events on its contract and finds the payments addressed to you.
+3. Withdraw each payment using whatever options Umbra offers — typically a hosted relayer that covers gas (with a fee taken from the withdrawn amount), or a self-paid withdrawal if you already hold ETH on the stealth address. Refer to Umbra's own docs for current details.
+
+## Cost
+
+| Cost | Paid by | Notes |
+|---|---|---|
+| Stealth payment amount | Multisig | The amount the sender intends the recipient to receive |
+| Umbra protocol toll | Multisig | `umbra.toll()` read live on each propose. The multisig sends `amount + toll` ETH to `UmbraBatchSend`; Umbra keeps the toll, the recipient receives the amount. Currently ~0.00003 ETH on Base |
+| Execute gas | Relayer | PolyPay's relayer wallet covers the on-chain `multisig.execute(...)` gas, same as any other PolyPay transaction |
+| Withdrawal gas (recipient side) | Umbra relayer or recipient | Umbra typically offers a hosted relayer that takes a fee from the withdrawn token, or self-paid withdrawal if the stealth address has ETH. Exact mechanics live on Umbra's side |
\ No newline at end of file
diff --git a/docs/zkverify-horizen-integration.md b/docs/zkverify-horizen-integration.md
index c452a1e2..587e4466 100644
--- a/docs/zkverify-horizen-integration.md
+++ b/docs/zkverify-horizen-integration.md
@@ -10,6 +10,26 @@ PolyPay uses multiple blockchain layers for privacy-preserving multisig operatio
 
 > **"Destination Chain"** refers to the EVM chain where the multisig account is deployed — either **Horizen** (L3, chain ID 26514) or **Base** (L2, chain ID 8453). The user selects the destination chain when creating an account, and all subsequent operations for that account happen on the same chain.
 
+## Network support matrix
+
+Features available per destination chain. The ZK private multisig core works on every supported chain; integrations on top of it are EVM-ecosystem features that only some chains have.
+
+| Feature | Horizen Mainnet | Horizen Testnet | Base Mainnet | Base Sepolia |
+|---|---|---|---|---|
+| ZK private multisig (transfer, batch, signer mgmt, threshold) | ✅ | ✅ | ✅ | ✅ |
+| ETH transfers (native) | ✅ | ✅ | ✅ | ✅ |
+| ZEN transfers (bridged ERC20) | ✅ | ✅ | ✅ | ✅ |
+| USDC transfers (bridged ERC20) | ✅ | ✅ | ✅ | ✅ |
+| Gasless USDC deposit via x402 | — | — | ✅ | ✅ |
+| Stealth payments (Umbra) | — | — | ✅ | — |
+| Native gas token | ETH | ETH | ETH | ETH |
+
+Notes:
+
+- **x402 gasless deposits** ride on EIP-3009 USDC, available on Base where USDC is canonical.
+- **Stealth payments** rely on the Umbra protocol, which (among PolyPay's supported chains) is only deployed on Base mainnet. See [Stealth Payments](stealth-payments.md).
+- All four chains are EVM L2/L3 networks that use ETH for gas — there is no native ZEN gas token on any of them in PolyPay's current deployments.
+
 ## Blockchain Classification
 
 | Action | Blockchain | Description |
diff --git a/packages/backend/prisma/migrations/20260521083753_add_stealth_data/migration.sql b/packages/backend/prisma/migrations/20260521083753_add_stealth_data/migration.sql
new file mode 100644
index 00000000..b61fe43e
--- /dev/null
+++ b/packages/backend/prisma/migrations/20260521083753_add_stealth_data/migration.sql
@@ -0,0 +1,2 @@
+-- AlterTable
+ALTER TABLE "transactions" ADD COLUMN     "stealth_data" TEXT;
diff --git a/packages/backend/prisma/schema.prisma b/packages/backend/prisma/schema.prisma
index 8df45ddf..11d60fde 100644
--- a/packages/backend/prisma/schema.prisma
+++ b/packages/backend/prisma/schema.prisma
@@ -74,6 +74,7 @@ model Transaction {
   signerData     String?   @map("signer_data")
   newThreshold   Int?      @map("new_threshold")
   batchData      String?   @map("batch_data")
+  stealthData    String?   @map("stealth_data")
   createdBy      String    @map("created_by")
   threshold      Int
   txHash         String?   @map("tx_hash")
diff --git a/packages/backend/src/transaction/transaction-executor.service.ts b/packages/backend/src/transaction/transaction-executor.service.ts
index 70a6187d..33337fd5 100644
--- a/packages/backend/src/transaction/transaction-executor.service.ts
+++ b/packages/backend/src/transaction/transaction-executor.service.ts
@@ -425,6 +425,25 @@ export class TransactionExecutorService {
     value: string;
     data: string;
   } {
+    // Stealth transactions ship the exact (to, value, data) the proposer
+    // hashed and proved. Re-deriving it from semantic fields is impossible
+    // (ephemeral entropy is client-side only) and any drift would make the
+    // contract's hash check fail. Always use the stored payload verbatim.
+    if (transaction.stealthData) {
+      try {
+        const parsed = JSON.parse(transaction.stealthData) as {
+          to: string;
+          value: string;
+          data: string;
+        };
+        return { to: parsed.to, value: parsed.value, data: parsed.data };
+      } catch (err) {
+        throw new BadRequestException(
+          `Corrupt stealthData for txId ${transaction.txId}: ${(err as Error).message}`,
+        );
+      }
+    }
+
     switch (transaction.type) {
       case TxType.TRANSFER:
         if (transaction?.tokenAddress) {
diff --git a/packages/backend/src/transaction/transaction.service.ts b/packages/backend/src/transaction/transaction.service.ts
index bb090087..684e5616 100644
--- a/packages/backend/src/transaction/transaction.service.ts
+++ b/packages/backend/src/transaction/transaction.service.ts
@@ -160,6 +160,7 @@ export class TransactionService {
           createdBy: userCommitment,
           status: TxStatus.PENDING,
           batchData,
+          stealthData: dto.stealthData ?? null,
         },
       });
 
@@ -586,6 +587,10 @@ export class TransactionService {
   // ============ Private Methods ============
 
   private validateTransactionDto(dto: CreateTransactionDto) {
+    if (dto.stealthData !== undefined && dto.stealthData !== null) {
+      this.validateStealthData(dto.stealthData);
+    }
+
     switch (dto.type) {
       case TxType.TRANSFER:
         if (!dto.to || !dto.value) {
@@ -643,6 +648,35 @@ export class TransactionService {
     }
   }
 
+  // stealthData is opaque to most of the system but the executor will submit
+  // it verbatim, so reject malformed payloads early. We don't validate the
+  // calldata target against a contract allowlist here because the proposer's
+  // ZK proof already binds (nonce, to, value, data); a wrong target only
+  // wastes the proposer's own gas reservation.
+  private validateStealthData(raw: string) {
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(raw);
+    } catch {
+      throw new BadRequestException('stealthData must be a JSON string');
+    }
+    if (!parsed || typeof parsed !== 'object') {
+      throw new BadRequestException('stealthData must be a JSON object');
+    }
+    const { to, value, data } = parsed as Record<string, unknown>;
+    if (typeof to !== 'string' || !/^0x[a-fA-F0-9]{40}$/.test(to)) {
+      throw new BadRequestException('stealthData.to must be a 0x address');
+    }
+    if (typeof value !== 'string' || !/^[0-9]+$/.test(value)) {
+      throw new BadRequestException(
+        'stealthData.value must be a decimal string',
+      );
+    }
+    if (typeof data !== 'string' || !/^0x[a-fA-F0-9]*$/.test(data)) {
+      throw new BadRequestException('stealthData.data must be hex-encoded');
+    }
+  }
+
   /**
    * Check if transaction should be marked as FAILED
    * Query totalSigners realtime from account.signers
diff --git a/packages/nextjs/components/Batch/BatchContainer.tsx b/packages/nextjs/components/Batch/BatchContainer.tsx
index febcefca..86f91ccc 100644
--- a/packages/nextjs/components/Batch/BatchContainer.tsx
+++ b/packages/nextjs/components/Batch/BatchContainer.tsx
@@ -70,7 +70,15 @@ function BatchTransactions({
   onSelectAll: () => void;
   onSelectItem: (id: string) => void;
   onRemove: (id: string) => void;
-  onEdit: (id: string, data: { recipient: string; amount: string; token: ResolvedToken; contactId?: string }) => void;
+  onEdit: (
+    id: string,
+    data: {
+      recipient: string;
+      amount: string;
+      token: ResolvedToken;
+      contactId?: string;
+    },
+  ) => void;
   isLoading?: boolean;
   isRemoving?: boolean;
   accountId: string | null;
@@ -355,7 +363,15 @@ export default function BatchContainer() {
   );
 
   const handleEdit = useCallback(
-    async (id: string, data: { recipient: string; amount: string; token: ResolvedToken; contactId?: string }) => {
+    async (
+      id: string,
+      data: {
+        recipient: string;
+        amount: string;
+        token: ResolvedToken;
+        contactId?: string;
+      },
+    ) => {
       try {
         const amountInSmallestUnit = parseTokenAmount(data.amount, data.token.decimals);
 
diff --git a/packages/nextjs/components/Dashboard/TransactionRow/AddressWithContact.tsx b/packages/nextjs/components/Dashboard/TransactionRow/AddressWithContact.tsx
index 4a892585..0baff24d 100644
--- a/packages/nextjs/components/Dashboard/TransactionRow/AddressWithContact.tsx
+++ b/packages/nextjs/components/Dashboard/TransactionRow/AddressWithContact.tsx
@@ -5,14 +5,24 @@ export function AddressWithContact({
   address,
   contactName,
   className,
+  showRecipientDot = false,
 }: {
   address: string;
   contactName?: string;
   className?: string;
+  // Renders a small green dot next to the pill — used when the current user
+  // is the stealth recipient of this tx, so they notice they have something
+  // to claim and expand the row for the Umbra link.
+  showRecipientDot?: boolean;
 }) {
+  const dot = showRecipientDot ? (
+    <span className="inline-block w-2 h-2 rounded-full bg-green-500 mr-1.5 align-middle" aria-label="You receive" />
+  ) : null;
+
   if (contactName) {
     return (
       <span className={`text-sm text-main-black bg-grey-100 px-5 py-1 rounded-3xl ${className}`}>
+        {dot}
         <span className="font-medium">{contactName}</span>
         <span className="text-main-black ml-1">({formatAddress(address, { start: 3, end: 3 })})</span>
       </span>
@@ -20,6 +30,7 @@ export function AddressWithContact({
   }
   return (
     <span className={`text-sm text-main-black bg-grey-100 px-5 py-1 rounded-3xl ${className}`}>
+      {dot}
       {formatAddress(address, { start: 3, end: 3 })}
     </span>
   );
diff --git a/packages/nextjs/components/Dashboard/TransactionRow/TxDetails.tsx b/packages/nextjs/components/Dashboard/TransactionRow/TxDetails.tsx
index b6dc64ef..42b783f8 100644
--- a/packages/nextjs/components/Dashboard/TransactionRow/TxDetails.tsx
+++ b/packages/nextjs/components/Dashboard/TransactionRow/TxDetails.tsx
@@ -2,11 +2,23 @@ import React from "react";
 import Image from "next/image";
 import { AddressWithContact } from "./AddressWithContact";
 import { TxType, getTokenByAddress } from "@polypay/shared";
+import { ExternalLink } from "lucide-react";
+import { useAccount } from "wagmi";
+import { Tooltip, TooltipContent, TooltipTrigger } from "~~/components/ui/tooltip";
 import { TransactionRowData, useNetworkTokens } from "~~/hooks";
 import { formatAddress, formatAmount } from "~~/utils/format";
 
+const UMBRA_APP_URL = "https://app.umbra.cash";
+
 export function TxDetails({ tx }: { tx: TransactionRowData }) {
   const { chainId } = useNetworkTokens();
+  const { address: connectedAddress } = useAccount();
+  const isStealthRecipient =
+    !!tx.stealthCall &&
+    !!connectedAddress &&
+    !!tx.recipientAddress &&
+    tx.recipientAddress.toLowerCase() === connectedAddress.toLowerCase();
+
   switch (tx.type) {
     case TxType.TRANSFER:
       return (
@@ -21,7 +33,29 @@ export function TxDetails({ tx }: { tx: TransactionRowData }) {
             <span className="font-medium">{formatAmount(tx.amount ?? "0", chainId, tx.tokenAddress)}</span>
           </div>
           <Image src="/icons/arrows/arrow-right-long-purple.svg" alt="Arrow Right" width={100} height={100} />
-          <AddressWithContact address={tx.recipientAddress ?? ""} contactName={tx.contact?.name} />
+          <AddressWithContact
+            address={tx.recipientAddress ?? ""}
+            contactName={tx.contact?.name}
+            showRecipientDot={isStealthRecipient}
+          />
+          {isStealthRecipient && (
+            <Tooltip>
+              <TooltipTrigger asChild>
+                <a
+                  href={UMBRA_APP_URL}
+                  target="_blank"
+                  rel="noopener noreferrer"
+                  className="inline-flex items-center gap-1 px-2.5 py-1 rounded-full bg-green-100 text-green-800 text-xs font-medium hover:bg-green-200"
+                >
+                  Open Umbra
+                  <ExternalLink className="w-3 h-3" />
+                </a>
+              </TooltipTrigger>
+              <TooltipContent side="top" className="max-w-[260px] bg-grey-1000 text-white">
+                Connect this wallet on app.umbra.cash, sign once to scan, then withdraw your funds.
+              </TooltipContent>
+            </Tooltip>
+          )}
         </div>
       );
 
diff --git a/packages/nextjs/components/Dashboard/TransactionRow/TxHeader.tsx b/packages/nextjs/components/Dashboard/TransactionRow/TxHeader.tsx
index c2f2e2d3..893ad34b 100644
--- a/packages/nextjs/components/Dashboard/TransactionRow/TxHeader.tsx
+++ b/packages/nextjs/components/Dashboard/TransactionRow/TxHeader.tsx
@@ -6,12 +6,36 @@ import { AddressWithContact } from "./AddressWithContact";
 import { getExpandedHeaderText } from "./utils";
 import { TxType, ZERO_ADDRESS, formatTokenAmount, getTokenByAddress } from "@polypay/shared";
 import { Contact } from "@polypay/shared";
+import { Shield } from "lucide-react";
+import { useAccount } from "wagmi";
 import { BatchContactEntry } from "~~/components/modals/CreateBatchFromContactsModal";
 import { modalManager } from "~~/components/modals/ModalLayout";
+import { Tooltip, TooltipContent, TooltipTrigger } from "~~/components/ui/tooltip";
 import { BatchTransfer, TransactionRowData, VoteStatus, useNetworkTokens } from "~~/hooks";
 import { useAccountStore } from "~~/services/store";
 import { formatAddress, formatAmount } from "~~/utils/format";
 
+// Sender-facing badge for stealth transfers. On-chain the call routes
+// through UmbraBatchSend / Umbra, not directly to the displayed recipient
+// — without this marker co-signers might think they're approving a
+// straight transfer.
+function PrivateBadge() {
+  return (
+    <Tooltip>
+      <TooltipTrigger asChild>
+        <span className="inline-flex items-center gap-1 px-2 py-0.5 rounded-full bg-white/20 text-white text-[11px] font-medium cursor-help">
+          <Shield className="w-3 h-3" />
+          Private
+        </span>
+      </TooltipTrigger>
+      <TooltipContent side="top" className="max-w-[280px] bg-grey-1000 text-white">
+        Routed through Umbra. On-chain the call goes to UmbraBatchSend, not directly to the recipient. The recipient
+        withdraws from a one-time stealth address.
+      </TooltipContent>
+    </Tooltip>
+  );
+}
+
 interface TxHeaderProps {
   tx: TransactionRowData;
   myVoteStatus: VoteStatus | null;
@@ -69,6 +93,12 @@ export function TxHeader({
   const shortCommitment = formatAddress(initiatorCommitment, { start: 4, end: 4 });
   const { chainId } = useNetworkTokens();
   const { currentAccount } = useAccountStore();
+  const { address: connectedAddress } = useAccount();
+  const isStealthRecipient =
+    !!tx.stealthCall &&
+    !!connectedAddress &&
+    !!tx.recipientAddress &&
+    tx.recipientAddress.toLowerCase() === connectedAddress.toLowerCase();
 
   const handleDuplicate = () => {
     if (!batchData) return;
@@ -157,7 +187,10 @@ export function TxHeader({
       <div className="bg-violet-300 text-white p-4 rounded-lg">
         {renderHeaderRow()}
         <div className="flex items-center gap-4" key={tx.type}>
-          <span className="mr-10">Tranfer</span>
+          <div className="mr-10 flex items-center gap-2">
+            <span>Tranfer</span>
+            {tx.stealthCall && <PrivateBadge />}
+          </div>
           <Image
             src={getTokenByAddress(tx.tokenAddress, chainId).icon}
             alt={getTokenByAddress(tx.tokenAddress, chainId).symbol}
@@ -166,7 +199,12 @@ export function TxHeader({
           />
           <span>{formatAmount(tx.amount ?? "0", chainId, tx.tokenAddress)}</span>
           <Image src="/icons/arrows/arrow-right-long-white.svg" alt="Arrow Right" width={100} height={100} />
-          <AddressWithContact address={tx.recipientAddress ?? ""} contactName={tx.contact?.name} className="bg-white" />
+          <AddressWithContact
+            address={tx.recipientAddress ?? ""}
+            contactName={tx.contact?.name}
+            className="bg-white"
+            showRecipientDot={isStealthRecipient}
+          />
         </div>
       </div>
     );
@@ -200,6 +238,11 @@ export function TxHeader({
     return (
       <div className="bg-violet-300 text-white p-4 rounded-lg">
         {renderHeaderRow()}
+        {tx.stealthCall && (
+          <div className="mb-2">
+            <PrivateBadge />
+          </div>
+        )}
         <div className="space-y-2 max-h-[200px] overflow-y-auto">
           {tx.batchData.map((transfer, index) => (
             <div className="flex items-center gap-4" key={tx.type + index}>
diff --git a/packages/nextjs/components/Dashboard/TransactionRow/utils.ts b/packages/nextjs/components/Dashboard/TransactionRow/utils.ts
index b2063d34..d3e10605 100644
--- a/packages/nextjs/components/Dashboard/TransactionRow/utils.ts
+++ b/packages/nextjs/components/Dashboard/TransactionRow/utils.ts
@@ -1,5 +1,5 @@
 import { Transaction, TxType, VoteType } from "@polypay/shared";
-import { BatchTransfer, Member, TransactionRowData, VoteStatus } from "~~/hooks";
+import { BatchTransfer, Member, StealthCall, TransactionRowData, VoteStatus } from "~~/hooks";
 
 export function convertToRowData(tx: Transaction, myCommitment: string): TransactionRowData {
   const members: Member[] = tx.votes.map(vote => ({
@@ -27,6 +27,21 @@ export function convertToRowData(tx: Transaction, myCommitment: string): Transac
     }
   }
 
+  let stealthCall: StealthCall | undefined;
+  if (tx.stealthData) {
+    try {
+      const parsed = JSON.parse(tx.stealthData) as StealthCall;
+      // Trust the shape because the backend validated it on create; if it
+      // ever drifts, voters will just see no stealthCall and fall back to
+      // the (broken) semantic rebuild — same result as before this feature.
+      if (parsed && parsed.to && parsed.value && parsed.data) {
+        stealthCall = parsed;
+      }
+    } catch {
+      stealthCall = undefined;
+    }
+  }
+
   return {
     id: tx.id,
     txId: tx.txId,
@@ -41,6 +56,7 @@ export function convertToRowData(tx: Transaction, myCommitment: string): Transac
     oldThreshold: tx.threshold,
     newThreshold: tx.newThreshold || undefined,
     batchData,
+    stealthCall,
     members,
     votedCount: tx.votes.length,
     threshold: tx.threshold,
diff --git a/packages/nextjs/components/Sidebar/Sidebar.tsx b/packages/nextjs/components/Sidebar/Sidebar.tsx
index fa64c303..1228e683 100644
--- a/packages/nextjs/components/Sidebar/Sidebar.tsx
+++ b/packages/nextjs/components/Sidebar/Sidebar.tsx
@@ -6,9 +6,12 @@ import { usePathname, useRouter } from "next/navigation";
 import AccountSidebar from "./AccountSidebar";
 import ManageAccountsSidebar from "./ManageAccountsSidebar";
 import NetworkChooserSidebar from "./NetworkChooserSidebar";
-import { useSwitchChain, useWalletClient } from "wagmi";
+import { isStealthSupportedChain } from "@polypay/shared";
+import { Shield } from "lucide-react";
+import { useAccount, useSwitchChain, useWalletClient } from "wagmi";
 import Routes from "~~/configs/routes.config";
 import { useMyAccounts } from "~~/hooks";
+import { useStealthStatus } from "~~/hooks/api/useStealthStatus";
 import { useModalApp } from "~~/hooks/app/useModalApp";
 import { useAppRouter } from "~~/hooks/app/useRouteApp";
 import { useAccountStore, useIdentityStore, useSidebarStore } from "~~/services/store";
@@ -161,7 +164,18 @@ export default function Sidebar() {
   const { data: accounts = [], isLoading: isLoadingAccounts } = useMyAccounts();
   const { commitment } = useIdentityStore();
   const { data: walletClient } = useWalletClient();
+  const { address: connectedAddress } = useAccount();
   const { currentAccount, setCurrentAccount } = useAccountStore();
+  // Stealth onboarding only makes sense when the user is operating in a
+  // Base-mainnet account context. Showing it while they're working on a
+  // Horizen multisig would be noise — they'd have to switch accounts to
+  // use the feature anyway. We keep the CTA visible after registration too
+  // so users have a one-click handle to confirm/share their setup; the
+  // shared modal already renders both setup and success states.
+  const isStealthChainContext = !!currentAccount?.chainId && isStealthSupportedChain(currentAccount.chainId);
+  const stealthStatus = useStealthStatus(isStealthChainContext && connectedAddress ? connectedAddress : null);
+  const showStealthPrompt = isStealthChainContext && !!connectedAddress && stealthStatus.isFetched;
+  const isStealthRegistered = stealthStatus.data?.registered === true;
   const { switchChainAsync } = useSwitchChain();
   const {
     isManageAccountsOpen,
@@ -270,6 +284,29 @@ export default function Sidebar() {
 
         {/* Bottom Section */}
         <div className="flex flex-col gap-2.5">
+          {/* Stealth-receive CTA — green icon + "ready" label once registered,
+              so the user has a one-click handle to confirm/share their setup. */}
+          {showStealthPrompt && (
+            <div
+              className="h-[36px] flex items-center gap-[5px] px-2.5 py-1.5 bg-main-white rounded-lg cursor-pointer hover:bg-grey-50"
+              onClick={() => openModal("receivePrivately")}
+            >
+              <div className="w-5 h-5 flex items-center justify-center">
+                <Shield className={`h-4 w-4 ${isStealthRegistered ? "text-green-600" : "text-main-violet"}`} />
+              </div>
+              <span className="xl:block hidden flex-1 text-sm font-medium text-grey-700">
+                {isStealthRegistered ? "Private receive ready" : "Receive privately"}
+              </span>
+              <Image
+                src="/icons/arrows/arrow-right-purple.svg"
+                alt="Arrow"
+                width={16}
+                height={16}
+                className="xl:block hidden"
+              />
+            </div>
+          )}
+
           {/* Request new feature */}
           {commitment && (
             <div
diff --git a/packages/nextjs/components/Transfer/StealthToggle.tsx b/packages/nextjs/components/Transfer/StealthToggle.tsx
new file mode 100644
index 00000000..774ba209
--- /dev/null
+++ b/packages/nextjs/components/Transfer/StealthToggle.tsx
@@ -0,0 +1,82 @@
+"use client";
+
+import { isStealthSupportedChain, isStealthSupportedToken } from "@polypay/shared";
+import { useQuery } from "@tanstack/react-query";
+import { formatEther } from "viem";
+import { useStealthStatus } from "~~/hooks/api/useStealthStatus";
+import { getUmbraToll } from "~~/utils/stealth";
+
+const STEALTH_RPC_URL = "https://base-rpc.publicnode.com";
+
+function useUmbraToll(chainId: number | undefined) {
+  return useQuery({
+    queryKey: ["umbra", "toll", chainId],
+    queryFn: () => getUmbraToll(chainId!, STEALTH_RPC_URL),
+    enabled: !!chainId && isStealthSupportedChain(chainId),
+    staleTime: 5 * 60_000,
+  });
+}
+
+interface StealthToggleProps {
+  checked: boolean;
+  onChange: (next: boolean) => void;
+  chainId: number | undefined;
+  tokenAddress: string | undefined;
+  recipientAddress: string | undefined;
+  disabled?: boolean;
+}
+
+// Shared UI for the "Send privately" toggle. Same component drives the
+// single-transfer and batch-edit flows so disable/hint logic stays in one place.
+export function StealthToggle({
+  checked,
+  onChange,
+  chainId,
+  tokenAddress,
+  recipientAddress,
+  disabled = false,
+}: StealthToggleProps) {
+  const chainOk = !!chainId && isStealthSupportedChain(chainId);
+  const tokenOk = chainOk && !!tokenAddress && isStealthSupportedToken(chainId!, tokenAddress);
+
+  const status = useStealthStatus(chainOk && tokenOk && recipientAddress ? recipientAddress : undefined);
+  const recipientOk = status.data?.registered === true;
+  const tollQuery = useUmbraToll(chainOk ? chainId : undefined);
+  const tollText = tollQuery.data && tollQuery.data > 0n ? `${formatEther(tollQuery.data)} ETH` : null;
+
+  // Hide entirely when the feature flag is off OR the current chain/token
+  // can't use Umbra. There's no value in showing a dangling option for ZEN
+  // or non-Base chains — users would just see noise. Hooks above are
+  // called unconditionally to satisfy React's rules-of-hooks.
+  if (!chainOk || !tokenOk) return null;
+
+  let hint: string | null = null;
+  if (!recipientAddress) hint = null;
+  else if (status.isLoading) hint = "Checking recipient setup…";
+  else if (!recipientOk) hint = "Recipient has not registered. Ask them to set up at app.umbra.cash.";
+
+  const inputDisabled = disabled || !recipientOk;
+
+  return (
+    <div className="flex flex-col gap-1">
+      <label className="flex items-center gap-2 cursor-pointer select-none">
+        <input
+          type="checkbox"
+          checked={checked && !inputDisabled}
+          onChange={e => onChange(e.target.checked)}
+          disabled={inputDisabled}
+          className="h-4 w-4 accent-main-violet disabled:opacity-50"
+        />
+        <span className={`text-sm font-medium ${inputDisabled ? "text-grey-400" : "text-grey-800"}`}>
+          Send privately (stealth)
+        </span>
+      </label>
+      {hint && <span className="text-xs text-grey-500 pl-6">{hint}</span>}
+      {tollText && !hint && (
+        <span className="text-xs text-grey-500 pl-6">
+          Umbra protocol toll: {tollText} per recipient, paid from your multisig.
+        </span>
+      )}
+    </div>
+  );
+}
diff --git a/packages/nextjs/components/Transfer/TransferContainer.tsx b/packages/nextjs/components/Transfer/TransferContainer.tsx
index 24c291f0..1751742e 100644
--- a/packages/nextjs/components/Transfer/TransferContainer.tsx
+++ b/packages/nextjs/components/Transfer/TransferContainer.tsx
@@ -4,6 +4,7 @@ import React, { useEffect, useState } from "react";
 import Image from "next/image";
 import { ResolvedToken, parseTokenAmount } from "@polypay/shared";
 import { parseEther } from "viem";
+import { StealthToggle } from "~~/components/Transfer/StealthToggle";
 import { ContactPicker } from "~~/components/contact-book/ContactPicker";
 import { TokenPillPopover } from "~~/components/popovers/TokenPillPopover";
 import { Spinner } from "~~/components/ui/Spinner";
@@ -85,6 +86,7 @@ export default function TransferContainer() {
       amount: data.amount,
       token: selectedToken,
       contactId: selectedContactId,
+      sendPrivately: data.sendPrivately,
     });
   };
 
@@ -265,6 +267,17 @@ export default function TransferContainer() {
           {form.formState.errors.recipient && (
             <p className="text-red-500 text-sm">{form.formState.errors.recipient.message}</p>
           )}
+
+          <div className="w-full mt-3">
+            <StealthToggle
+              checked={!!form.watch("sendPrivately")}
+              onChange={next => form.setValue("sendPrivately", next, { shouldValidate: false })}
+              chainId={selectedAccount?.chainId}
+              tokenAddress={selectedToken.address}
+              recipientAddress={watchedRecipient || undefined}
+              disabled={isLoading}
+            />
+          </div>
         </div>
 
         {/* Action buttons */}
@@ -284,7 +297,8 @@ export default function TransferContainer() {
         <div className="flex gap-2 items-center justify-center w-full max-w-xs">
           <button
             onClick={handleAddToBatch}
-            disabled={!canSubmit}
+            disabled={!canSubmit || !!form.watch("sendPrivately")}
+            title={form.watch("sendPrivately") ? "Stealth send doesn't support batch — propose directly" : undefined}
             className="bg-main-black flex items-center justify-center gap-2 px-3 py-2 rounded-[10px] disabled:opacity-50 cursor-pointer border-0 flex-1 transition-colors"
           >
             {isLoading && <Spinner />}
diff --git a/packages/nextjs/components/modals/ModalLayout.tsx b/packages/nextjs/components/modals/ModalLayout.tsx
index b756cfa2..cc9c9f52 100644
--- a/packages/nextjs/components/modals/ModalLayout.tsx
+++ b/packages/nextjs/components/modals/ModalLayout.tsx
@@ -58,6 +58,7 @@ const modals: ModalRegistry = {
   createBatchFromContacts: dynamic(() => import("./CreateBatchFromContactsModal"), { ssr: false }),
   depositX402: dynamic(() => import("./DepositModal"), { ssr: false }),
   receiveMethod: dynamic(() => import("./ReceiveMethodModal"), { ssr: false }),
+  receivePrivately: dynamic(() => import("./ReceivePrivatelyModal"), { ssr: false }),
 };
 
 type ModalInstance = {
diff --git a/packages/nextjs/components/modals/ReceivePrivatelyModal.tsx b/packages/nextjs/components/modals/ReceivePrivatelyModal.tsx
new file mode 100644
index 00000000..35c1b8d2
--- /dev/null
+++ b/packages/nextjs/components/modals/ReceivePrivatelyModal.tsx
@@ -0,0 +1,191 @@
+"use client";
+
+import React, { useState } from "react";
+import ModalContainer from "./ModalContainer";
+import { useQueryClient } from "@tanstack/react-query";
+import { Check, Copy, ExternalLink, Shield, X } from "lucide-react";
+import { useAccount } from "wagmi";
+import { Button } from "~~/components/ui/button";
+import { stealthKeys, useStealthStatus } from "~~/hooks/api/useStealthStatus";
+import { ModalProps } from "~~/types/modal";
+import { copyToClipboard } from "~~/utils/copy";
+import { formatAddress } from "~~/utils/format";
+import { notification } from "~~/utils/scaffold-eth";
+
+const UMBRA_SETUP_URL = "https://app.umbra.cash";
+
+// We point users to app.umbra.cash for stealth key registration instead of
+// hosting our own onboarding flow. PolyPay only observes the registry on
+// chain and unlocks stealth sends once the recipient has registered.
+const ReceivePrivatelyModal: React.FC<ModalProps> = ({ isOpen, onClose }) => {
+  const { address } = useAccount();
+  const queryClient = useQueryClient();
+  const stealthStatus = useStealthStatus(address ?? null);
+  const [isRechecking, setIsRechecking] = useState(false);
+
+  const isRegistered = stealthStatus.data?.registered === true;
+
+  const handleRecheck = async () => {
+    if (!address) return;
+    setIsRechecking(true);
+    try {
+      await queryClient.invalidateQueries({ queryKey: stealthKeys.status(address.toLowerCase()) });
+      const fresh = await queryClient.fetchQuery({ queryKey: stealthKeys.status(address.toLowerCase()) });
+      if (!(fresh as { registered?: boolean })?.registered) {
+        notification.info("Not registered yet. Complete setup on Umbra and try again.");
+      }
+      // If registered, the component will re-render into the success state.
+    } finally {
+      setIsRechecking(false);
+    }
+  };
+
+  const handleCopy = () => {
+    if (!address) return;
+    copyToClipboard(address, "Address copied");
+  };
+
+  return (
+    <ModalContainer
+      isOpen={isOpen}
+      onClose={onClose}
+      isCloseButton={false}
+      className="bg-white rounded-3xl w-[min(480px,92vw)] p-0 shadow-modal overflow-hidden"
+    >
+      <div className="flex flex-col">
+        {/* Header */}
+        <div className="flex items-center justify-between px-5 pt-5 pb-3">
+          <div className="flex items-center gap-2">
+            <Shield className="w-5 h-5 text-main-violet" />
+            <span className="text-grey-1000 text-base font-semibold">Receive privately</span>
+          </div>
+          <button
+            type="button"
+            onClick={onClose}
+            className="w-9 h-9 flex items-center justify-center rounded-lg border border-grey-200 hover:bg-grey-50 cursor-pointer"
+            aria-label="Close"
+          >
+            <X className="w-4 h-4 text-grey-1000" />
+          </button>
+        </div>
+
+        {isRegistered ? (
+          /* ---- Success state ---- */
+          <>
+            <div className="flex flex-col items-center gap-4 px-5 pt-2 pb-6">
+              <div className="w-16 h-16 rounded-full bg-green-500 flex items-center justify-center">
+                <Check className="w-9 h-9 text-white" strokeWidth={3} />
+              </div>
+              <h3 className="text-grey-1000 text-2xl font-semibold uppercase tracking-tight">You&apos;re all set</h3>
+              <p className="text-sm text-grey-600 text-center max-w-[320px]">
+                This wallet can receive private payments. Share your wallet address with senders.
+              </p>
+              {address && (
+                <div className="w-full mt-2 flex items-center gap-2">
+                  <div className="flex-1 px-3 py-2.5 rounded-xl bg-grey-50 border border-grey-100 text-sm font-mono text-grey-900 break-all">
+                    {address}
+                  </div>
+                  <button
+                    type="button"
+                    onClick={handleCopy}
+                    className="w-10 h-10 flex items-center justify-center rounded-xl border border-grey-200 hover:bg-grey-50 cursor-pointer shrink-0"
+                    aria-label="Copy address"
+                  >
+                    <Copy className="w-4 h-4 text-grey-1000" />
+                  </button>
+                </div>
+              )}
+            </div>
+
+            <div className="flex gap-3 px-5 py-4 border-t border-grey-100">
+              <Button
+                type="button"
+                onClick={onClose}
+                className="flex-1 h-11 bg-main-pink hover:bg-pink-550 text-grey-1000 rounded-xl cursor-pointer"
+              >
+                Done
+              </Button>
+            </div>
+          </>
+        ) : (
+          /* ---- Setup state ---- */
+          <>
+            <div className="flex flex-col items-center gap-4 px-5 pt-2 pb-5">
+              <div className="w-16 h-16 rounded-full bg-violet-100 flex items-center justify-center">
+                <Shield className="w-8 h-8 text-main-violet" />
+              </div>
+              <div className="text-center">
+                <h3 className="text-grey-1000 text-lg font-semibold">Set up your wallet on Umbra</h3>
+                <p className="text-sm text-grey-600 mt-1">One-time setup on Base mainnet (~$0.01 gas)</p>
+              </div>
+
+              {/* Steps card */}
+              <div className="w-full rounded-2xl bg-grey-50 border border-grey-100 p-4 flex flex-col gap-2.5">
+                <StepRow num={1} text="Open app.umbra.cash" />
+                <StepRow num={2} text="Connect this same wallet on Base mainnet" />
+                <StepRow num={3} text="Follow Umbra's setup flow to publish your stealth keys" />
+                <StepRow num={4} text={`Return here and click "I've completed setup"`} />
+              </div>
+
+              {/* Wallet to register */}
+              {address && (
+                <div className="w-full">
+                  <span className="block text-xs text-grey-600 mb-1.5">Wallet to register</span>
+                  <div className="flex items-center gap-2">
+                    <div className="flex-1 px-3 py-2.5 rounded-xl bg-grey-50 border border-grey-100 text-sm font-mono text-grey-900">
+                      {formatAddress(address, { start: 10, end: 8 })}
+                    </div>
+                    <button
+                      type="button"
+                      onClick={handleCopy}
+                      className="w-10 h-10 flex items-center justify-center rounded-xl border border-grey-200 hover:bg-grey-50 cursor-pointer shrink-0"
+                      aria-label="Copy address"
+                    >
+                      <Copy className="w-4 h-4 text-grey-1000" />
+                    </button>
+                  </div>
+                </div>
+              )}
+            </div>
+
+            <div className="flex gap-3 px-5 py-4 border-t border-grey-100">
+              <a
+                href={UMBRA_SETUP_URL}
+                target="_blank"
+                rel="noopener noreferrer"
+                className="flex-1 h-11 inline-flex items-center justify-center gap-2 bg-main-pink hover:bg-pink-550 text-grey-1000 rounded-xl cursor-pointer text-sm font-medium"
+              >
+                Open app.umbra.cash
+                <ExternalLink className="w-4 h-4" />
+              </a>
+              <Button
+                type="button"
+                onClick={handleRecheck}
+                disabled={isRechecking || !address}
+                className="flex-1 h-11 bg-white hover:bg-grey-50 text-grey-1000 border border-grey-200 rounded-xl cursor-pointer disabled:opacity-50"
+              >
+                {isRechecking ? "Checking…" : "I've completed setup"}
+              </Button>
+            </div>
+          </>
+        )}
+      </div>
+    </ModalContainer>
+  );
+};
+
+interface StepRowProps {
+  num: number;
+  text: string;
+}
+
+const StepRow: React.FC<StepRowProps> = ({ num, text }) => (
+  <div className="flex items-start gap-3">
+    <div className="w-6 h-6 rounded-full bg-main-violet text-white text-xs font-semibold flex items-center justify-center shrink-0 mt-0.5">
+      {num}
+    </div>
+    <span className="text-sm text-grey-900 leading-6">{text}</span>
+  </div>
+);
+
+export default ReceivePrivatelyModal;
diff --git a/packages/nextjs/constants/features.ts b/packages/nextjs/constants/features.ts
new file mode 100644
index 00000000..fe0d1608
--- /dev/null
+++ b/packages/nextjs/constants/features.ts
@@ -0,0 +1,3 @@
+// Centralized feature flag readers. Keep one source of truth so we don't
+// scatter `process.env.NEXT_PUBLIC_*` checks across the codebase.
+export const X402_DEPOSIT_ENABLED = process.env.NEXT_PUBLIC_FEATURE_X402_DEPOSIT === "true";
diff --git a/packages/nextjs/constants/index.ts b/packages/nextjs/constants/index.ts
index 2ce70976..27f14e21 100644
--- a/packages/nextjs/constants/index.ts
+++ b/packages/nextjs/constants/index.ts
@@ -1 +1,2 @@
 export const API_BASE_URL = process.env.NEXT_PUBLIC_API_URL || "http://localhost:4000";
+export * from "./features";
diff --git a/packages/nextjs/hooks/api/useStealthStatus.ts b/packages/nextjs/hooks/api/useStealthStatus.ts
new file mode 100644
index 00000000..ce0108e2
--- /dev/null
+++ b/packages/nextjs/hooks/api/useStealthStatus.ts
@@ -0,0 +1,54 @@
+import { STEALTH_KEY_REGISTRY_ABI, getUmbraAddresses, isStealthSupportedChain } from "@polypay/shared";
+import { useQuery } from "@tanstack/react-query";
+import { type Address, createPublicClient, http } from "viem";
+import { base } from "viem/chains";
+
+// Stealth registry only exists on Base mainnet. We read it directly from
+// chain — there's no PolyPay backend involvement in recipient onboarding:
+// recipients register via app.umbra.cash and we just observe the result.
+const STEALTH_CHAIN_ID = 8453;
+
+// Same RPC override scaffold.config.ts uses — public mainnet.base.org rejects
+// browser-origin requests.
+const STEALTH_RPC_URL = "https://base-rpc.publicnode.com";
+
+const client = createPublicClient({ chain: base, transport: http(STEALTH_RPC_URL) });
+
+export const stealthKeys = {
+  all: ["stealth"] as const,
+  status: (walletAddress: string) => [...stealthKeys.all, "status", walletAddress.toLowerCase()] as const,
+};
+
+export interface StealthStatus {
+  walletAddress: string;
+  registered: boolean;
+}
+
+async function fetchStealthStatus(walletAddress: string): Promise<StealthStatus> {
+  if (!isStealthSupportedChain(STEALTH_CHAIN_ID)) {
+    return { walletAddress, registered: false };
+  }
+  const { registry } = getUmbraAddresses(STEALTH_CHAIN_ID);
+  const [, spendingPubKey, , viewingPubKey] = (await client.readContract({
+    address: registry as Address,
+    abi: STEALTH_KEY_REGISTRY_ABI,
+    functionName: "stealthKeys",
+    args: [walletAddress as Address],
+  })) as readonly [bigint, bigint, bigint, bigint];
+
+  return {
+    walletAddress,
+    registered: spendingPubKey !== 0n && viewingPubKey !== 0n,
+  };
+}
+
+export function useStealthStatus(walletAddress: string | undefined | null) {
+  const normalized = walletAddress?.toLowerCase() ?? "";
+
+  return useQuery({
+    queryKey: stealthKeys.status(normalized),
+    queryFn: () => fetchStealthStatus(normalized),
+    enabled: !!normalized && /^0x[a-fA-F0-9]{40}$/.test(normalized),
+    staleTime: 60_000,
+  });
+}
diff --git a/packages/nextjs/hooks/app/transaction/useBatchTransaction.ts b/packages/nextjs/hooks/app/transaction/useBatchTransaction.ts
index cee8b71d..0cd97943 100644
--- a/packages/nextjs/hooks/app/transaction/useBatchTransaction.ts
+++ b/packages/nextjs/hooks/app/transaction/useBatchTransaction.ts
@@ -1,4 +1,3 @@
-import { useState } from "react";
 import { createTransactionSteps } from "./transactionSteps";
 import { BatchItem, TxType, ZERO_ADDRESS, encodeBatchTransfer, encodeBatchTransferMulti } from "@polypay/shared";
 import { useWalletClient } from "wagmi";
@@ -35,7 +34,6 @@ export const useBatchTransaction = (options?: UseBatchTransactionOptions) => {
       return;
     }
 
-    // Validate wallet connection
     if (!walletClient || !metaMultiSigWallet) {
       notification.error("Wallet not connected");
       return;
@@ -56,34 +54,35 @@ export const useBatchTransaction = (options?: UseBatchTransactionOptions) => {
         chainId: currentAccount!.chainId,
       });
 
-      // 2. Get current threshold and commitments
+      // 2. Get current threshold
       const currentThreshold = await metaMultiSigWallet.read.signaturesRequired();
 
-      // 3. Prepare batch data
+      // 3. Build (to, value, data)
       const recipients = selectedBatchItems.map(item => item.recipient as `0x${string}`);
       const amounts: bigint[] = selectedBatchItems.map(item => BigInt(item.amount));
       const tokenAddresses = selectedBatchItems.map(item => item.tokenAddress || ZERO_ADDRESS);
 
-      // Check if any ERC20 token in batch
       const hasERC20 = tokenAddresses.some(addr => addr !== ZERO_ADDRESS);
-
-      // 4. Encode function call based on token types
       const batchTransferData = hasERC20
         ? encodeBatchTransferMulti(recipients, amounts, tokenAddresses)
         : encodeBatchTransfer(recipients, amounts);
 
-      // 5. Calculate txHash (to = wallet itself, value = 0, data = batchTransfer call)
+      const toAddress = metaMultiSigWallet.address;
+      const txValue = 0n;
+      const txData = batchTransferData as `0x${string}`;
+
+      // 4. Calculate txHash
       const txHash = (await metaMultiSigWallet.read.getTransactionHash([
         BigInt(nonce),
-        metaMultiSigWallet.address,
-        0n,
-        batchTransferData,
+        toAddress,
+        txValue,
+        txData,
       ])) as `0x${string}`;
 
-      // 6. Generate ZK proof
+      // 5. Generate ZK proof
       const { proof, publicInputs, nullifier, vk } = await generateProof(txHash);
 
-      // 7. Submit to backend
+      // 6. Submit to backend
       startStep(4);
       const result = await createTransaction({
         nonce,
@@ -91,8 +90,8 @@ export const useBatchTransaction = (options?: UseBatchTransactionOptions) => {
         accountAddress: metaMultiSigWallet.address,
         chainId: currentAccount!.chainId,
         threshold: Number(currentThreshold),
-        to: metaMultiSigWallet.address,
-        value: "0",
+        to: toAddress,
+        value: txValue.toString(),
         proof: Array.from(proof),
         publicInputs,
         nullifier: nullifier.toString(),
diff --git a/packages/nextjs/hooks/app/transaction/useTransactionVote.ts b/packages/nextjs/hooks/app/transaction/useTransactionVote.ts
index 1cbfebca..f85cd6df 100644
--- a/packages/nextjs/hooks/app/transaction/useTransactionVote.ts
+++ b/packages/nextjs/hooks/app/transaction/useTransactionVote.ts
@@ -45,6 +45,12 @@ export interface BatchTransfer {
   tokenAddress?: string;
 }
 
+export interface StealthCall {
+  to: `0x${string}`;
+  value: string;
+  data: `0x${string}`;
+}
+
 export interface TransactionRowData {
   id: string;
   txId: number;
@@ -59,6 +65,7 @@ export interface TransactionRowData {
   oldThreshold?: number;
   newThreshold?: number;
   batchData?: BatchTransfer[];
+  stealthCall?: StealthCall;
   contact?: {
     id: string;
     name: string;
@@ -80,6 +87,17 @@ function buildTransactionParams(tx: TransactionRowData): {
   value: bigint;
   callData: `0x${string}`;
 } {
+  // Stealth transactions ship the verbatim (to, value, data) the proposer
+  // executed on chain. Voters must compute the same hash to generate valid
+  // proofs, so always prefer stealthCall when present.
+  if (tx.stealthCall) {
+    return {
+      to: tx.stealthCall.to,
+      value: BigInt(tx.stealthCall.value),
+      callData: tx.stealthCall.data,
+    };
+  }
+
   let callData: `0x${string}` = "0x";
   let to: `0x${string}` = tx.recipientAddress as `0x${string}`;
   let value = BigInt(tx.amount || "0");
diff --git a/packages/nextjs/hooks/app/transaction/useTransferTransaction.ts b/packages/nextjs/hooks/app/transaction/useTransferTransaction.ts
index d94700e0..66ddaff5 100644
--- a/packages/nextjs/hooks/app/transaction/useTransferTransaction.ts
+++ b/packages/nextjs/hooks/app/transaction/useTransferTransaction.ts
@@ -1,6 +1,14 @@
 import { useEffect } from "react";
 import { createTransactionSteps } from "./transactionSteps";
-import { ResolvedToken, TxType, ZERO_ADDRESS, encodeERC20Transfer, parseTokenAmount } from "@polypay/shared";
+import {
+  ResolvedToken,
+  TxType,
+  ZERO_ADDRESS,
+  encodeERC20Transfer,
+  isStealthSupportedChain,
+  isStealthSupportedToken,
+  parseTokenAmount,
+} from "@polypay/shared";
 import { parseEther } from "viem";
 import { useWalletClient } from "wagmi";
 import { useMetaMultiSigWallet } from "~~/hooks";
@@ -10,14 +18,21 @@ import { useStepLoading } from "~~/hooks/app/useStepLoading";
 import { useAccountStore } from "~~/services/store";
 import { formatErrorMessage } from "~~/utils/formatError";
 import { notification } from "~~/utils/scaffold-eth";
+import { buildStealthBatchCall, getUmbraToll } from "~~/utils/stealth";
+import { deriveStealthEntries } from "~~/utils/stealthEntries";
 
 interface TransferParams {
   recipient: string;
   amount: string;
   token: ResolvedToken;
   contactId?: string | null;
+  sendPrivately?: boolean;
 }
 
+// Public mainnet.base.org rejects browser-origin requests (403). Use the
+// same Base RPC override the rest of the app relies on (scaffold.config.ts).
+const DEFAULT_BASE_RPC_URL = "https://base-rpc.publicnode.com";
+
 interface UseTransferTransactionOptions {
   onSuccess?: () => void;
 }
@@ -36,13 +51,26 @@ export const useTransferTransaction = (options?: UseTransferTransactionOptions)
     onLoadingStateChange: setStepByLabel,
   });
 
-  const transfer = async ({ recipient, amount, token, contactId }: TransferParams) => {
+  const transfer = async ({ recipient, amount, token, contactId, sendPrivately }: TransferParams) => {
     if (!walletClient || !metaMultiSigWallet) {
       notification.error("Wallet not connected");
       return;
     }
 
     const isNativeETH = token.address === ZERO_ADDRESS;
+    const chainId = currentAccount?.chainId;
+
+    if (sendPrivately) {
+      if (!chainId || !isStealthSupportedChain(chainId)) {
+        notification.error("Stealth payments are only available on Base mainnet");
+        return;
+      }
+      if (!isStealthSupportedToken(chainId, token.address)) {
+        notification.error("Stealth payments support only ETH and USDC");
+        return;
+      }
+    }
+
     try {
       // 1. Reserve nonce from backend
       startStep(1);
@@ -59,32 +87,57 @@ export const useTransferTransaction = (options?: UseTransferTransactionOptions)
         ? parseEther(amount).toString()
         : parseTokenAmount(amount, token.decimals);
 
-      // 4. Calculate txHash (different for ETH vs ERC20)
-      let txHash: `0x${string}`;
-
-      if (isNativeETH) {
-        // ETH: to = recipient, value = amount, data = 0x
-        txHash = (await metaMultiSigWallet.read.getTransactionHash([
-          BigInt(nonce),
-          recipient as `0x${string}`,
-          BigInt(valueInSmallestUnit),
-          "0x" as `0x${string}`,
-        ])) as `0x${string}`;
+      // 4. Build (to, value, data) — stealth path replaces the recipient with a
+      //    fresh stealth address and routes through Umbra's batch contract so a
+      //    proper Announcement event is emitted.
+      let toAddress: `0x${string}`;
+      let txValue: bigint;
+      let txData: `0x${string}`;
+      let stealthData: string | undefined;
+
+      if (sendPrivately) {
+        const [{ entry }] = await deriveStealthEntries(chainId!, DEFAULT_BASE_RPC_URL, [
+          {
+            recipient,
+            tokenAddress: token.address,
+            amount: BigInt(valueInSmallestUnit),
+          },
+        ]);
+        const toll = await getUmbraToll(chainId!, DEFAULT_BASE_RPC_URL);
+        const built = buildStealthBatchCall(chainId!, toll, [entry]);
+        toAddress = built.to as `0x${string}`;
+        txValue = built.value;
+        txData = built.data as `0x${string}`;
+        // Persist the exact on-chain call so the executor and any approver
+        // can recompute the same txHash without needing the ephemeral entropy.
+        stealthData = JSON.stringify({
+          to: toAddress,
+          value: txValue.toString(),
+          data: txData,
+        });
+      } else if (isNativeETH) {
+        toAddress = recipient as `0x${string}`;
+        txValue = BigInt(valueInSmallestUnit);
+        txData = "0x";
       } else {
-        // ERC20: to = tokenAddress, value = 0, data = transfer(recipient, amount)
-        const encodedData = encodeERC20Transfer(recipient, BigInt(valueInSmallestUnit));
-        txHash = (await metaMultiSigWallet.read.getTransactionHash([
-          BigInt(nonce),
-          token.address as `0x${string}`,
-          0n,
-          encodedData as `0x${string}`,
-        ])) as `0x${string}`;
+        toAddress = token.address as `0x${string}`;
+        txValue = 0n;
+        txData = encodeERC20Transfer(recipient, BigInt(valueInSmallestUnit)) as `0x${string}`;
       }
 
+      const txHash = (await metaMultiSigWallet.read.getTransactionHash([
+        BigInt(nonce),
+        toAddress,
+        txValue,
+        txData,
+      ])) as `0x${string}`;
+
       // 5. Generate ZK proof
       const { proof, publicInputs, nullifier, vk } = await generateProof(txHash);
 
-      // 6. Submit to backend
+      // 6. Submit to backend. For stealth, we record the ORIGINAL recipient and
+      //    token in the transaction row (so the UI keeps showing "Alice / USDC"),
+      //    and pass stealthData so the executor knows to call UmbraBatchSend.
       startStep(4);
       const result = await createTransaction({
         nonce,
@@ -101,10 +154,15 @@ export const useTransferTransaction = (options?: UseTransferTransactionOptions)
         nullifier: nullifier.toString(),
         userAddress: walletClient.account.address,
         vk,
+        stealthData,
       });
 
       if (result) {
-        notification.success("Transfer transaction created! Waiting for approvals.");
+        notification.success(
+          sendPrivately
+            ? "Private transfer created. Waiting for approvals."
+            : "Transfer transaction created! Waiting for approvals.",
+        );
       }
 
       options?.onSuccess?.();
diff --git a/packages/nextjs/lib/form/schemas.ts b/packages/nextjs/lib/form/schemas.ts
index 6501d25b..bf37fede 100644
--- a/packages/nextjs/lib/form/schemas.ts
+++ b/packages/nextjs/lib/form/schemas.ts
@@ -41,6 +41,8 @@ export const transferSchema = z.object({
       message: "Invalid address format",
     }),
   amount: z.string(),
+  // Transient UI flag for stealth send (Transfer page only). Not persisted.
+  sendPrivately: z.boolean().optional(),
 });
 export type TransferFormData = z.infer<typeof transferSchema>;
 
diff --git a/packages/nextjs/package.json b/packages/nextjs/package.json
index 7d219964..c02d2143 100644
--- a/packages/nextjs/package.json
+++ b/packages/nextjs/package.json
@@ -30,6 +30,7 @@
     "@radix-ui/react-tooltip": "^1.2.8",
     "@rainbow-me/rainbowkit": "2.2.7",
     "@tanstack/react-query": "~5.59.15",
+    "@umbracash/umbra-js": "^0.2.2",
     "@uniswap/sdk-core": "~5.8.2",
     "@uniswap/v2-sdk": "~4.6.1",
     "axios": "^1.13.2",
@@ -39,6 +40,7 @@
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
     "daisyui": "5.0.9",
+    "ethers": "^5.7.2",
     "kubo-rpc-client": "~5.0.2",
     "lucide-react": "^0.556.0",
     "motion": "^12.23.12",
diff --git a/packages/nextjs/types/modal.ts b/packages/nextjs/types/modal.ts
index 3cc0ed25..78c517d2 100644
--- a/packages/nextjs/types/modal.ts
+++ b/packages/nextjs/types/modal.ts
@@ -34,4 +34,5 @@ export type ModalName =
   // | "questIntro"
   | "createBatchFromContacts"
   | "depositX402"
-  | "receiveMethod";
+  | "receiveMethod"
+  | "receivePrivately";
diff --git a/packages/nextjs/utils/stealth.ts b/packages/nextjs/utils/stealth.ts
new file mode 100644
index 00000000..37a4866d
--- /dev/null
+++ b/packages/nextjs/utils/stealth.ts
@@ -0,0 +1,120 @@
+import { UMBRA_ETH_PLACEHOLDER, ZERO_ADDRESS, getUmbraAddresses, isStealthSupportedChain } from "@polypay/shared";
+import { type Address, type Hex, createPublicClient, encodeFunctionData, http } from "viem";
+import { base } from "viem/chains";
+
+// Single entry in UmbraBatchSend.batchSend. Matches the on-chain tuple layout.
+export interface StealthBatchEntry {
+  receiver: Address;
+  tokenAddr: Address;
+  amount: bigint;
+  pkx: Hex; // 32 bytes
+  ciphertext: Hex; // 32 bytes
+}
+
+// UmbraBatchSend reverts with NotSorted() if any entry's tokenAddr is less
+// than the previous distinct one. The contract only enforces tokenAddr non-
+// decreasing — within a token, order is free. We also break ties by receiver
+// to keep ordering deterministic across retries.
+export function sortStealthEntries(entries: StealthBatchEntry[]): StealthBatchEntry[] {
+  return [...entries].sort((a, b) => {
+    const tokenCompare = a.tokenAddr.toLowerCase().localeCompare(b.tokenAddr.toLowerCase());
+    if (tokenCompare !== 0) return tokenCompare;
+    return a.receiver.toLowerCase().localeCompare(b.receiver.toLowerCase());
+  });
+}
+
+const UMBRA_BATCH_SEND_ABI = [
+  {
+    name: "batchSend",
+    type: "function",
+    stateMutability: "payable",
+    inputs: [
+      { name: "_tollCommitment", type: "uint256" },
+      {
+        name: "_data",
+        type: "tuple[]",
+        components: [
+          { name: "receiver", type: "address" },
+          { name: "tokenAddr", type: "address" },
+          { name: "amount", type: "uint256" },
+          { name: "pkx", type: "bytes32" },
+          { name: "ciphertext", type: "bytes32" },
+        ],
+      },
+    ],
+    outputs: [],
+  },
+] as const;
+
+export interface BuiltStealthCall {
+  to: Address;
+  value: bigint;
+  data: Hex;
+}
+
+// Convert PolyPay's "ZERO_ADDRESS means native ETH" convention to Umbra's
+// own placeholder. Token addresses are unchanged otherwise.
+export function toUmbraTokenAddress(tokenAddress: string): Address {
+  if (tokenAddress.toLowerCase() === ZERO_ADDRESS.toLowerCase()) {
+    return UMBRA_ETH_PLACEHOLDER as Address;
+  }
+  return tokenAddress as Address;
+}
+
+const UMBRA_TOLL_ABI = [
+  {
+    name: "toll",
+    type: "function",
+    stateMutability: "view",
+    inputs: [],
+    outputs: [{ name: "", type: "uint256" }],
+  },
+] as const;
+
+// umbra.sendEth/sendToken require _tollCommitment to equal the on-chain toll
+// exactly. Toll is 0 on Base today but ScopeLift can flip it on, and a stale
+// hardcoded value would brick stealth sends silently. Read it at propose time.
+export async function getUmbraToll(chainId: number, rpcUrl: string): Promise<bigint> {
+  const { umbra } = getUmbraAddresses(chainId);
+  const client = createPublicClient({ chain: base, transport: http(rpcUrl) });
+  return (await client.readContract({
+    address: umbra as Address,
+    abi: UMBRA_TOLL_ABI,
+    functionName: "toll",
+  })) as bigint;
+}
+
+export function buildStealthBatchCall(chainId: number, toll: bigint, entries: StealthBatchEntry[]): BuiltStealthCall {
+  if (!isStealthSupportedChain(chainId)) {
+    throw new Error(`Stealth not supported on chain ${chainId}`);
+  }
+  if (entries.length === 0) {
+    throw new Error("buildStealthBatchCall: empty entries");
+  }
+
+  const sorted = sortStealthEntries(entries);
+
+  // Per UmbraBatchSend source: every entry forwards `_tollCommitment` as ETH
+  // to the inner umbra.sendEth/sendToken call, and ETH entries additionally
+  // forward their `amount`. The contract enforces that msg.value is consumed
+  // exactly (TooMuchEthSent). So msg.value = sum(eth_amounts) + N * toll.
+  let ethTotal = BigInt(sorted.length) * toll;
+  for (const entry of sorted) {
+    if (entry.tokenAddr.toLowerCase() === UMBRA_ETH_PLACEHOLDER.toLowerCase()) {
+      ethTotal += entry.amount;
+    }
+  }
+
+  const data = encodeFunctionData({
+    abi: UMBRA_BATCH_SEND_ABI,
+    functionName: "batchSend",
+    args: [toll, sorted],
+  });
+
+  const { batchSend } = getUmbraAddresses(chainId);
+  return {
+    to: batchSend as Address,
+    value: ethTotal,
+    data,
+  };
+}
diff --git a/packages/nextjs/utils/stealthEntries.ts b/packages/nextjs/utils/stealthEntries.ts
new file mode 100644
index 00000000..8d9f879f
--- /dev/null
+++ b/packages/nextjs/utils/stealthEntries.ts
@@ -0,0 +1,78 @@
+import { type StealthBatchEntry, toUmbraTokenAddress } from "./stealth";
+import { isStealthSupportedChain } from "@polypay/shared";
+import { KeyPair, RandomNumber, Umbra } from "@umbracash/umbra-js";
+import { providers } from "ethers";
+import type { Address, Hex } from "viem";
+
+// The Umbra SDK constructor eagerly builds an internal fallback provider
+// from `process.env.BASE_RPC_URL`. Without this, in the browser it resolves
+// to literal "undefined" and spams 404s. The fallback is only used by
+// withdraw flows we never trigger, but silencing the noise keeps dev logs
+// clean. Setting at module load is fine — the SDK reads it lazily at
+// constructor time.
+if (typeof process !== "undefined" && process.env && !process.env.BASE_RPC_URL) {
+  (process.env as Record<string, string>).BASE_RPC_URL = "https://base-rpc.publicnode.com";
+}
+
+export interface StealthRecipientInput {
+  recipient: string; // wallet address of recipient (NOT stealth)
+  tokenAddress: string; // PolyPay convention (ZERO_ADDRESS for ETH)
+  amount: bigint;
+}
+
+interface DerivedStealthOutput {
+  entry: StealthBatchEntry;
+  stealthAddress: Address;
+}
+
+// For each (recipient wallet, amount, token), this:
+//  1. Looks up the recipient's meta-address on the Umbra StealthKeyRegistry.
+//  2. Generates fresh ephemeral entropy.
+//  3. Derives a one-time stealth address from the recipient's spending key.
+//  4. Encrypts the entropy with the recipient's viewing key so they can scan.
+//
+// Result is a list of UmbraBatchSend entries ready to be encoded into a
+// single multisig.execute call.
+export async function deriveStealthEntries(
+  chainId: number,
+  rpcUrl: string,
+  inputs: StealthRecipientInput[],
+): Promise<DerivedStealthOutput[]> {
+  if (!isStealthSupportedChain(chainId)) {
+    throw new Error(`Stealth not supported on chain ${chainId}`);
+  }
+  if (inputs.length === 0) return [];
+
+  const provider = new providers.JsonRpcProvider(rpcUrl, chainId);
+  const umbra = new Umbra(provider, chainId);
+
+  const outputs: DerivedStealthOutput[] = [];
+
+  for (const input of inputs) {
+    // Pull recipient's registered keys. The SDK throws if unregistered —
+    // callers should pre-check via /api/stealth/status before reaching here.
+    const recipientId = input.recipient;
+    const stealthMeta = await (
+      umbra as unknown as {
+        prepareSend: (recipientId: string) => Promise<{
+          stealthKeyPair: KeyPair;
+          pubKeyXCoordinate: Hex;
+          encrypted: { ciphertext: Hex };
+          randomNumber: RandomNumber;
+        }>;
+      }
+    ).prepareSend(recipientId);
+
+    const entry: StealthBatchEntry = {
+      receiver: stealthMeta.stealthKeyPair.address as Address,
+      tokenAddr: toUmbraTokenAddress(input.tokenAddress),
+      amount: input.amount,
+      pkx: stealthMeta.pubKeyXCoordinate,
+      ciphertext: stealthMeta.encrypted.ciphertext,
+    };
+
+    outputs.push({ entry, stealthAddress: entry.receiver });
+  }
+
+  return outputs;
+}
diff --git a/packages/shared/src/constants/index.ts b/packages/shared/src/constants/index.ts
index c63b2893..c851d472 100644
--- a/packages/shared/src/constants/index.ts
+++ b/packages/shared/src/constants/index.ts
@@ -3,3 +3,4 @@ export * from "./room";
 export * from "./token";
 export * from "./campaign";
 export * from "./contract";
+export * from "./umbra";
diff --git a/packages/shared/src/constants/umbra.ts b/packages/shared/src/constants/umbra.ts
new file mode 100644
index 00000000..79d46cd5
--- /dev/null
+++ b/packages/shared/src/constants/umbra.ts
@@ -0,0 +1,69 @@
+import { ZERO_ADDRESS } from "./token";
+
+// Umbra uses this placeholder to represent native ETH in its contract calls
+// and Announcement events. Keep separate from ZERO_ADDRESS, which PolyPay's
+// own token registry uses for native ETH.
+export const UMBRA_ETH_PLACEHOLDER =
+  "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE";
+
+const BASE_MAINNET = 8453;
+
+export const UMBRA_ADDRESSES: Record<
+  number,
+  { umbra: string; registry: string; batchSend: string }
+> = {
+  [BASE_MAINNET]: {
+    umbra: "0xFb2dc580Eed955B528407b4d36FfaFe3da685401",
+    registry: "0x31fe56609C65Cd0C510E7125f051D440424D38f3",
+    batchSend: "0xDbD0f5EBAdA6632Dde7d47713ea200a7C2ff91EB",
+  },
+};
+
+// Tokens supported by stealth payments on Base mainnet.
+// Only native ETH for now — ERC20s require a separate one-time multisig
+// proposal to approve UmbraBatchSend, which we've intentionally not built
+// out to keep the flow zero-setup.
+export const UMBRA_SUPPORTED_TOKENS: Record<number, readonly string[]> = {
+  [BASE_MAINNET]: [ZERO_ADDRESS],
+};
+
+export const UMBRA_RELAYER_BASE_URL = "https://mainnet.api.umbra.cash";
+
+export function isStealthSupportedChain(chainId: number): boolean {
+  return UMBRA_ADDRESSES[chainId] !== undefined;
+}
+
+export function isStealthSupportedToken(
+  chainId: number,
+  tokenAddress: string,
+): boolean {
+  const tokens = UMBRA_SUPPORTED_TOKENS[chainId];
+  if (!tokens) return false;
+  const lower = tokenAddress.toLowerCase();
+  return tokens.some((t) => t.toLowerCase() === lower);
+}
+
+export function getUmbraAddresses(chainId: number) {
+  const addrs = UMBRA_ADDRESSES[chainId];
+  if (!addrs) {
+    throw new Error(`Umbra not deployed on chain ${chainId}`);
+  }
+  return addrs;
+}
+
+// Minimal ABI for client-side registry reads (status checks).
+// Recipients register via app.umbra.cash directly; PolyPay never writes.
+export const STEALTH_KEY_REGISTRY_ABI = [
+  {
+    name: "stealthKeys",
+    type: "function",
+    stateMutability: "view",
+    inputs: [{ name: "registrant", type: "address" }],
+    outputs: [
+      { name: "spendingPubKeyPrefix", type: "uint256" },
+      { name: "spendingPubKey", type: "uint256" },
+      { name: "viewingPubKeyPrefix", type: "uint256" },
+      { name: "viewingPubKey", type: "uint256" },
+    ],
+  },
+] as const;
diff --git a/packages/shared/src/dto/transaction/create-transaction.dto.ts b/packages/shared/src/dto/transaction/create-transaction.dto.ts
index 4c44a460..7a94261b 100644
--- a/packages/shared/src/dto/transaction/create-transaction.dto.ts
+++ b/packages/shared/src/dto/transaction/create-transaction.dto.ts
@@ -85,6 +85,15 @@ export class CreateTransactionDto {
   @IsString({ each: true })
   batchItemIds?: string[];
 
+  // STEALTH: JSON string of { to, value, data } to execute as-is. Used when the
+  // semantic fields above (recipient/token/value/batchData) describe what the
+  // user intends but the on-chain call routes through UmbraBatchSend with
+  // a derived stealth address. Backend validates shape on create.
+  @IsOptional()
+  @IsString()
+  @MaxLength(65536)
+  stealthData?: string;
+
   // Proof data
   @IsNotEmpty()
   @IsArray()
diff --git a/packages/shared/src/types/transaction.ts b/packages/shared/src/types/transaction.ts
index b0eaecc2..d17dd144 100644
--- a/packages/shared/src/types/transaction.ts
+++ b/packages/shared/src/types/transaction.ts
@@ -22,6 +22,7 @@ export interface Transaction {
   signerData?: SignerData[] | null;
   newThreshold?: number;
   batchData?: string;
+  stealthData?: string;
   createdBy: string;
   threshold: number;
   txHash?: string;
diff --git a/yarn.lock b/yarn.lock
index ee89301f..ed3f2d21 100644
--- a/yarn.lock
+++ b/yarn.lock
@@ -1209,7 +1209,7 @@ __metadata:
   languageName: node
   linkType: hard
 
-"@ethersproject/abi@npm:5.8.0, @ethersproject/abi@npm:^5.0.9, @ethersproject/abi@npm:^5.1.2, @ethersproject/abi@npm:^5.7.0, @ethersproject/abi@npm:^5.8.0":
+"@ethersproject/abi@npm:5.8.0, @ethersproject/abi@npm:^5.0.1, @ethersproject/abi@npm:^5.0.9, @ethersproject/abi@npm:^5.1.2, @ethersproject/abi@npm:^5.7.0, @ethersproject/abi@npm:^5.8.0":
   version: 5.8.0
   resolution: "@ethersproject/abi@npm:5.8.0"
   dependencies:
@@ -4264,7 +4264,7 @@ __metadata:
   languageName: node
   linkType: hard
 
-"@noble/secp256k1@npm:~1.7.0":
+"@noble/secp256k1@npm:^1.7.1, @noble/secp256k1@npm:~1.7.0":
   version: 1.7.2
   resolution: "@noble/secp256k1@npm:1.7.2"
   checksum: 34c80b862996e215b9abb4faa53c30155bbf4338bfb973218f91139fd882dbeff01dde63de3745485664aee539621c13e11fc4ee55c87a462a30e414db6459fc
@@ -5024,6 +5024,7 @@ __metadata:
     "@types/node": ~18.19.50
     "@types/react": ~19.0.7
     "@types/react-dom": latest
+    "@umbracash/umbra-js": ^0.2.2
     "@uniswap/sdk-core": ~5.8.2
     "@uniswap/v2-sdk": ~4.6.1
     abitype: 1.0.6
@@ -5040,6 +5041,7 @@ __metadata:
     eslint-config-next: ~15.2.3
     eslint-config-prettier: ~10.1.1
     eslint-plugin-prettier: ~5.2.4
+    ethers: ^5.7.2
     kubo-rpc-client: ~5.0.2
     lucide-react: ^0.556.0
     motion: ^12.23.12
@@ -8293,6 +8295,17 @@ __metadata:
   languageName: node
   linkType: hard
 
+"@umbracash/umbra-js@npm:^0.2.2":
+  version: 0.2.2
+  resolution: "@umbracash/umbra-js@npm:0.2.2"
+  dependencies:
+    "@noble/secp256k1": ^1.7.1
+    "@unstoppabledomains/resolution": 8.5.0
+    ethers: 5.7.2
+  checksum: 22dcccb1bfff722b6251fc209e95d89c9f11addb0e5e009d172e712d6659cdaea6fdd4593ff851faa9e710e270b49d7b117e0866f1fddae1c3507ecca5e5906d
+  languageName: node
+  linkType: hard
+
 "@ungap/structured-clone@npm:^1.3.0":
   version: 1.3.0
   resolution: "@ungap/structured-clone@npm:1.3.0"
@@ -8482,6 +8495,19 @@ __metadata:
   languageName: node
   linkType: hard
 
+"@unstoppabledomains/resolution@npm:8.5.0":
+  version: 8.5.0
+  resolution: "@unstoppabledomains/resolution@npm:8.5.0"
+  dependencies:
+    "@ethersproject/abi": ^5.0.1
+    bn.js: ^4.4.0
+    cross-fetch: ^3.1.4
+    crypto-js: ^4.1.1
+    elliptic: ^6.5.4
+  checksum: 3deaae15c0ff9699a30306a5c2a4ff09a5fc9bd9f2c4e9ab22621e85bad7109cff5bfe8bebe2f334cf7b76e602e25b9af659a4d5f5dab44738b41a0b60d8d608
+  languageName: node
+  linkType: hard
+
 "@vanilla-extract/css@npm:1.17.3":
   version: 1.17.3
   resolution: "@vanilla-extract/css@npm:1.17.3"
@@ -10560,6 +10586,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"bn.js@npm:^4.4.0":
+  version: 4.12.3
+  resolution: "bn.js@npm:4.12.3"
+  checksum: 0fb6455c6d56e3869589ad736cc2f5ed2b6229daa1af43e93bd373eb5e20bf0ae25b166087189bce9ba3b3f4d971e1b9a12ec6027e52eb182e5535e1494cadbb
+  languageName: node
+  linkType: hard
+
 "bn.js@npm:^5.1.2, bn.js@npm:^5.2.0, bn.js@npm:^5.2.1":
   version: 5.2.2
   resolution: "bn.js@npm:5.2.2"
@@ -11988,6 +12021,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"crypto-js@npm:^4.1.1":
+  version: 4.2.0
+  resolution: "crypto-js@npm:4.2.0"
+  checksum: f051666dbc077c8324777f44fbd3aaea2986f198fe85092535130d17026c7c2ccf2d23ee5b29b36f7a4a07312db2fae23c9094b644cc35f7858b1b4fcaf27774
+  languageName: node
+  linkType: hard
+
 "css-what@npm:^6.1.0":
   version: 6.2.2
   resolution: "css-what@npm:6.2.2"
@@ -12573,7 +12613,7 @@ __metadata:
   languageName: node
   linkType: hard
 
-"elliptic@npm:6.6.1, elliptic@npm:^6.5.2, elliptic@npm:^6.5.7":
+"elliptic@npm:6.6.1, elliptic@npm:^6.5.2, elliptic@npm:^6.5.4, elliptic@npm:^6.5.7":
   version: 6.6.1
   resolution: "elliptic@npm:6.6.1"
   dependencies:
@@ -13850,45 +13890,7 @@ __metadata:
   languageName: node
   linkType: hard
 
-"ethers@npm:^5.5.1, ethers@npm:^5.7.0":
-  version: 5.8.0
-  resolution: "ethers@npm:5.8.0"
-  dependencies:
-    "@ethersproject/abi": 5.8.0
-    "@ethersproject/abstract-provider": 5.8.0
-    "@ethersproject/abstract-signer": 5.8.0
-    "@ethersproject/address": 5.8.0
-    "@ethersproject/base64": 5.8.0
-    "@ethersproject/basex": 5.8.0
-    "@ethersproject/bignumber": 5.8.0
-    "@ethersproject/bytes": 5.8.0
-    "@ethersproject/constants": 5.8.0
-    "@ethersproject/contracts": 5.8.0
-    "@ethersproject/hash": 5.8.0
-    "@ethersproject/hdnode": 5.8.0
-    "@ethersproject/json-wallets": 5.8.0
-    "@ethersproject/keccak256": 5.8.0
-    "@ethersproject/logger": 5.8.0
-    "@ethersproject/networks": 5.8.0
-    "@ethersproject/pbkdf2": 5.8.0
-    "@ethersproject/properties": 5.8.0
-    "@ethersproject/providers": 5.8.0
-    "@ethersproject/random": 5.8.0
-    "@ethersproject/rlp": 5.8.0
-    "@ethersproject/sha2": 5.8.0
-    "@ethersproject/signing-key": 5.8.0
-    "@ethersproject/solidity": 5.8.0
-    "@ethersproject/strings": 5.8.0
-    "@ethersproject/transactions": 5.8.0
-    "@ethersproject/units": 5.8.0
-    "@ethersproject/wallet": 5.8.0
-    "@ethersproject/web": 5.8.0
-    "@ethersproject/wordlists": 5.8.0
-  checksum: fb107bf28dc3aedde4729f9553be066c699e0636346c095b4deeb5349a0c0c8538f48a58b5c8cbefced008706919739c5f7b8f4dd506bb471a31edee18cda228
-  languageName: node
-  linkType: hard
-
-"ethers@npm:~5.7.0":
+"ethers@npm:5.7.2, ethers@npm:~5.7.0":
   version: 5.7.2
   resolution: "ethers@npm:5.7.2"
   dependencies:
@@ -13926,6 +13928,44 @@ __metadata:
   languageName: node
   linkType: hard
 
+"ethers@npm:^5.5.1, ethers@npm:^5.7.0, ethers@npm:^5.7.2":
+  version: 5.8.0
+  resolution: "ethers@npm:5.8.0"
+  dependencies:
+    "@ethersproject/abi": 5.8.0
+    "@ethersproject/abstract-provider": 5.8.0
+    "@ethersproject/abstract-signer": 5.8.0
+    "@ethersproject/address": 5.8.0
+    "@ethersproject/base64": 5.8.0
+    "@ethersproject/basex": 5.8.0
+    "@ethersproject/bignumber": 5.8.0
+    "@ethersproject/bytes": 5.8.0
+    "@ethersproject/constants": 5.8.0
+    "@ethersproject/contracts": 5.8.0
+    "@ethersproject/hash": 5.8.0
+    "@ethersproject/hdnode": 5.8.0
+    "@ethersproject/json-wallets": 5.8.0
+    "@ethersproject/keccak256": 5.8.0
+    "@ethersproject/logger": 5.8.0
+    "@ethersproject/networks": 5.8.0
+    "@ethersproject/pbkdf2": 5.8.0
+    "@ethersproject/properties": 5.8.0
+    "@ethersproject/providers": 5.8.0
+    "@ethersproject/random": 5.8.0
+    "@ethersproject/rlp": 5.8.0
+    "@ethersproject/sha2": 5.8.0
+    "@ethersproject/signing-key": 5.8.0
+    "@ethersproject/solidity": 5.8.0
+    "@ethersproject/strings": 5.8.0
+    "@ethersproject/transactions": 5.8.0
+    "@ethersproject/units": 5.8.0
+    "@ethersproject/wallet": 5.8.0
+    "@ethersproject/web": 5.8.0
+    "@ethersproject/wordlists": 5.8.0
+  checksum: fb107bf28dc3aedde4729f9553be066c699e0636346c095b4deeb5349a0c0c8538f48a58b5c8cbefced008706919739c5f7b8f4dd506bb471a31edee18cda228
+  languageName: node
+  linkType: hard
+
 "ethers@npm:~6.13.2":
   version: 6.13.7
   resolution: "ethers@npm:6.13.7"