From d40d186b95f0560fefcac59224b64e298505e330 Mon Sep 17 00:00:00 2001 From: Mateo Sauton <39073982+mateosauton@users.noreply.github.com> Date: Wed, 19 Aug 2026 19:07:34 -0300 Subject: [PATCH 1/7] add YC World ID guide --- cspell.json | 2 + .../2026-08-19-yc-world-id-guide-design.md | 37 +++++ world-id/yc.mdx | 130 ++++++++++++++++++ 3 files changed, 169 insertions(+) create mode 100644 docs/superpowers/specs/2026-08-19-yc-world-id-guide-design.md create mode 100644 world-id/yc.mdx diff --git a/cspell.json b/cspell.json index 2b2ace0..15dbf92 100644 --- a/cspell.json +++ b/cspell.json @@ -46,6 +46,7 @@ "Ethereum", "ethersproject", "fdir", + "frontmatter", "fintech", "gatekept", "getenv", @@ -173,6 +174,7 @@ "virality", "vuni", "wagmi", + "waitlist", "walletauth", "wcsep", "webview", diff --git a/docs/superpowers/specs/2026-08-19-yc-world-id-guide-design.md b/docs/superpowers/specs/2026-08-19-yc-world-id-guide-design.md new file mode 100644 index 0000000..961b6f6 --- /dev/null +++ b/docs/superpowers/specs/2026-08-19-yc-world-id-guide-design.md @@ -0,0 +1,37 @@ +# World ID for YC Startups: Design + +## Goal + +Create a direct-link-only page for YC founders that explains the simplest safe path to add World ID, with familiar startup use cases and clear links to the full reference documentation. + +## Location and visibility + +- Add `world-id/yc.mdx`, served at `/world-id/yc`. +- Set `hidden: true` in frontmatter and do not add it to `docs.json` navigation. +- The page remains reachable by its direct URL but is not promoted in navigation or indexed. + +## Content + +1. Frame World ID as a privacy-preserving proof that one unique human is taking an action. +2. Help founders decide when to use it: anti-bot signup, referral and reward abuse, one-person allocations or votes, and community or marketplace trust. +3. Describe the shortest production flow without duplicating the full implementation guide: + - Create an app, RP, and action in the Developer Portal. + - Add the IDKit React widget using the Proof of Human flow. + - Generate the RP signature only on the backend. + - Forward the result unchanged to the World ID verification endpoint from the backend. + - Store the returned nullifier with a uniqueness constraint. +4. Include a small, actionable React outline and link to the existing integration guide for complete code. +5. Add short use-case examples for AI consumer products, marketplaces, rewards and referrals, communities, and crypto. +6. Close with optional next steps for stronger or broader trust signals: user presence and liveness, Identity Check, and AgentKit. + +## Constraints + +- Use only current IDKit 4.x terminology and the current Developer Portal flow. +- Do not include secret material or client-side signing guidance. +- Keep the page focused on Proof of Human; the other products are follow-on links, not parallel tutorials. +- Reuse existing internal documentation links wherever detailed integration material exists. + +## Validation + +- Run the repository spellcheck and broken-link checks. +- Confirm the new page is not listed in `docs.json` and has `hidden: true` frontmatter. diff --git a/world-id/yc.mdx b/world-id/yc.mdx new file mode 100644 index 0000000..108ccd1 --- /dev/null +++ b/world-id/yc.mdx @@ -0,0 +1,130 @@ +--- +title: "World ID for YC Startups" +description: "The simplest way to add proof of human to your startup." +hidden: true +hideFooterPagination: true +--- + +World ID lets your app verify that a real, unique human is behind an action—without collecting the person's identity or biometric data. + +For most startups, the simplest place to start is **Proof of Human**: require one proof before a user creates an account, claims a reward, or takes another high-value action. + +## Use World ID when one person should get one chance + +World ID is a strong fit when duplicate accounts, bots, or impersonation can change the outcome: + +| If you're building... | Use World ID to... | +| --- | --- | +| An AI consumer product | Protect free trials, credits, referrals, and limited-access features from bot abuse. | +| A marketplace or community | Make reviews, reputation, applications, and participation harder to manipulate. | +| A rewards or growth loop | Give each person one reward, invite bonus, waitlist spot, or vote. | +| A crypto product | Support fair claims, allocations, grants, governance, or incentive programs. | +| A product with high-stakes actions | Establish a clear human approval boundary before an agent or automated system acts. | + + + World ID proves a unique human, not a person's legal identity. Start with Proof of Human for anti-Sybil protection; add an identity credential later only when your product needs an eligibility attribute such as age or nationality. + + +## The simplest production path + +### 1. Create your app and action + +In the [Developer Portal](https://developer.world.org), create an app, register a World ID relying party (RP), and create an action such as `verify-account` or `claim-referral-reward`. + +`app_id` and `rp_id` are public identifiers and can be included where the SDK needs them. Keep the RP signing key secret and on the server: + +- RP signing key + + + Never expose the RP signing key in browser code or a `NEXT_PUBLIC_` environment variable. It authenticates proof requests from your app. + + +### 2. Add the React widget + +Install the React SDK: + +```bash +npm i @worldcoin/idkit +``` + +Request an RP context from a server endpoint, then open the [IDKit React widget](/world-id/idkit/react). The outline below requests the current Proof of Human credential and sends the result to your backend for verification and authorization. + +```tsx +import { useState } from "react"; +import { + IDKitRequestWidget, + proofOfHuman, + type RpContext, +} from "@worldcoin/idkit"; + +export function VerifyAccount({ + accountId, + rpContext, +}: { + accountId: string; + rpContext: RpContext; +}) { + const [open, setOpen] = useState(false); + + return ( + <> + + { + const response = await fetch("/api/verify-proof", { + method: "POST", + headers: { "content-type": "application/json" }, + body: JSON.stringify({ + idkitResponse, + }), + }); + + if (!response.ok) throw new Error("Verification failed"); + }} + onSuccess={() => { + // Refresh client UI only. The backend authorized the protected operation. + }} + /> + + ); +} +``` + +For a staging test, use the [World ID Simulator](https://simulator.worldcoin.org/) and a staging action. Use a production action and `environment="production"` for real users. + +### 3. Verify on your backend and store the nullifier + +Your backend must: + +1. From the authenticated server session, select an allowed action and derive the expected account context and signal. Do not accept these authorization inputs from the browser. +2. Generate the `rp_context` with the RP signing key. See [RP signatures](/world-id/idkit/signatures). +3. Forward the IDKit result **unchanged** to the verification endpoint constructed with the trusted, server-configured RP ID: `POST https://developer.world.org/api/v4/verify/{rp_id}`. Do not accept an RP ID from the browser. See [backend verification](/world-id/idkit/integrate#step-5-verify-the-proof-in-your-backend). +4. Validate that the verified proof matches the server-selected action and expected account context/signal, then store the `(action, nullifier)` pair with a database uniqueness constraint. Reject a duplicate insert so the same person cannot repeat the action. Grant the protected operation only after every check succeeds. See [nullifier storage](/world-id/idkit/integrate#step-6-store-the-nullifier). + + + The nullifier is a per-app, per-action identifier. It prevents repeat use while remaining unlinkable across other apps and actions. + + +## Start with one high-value moment + +Avoid gating every click. Choose the point where abuse is expensive—for example, account creation, a free-credit claim, a referral reward, a vote, or a marketplace listing—and require Proof of Human there first. + +After that works, add World ID to other high-value actions with separate actions and nullifier records. + +## Add more trust only when you need it + +- Need a fresh human-presence check for a sensitive action? Review [user presence and liveness](/world-id/idkit/credentials#user-presence-and-liveness). +- Need an eligibility signal such as age, nationality, or document type? Review [Identity Check](/world-id/idkit/credentials#identity-check-preview). +- Building an agentic product? Use [AgentKit](/agents/agent-kit/integrate) after defining the human approval point. + +## Build the complete integration + +This page is the fast path. Follow the [full IDKit integration guide](/world-id/idkit/integrate) for server-side signatures, complete SDK examples, testing, and production rollout details. From d0673d356b6f0db240bb65992be39e2d3b69f407 Mon Sep 17 00:00:00 2001 From: Mateo Sauton <39073982+mateosauton@users.noreply.github.com> Date: Wed, 19 Aug 2026 19:38:58 -0300 Subject: [PATCH 2/7] remove YC guide design file --- cspell.json | 1 - .../2026-08-19-yc-world-id-guide-design.md | 37 ------------------- 2 files changed, 38 deletions(-) delete mode 100644 docs/superpowers/specs/2026-08-19-yc-world-id-guide-design.md diff --git a/cspell.json b/cspell.json index 15dbf92..f9fb8be 100644 --- a/cspell.json +++ b/cspell.json @@ -46,7 +46,6 @@ "Ethereum", "ethersproject", "fdir", - "frontmatter", "fintech", "gatekept", "getenv", diff --git a/docs/superpowers/specs/2026-08-19-yc-world-id-guide-design.md b/docs/superpowers/specs/2026-08-19-yc-world-id-guide-design.md deleted file mode 100644 index 961b6f6..0000000 --- a/docs/superpowers/specs/2026-08-19-yc-world-id-guide-design.md +++ /dev/null @@ -1,37 +0,0 @@ -# World ID for YC Startups: Design - -## Goal - -Create a direct-link-only page for YC founders that explains the simplest safe path to add World ID, with familiar startup use cases and clear links to the full reference documentation. - -## Location and visibility - -- Add `world-id/yc.mdx`, served at `/world-id/yc`. -- Set `hidden: true` in frontmatter and do not add it to `docs.json` navigation. -- The page remains reachable by its direct URL but is not promoted in navigation or indexed. - -## Content - -1. Frame World ID as a privacy-preserving proof that one unique human is taking an action. -2. Help founders decide when to use it: anti-bot signup, referral and reward abuse, one-person allocations or votes, and community or marketplace trust. -3. Describe the shortest production flow without duplicating the full implementation guide: - - Create an app, RP, and action in the Developer Portal. - - Add the IDKit React widget using the Proof of Human flow. - - Generate the RP signature only on the backend. - - Forward the result unchanged to the World ID verification endpoint from the backend. - - Store the returned nullifier with a uniqueness constraint. -4. Include a small, actionable React outline and link to the existing integration guide for complete code. -5. Add short use-case examples for AI consumer products, marketplaces, rewards and referrals, communities, and crypto. -6. Close with optional next steps for stronger or broader trust signals: user presence and liveness, Identity Check, and AgentKit. - -## Constraints - -- Use only current IDKit 4.x terminology and the current Developer Portal flow. -- Do not include secret material or client-side signing guidance. -- Keep the page focused on Proof of Human; the other products are follow-on links, not parallel tutorials. -- Reuse existing internal documentation links wherever detailed integration material exists. - -## Validation - -- Run the repository spellcheck and broken-link checks. -- Confirm the new page is not listed in `docs.json` and has `hidden: true` frontmatter. From 87b26877c59321cba1a8cba56cb23f3cdcfe3581 Mon Sep 17 00:00:00 2001 From: Mateo Sauton <39073982+mateosauton@users.noreply.github.com> Date: Wed, 19 Aug 2026 20:52:44 -0300 Subject: [PATCH 3/7] simplify YC World ID guide --- cspell.json | 1 - world-id/yc.mdx | 153 ++++++++++++------------------------------------ 2 files changed, 37 insertions(+), 117 deletions(-) diff --git a/cspell.json b/cspell.json index f9fb8be..2b2ace0 100644 --- a/cspell.json +++ b/cspell.json @@ -173,7 +173,6 @@ "virality", "vuni", "wagmi", - "waitlist", "walletauth", "wcsep", "webview", diff --git a/world-id/yc.mdx b/world-id/yc.mdx index 108ccd1..2dbbeec 100644 --- a/world-id/yc.mdx +++ b/world-id/yc.mdx @@ -1,130 +1,51 @@ --- title: "World ID for YC Startups" -description: "The simplest way to add proof of human to your startup." +description: "Simple ways to build trust into your startup with World ID." hidden: true hideFooterPagination: true --- -World ID lets your app verify that a real, unique human is behind an action—without collecting the person's identity or biometric data. +The World stack is a privacy-preserving trust layer for startups that need to know whether a real, unique, present, or eligible person is behind an action. -For most startups, the simplest place to start is **Proof of Human**: require one proof before a user creates an account, claims a reward, or takes another high-value action. +## Start with the trust question you need to answer -## Use World ID when one person should get one chance +| Question | Use | What it helps you do | +| --- | --- | --- | +| Who can participate? | **World ID** | Prove a user is a real, unique human. | +| Who is present right now? | **Selfie Check** | Confirm that a human is approving an important action. | +| Who meets the requirements? | **Identity Attestations** | Verify an attribute such as age, nationality, residency, or document validity without collecting the underlying document. | +| When can an agent act? | **AgentKit** | Let an AI agent act after the required human trust checks are satisfied. | -World ID is a strong fit when duplicate accounts, bots, or impersonation can change the outcome: +## Why startups use World ID -| If you're building... | Use World ID to... | +1. **Stop bots and duplicate accounts.** Make rewards, referrals, voting, reviews, promotions, and social participation one-person-one-action. +2. **Protect sensitive moments.** Add human presence when someone approves a payment, recovers an account, deploys software, or authorizes a high-risk transaction. +3. **Check eligibility privately.** Confirm that someone meets a policy without asking your product to store their full identity documents. +4. **Match trust to risk.** Start with a lightweight check, then require stronger proof of humanity, presence, or eligibility where the stakes are higher. +5. **Build safer AI products.** Distinguish people from agents and make human approval an explicit boundary for consequential actions. +6. **Make communities more accountable.** Reduce impersonation, fake accounts, reputation manipulation, and fraudulent content while preserving privacy. + +## Where it fits in YC startups + +| If you're building... | The simplest place to use World ID | | --- | --- | -| An AI consumer product | Protect free trials, credits, referrals, and limited-access features from bot abuse. | -| A marketplace or community | Make reviews, reputation, applications, and participation harder to manipulate. | -| A rewards or growth loop | Give each person one reward, invite bonus, waitlist spot, or vote. | -| A crypto product | Support fair claims, allocations, grants, governance, or incentive programs. | -| A product with high-stakes actions | Establish a clear human approval boundary before an agent or automated system acts. | +| Proving you're human | Require one human per account to reduce Sybil attacks. | +| An AI consumer product | Protect a free trial, referral, reward, or limited promotion from duplicate claims. | +| Multiplayer AI | Distinguish verified people from AI agents in a shared environment. | +| An operating system for the physical world | Make sure tasks are assigned to real, unique workers. | +| A real-world data product | Limit data contribution and rewards to one unique contributor. | +| AI-native compliance | Add a privacy-preserving proof that a user is a real human before a regulated or high-risk action. | +| Crypto or stablecoins | Run fair allocations, grants, governance, airdrops, or incentives. | +| Cloud tools for small software | Reduce fake workspaces, spam, and abuse before privileged access. | +| Education | Protect scholarships, subsidized access, rewards, and student benefits. | +| Products for the aging population | Reduce impersonation of patients, family members, and caregivers. | +| Self-maintaining APIs | Add human accountability before critical code changes, merges, or deployments. | +| Defense or physical infrastructure | Add a human trust signal to safety-critical operations. | + +## Keep the first use case simple + +Choose the one action where abuse would most change the outcome—such as creating an account, claiming a reward, receiving a referral benefit, voting, or accessing a scarce resource. Start there, then add stronger trust signals only when the risk calls for them. - World ID proves a unique human, not a person's legal identity. Start with Proof of Human for anti-Sybil protection; add an identity credential later only when your product needs an eligibility attribute such as age or nationality. + World ID helps you know that a unique human can participate. Use Selfie Check when you need a signal that someone is present now, Identity Attestations when you need to know whether they meet a requirement, and AgentKit when an agent needs to act on their behalf. - -## The simplest production path - -### 1. Create your app and action - -In the [Developer Portal](https://developer.world.org), create an app, register a World ID relying party (RP), and create an action such as `verify-account` or `claim-referral-reward`. - -`app_id` and `rp_id` are public identifiers and can be included where the SDK needs them. Keep the RP signing key secret and on the server: - -- RP signing key - - - Never expose the RP signing key in browser code or a `NEXT_PUBLIC_` environment variable. It authenticates proof requests from your app. - - -### 2. Add the React widget - -Install the React SDK: - -```bash -npm i @worldcoin/idkit -``` - -Request an RP context from a server endpoint, then open the [IDKit React widget](/world-id/idkit/react). The outline below requests the current Proof of Human credential and sends the result to your backend for verification and authorization. - -```tsx -import { useState } from "react"; -import { - IDKitRequestWidget, - proofOfHuman, - type RpContext, -} from "@worldcoin/idkit"; - -export function VerifyAccount({ - accountId, - rpContext, -}: { - accountId: string; - rpContext: RpContext; -}) { - const [open, setOpen] = useState(false); - - return ( - <> - - { - const response = await fetch("/api/verify-proof", { - method: "POST", - headers: { "content-type": "application/json" }, - body: JSON.stringify({ - idkitResponse, - }), - }); - - if (!response.ok) throw new Error("Verification failed"); - }} - onSuccess={() => { - // Refresh client UI only. The backend authorized the protected operation. - }} - /> - - ); -} -``` - -For a staging test, use the [World ID Simulator](https://simulator.worldcoin.org/) and a staging action. Use a production action and `environment="production"` for real users. - -### 3. Verify on your backend and store the nullifier - -Your backend must: - -1. From the authenticated server session, select an allowed action and derive the expected account context and signal. Do not accept these authorization inputs from the browser. -2. Generate the `rp_context` with the RP signing key. See [RP signatures](/world-id/idkit/signatures). -3. Forward the IDKit result **unchanged** to the verification endpoint constructed with the trusted, server-configured RP ID: `POST https://developer.world.org/api/v4/verify/{rp_id}`. Do not accept an RP ID from the browser. See [backend verification](/world-id/idkit/integrate#step-5-verify-the-proof-in-your-backend). -4. Validate that the verified proof matches the server-selected action and expected account context/signal, then store the `(action, nullifier)` pair with a database uniqueness constraint. Reject a duplicate insert so the same person cannot repeat the action. Grant the protected operation only after every check succeeds. See [nullifier storage](/world-id/idkit/integrate#step-6-store-the-nullifier). - - - The nullifier is a per-app, per-action identifier. It prevents repeat use while remaining unlinkable across other apps and actions. - - -## Start with one high-value moment - -Avoid gating every click. Choose the point where abuse is expensive—for example, account creation, a free-credit claim, a referral reward, a vote, or a marketplace listing—and require Proof of Human there first. - -After that works, add World ID to other high-value actions with separate actions and nullifier records. - -## Add more trust only when you need it - -- Need a fresh human-presence check for a sensitive action? Review [user presence and liveness](/world-id/idkit/credentials#user-presence-and-liveness). -- Need an eligibility signal such as age, nationality, or document type? Review [Identity Check](/world-id/idkit/credentials#identity-check-preview). -- Building an agentic product? Use [AgentKit](/agents/agent-kit/integrate) after defining the human approval point. - -## Build the complete integration - -This page is the fast path. Follow the [full IDKit integration guide](/world-id/idkit/integrate) for server-side signatures, complete SDK examples, testing, and production rollout details. From 07a3adb819996249b69a0db54a9f80d452196b13 Mon Sep 17 00:00:00 2001 From: Mateo Sauton <39073982+mateosauton@users.noreply.github.com> Date: Wed, 19 Aug 2026 21:21:16 -0300 Subject: [PATCH 4/7] add YC integration link --- world-id/yc.mdx | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/world-id/yc.mdx b/world-id/yc.mdx index 2dbbeec..75154a2 100644 --- a/world-id/yc.mdx +++ b/world-id/yc.mdx @@ -49,3 +49,7 @@ Choose the one action where abuse would most change the outcome—such as creati World ID helps you know that a unique human can participate. Use Selfie Check when you need a signal that someone is present now, Identity Attestations when you need to know whether they meet a requirement, and AgentKit when an agent needs to act on their behalf. + +## Ready to build? + +[Start integrating World ID](/world-id/idkit/integrate) to bring the right trust signal into your product. From 73a4cb8ef11fc0f6e160cbe61f6414e945daaefb Mon Sep 17 00:00:00 2001 From: Mateo Sauton <39073982+mateosauton@users.noreply.github.com> Date: Wed, 19 Aug 2026 21:23:13 -0300 Subject: [PATCH 5/7] use companies in YC guide --- world-id/yc.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/world-id/yc.mdx b/world-id/yc.mdx index 75154a2..e47a00d 100644 --- a/world-id/yc.mdx +++ b/world-id/yc.mdx @@ -5,7 +5,7 @@ hidden: true hideFooterPagination: true --- -The World stack is a privacy-preserving trust layer for startups that need to know whether a real, unique, present, or eligible person is behind an action. +The World stack is a privacy-preserving trust layer for companies that need to know whether a real, unique, present, or eligible person is behind an action. ## Start with the trust question you need to answer From 9978f4b63882add22b57d0c00ae60fb9611d1db0 Mon Sep 17 00:00:00 2001 From: Mateo Sauton <39073982+mateosauton@users.noreply.github.com> Date: Thu, 20 Aug 2026 14:26:16 -0300 Subject: [PATCH 6/7] add YC guide contact --- world-id/yc.mdx | 2 ++ 1 file changed, 2 insertions(+) diff --git a/world-id/yc.mdx b/world-id/yc.mdx index e47a00d..b4e7d4e 100644 --- a/world-id/yc.mdx +++ b/world-id/yc.mdx @@ -53,3 +53,5 @@ Choose the one action where abuse would most change the outcome—such as creati ## Ready to build? [Start integrating World ID](/world-id/idkit/integrate) to bring the right trust signal into your product. + +Not sure how to use World ID in your project? Email [mateo.sauton@toolsforhumanity.com](mailto:mateo.sauton@toolsforhumanity.com) and we'll help you build it. From f4a8a1b4261a3617c24f90f3f8bf4ab5bcc36be4 Mon Sep 17 00:00:00 2001 From: Mateo Sauton <39073982+mateosauton@users.noreply.github.com> Date: Thu, 20 Aug 2026 14:28:45 -0300 Subject: [PATCH 7/7] correct YC identity check --- world-id/yc.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/world-id/yc.mdx b/world-id/yc.mdx index b4e7d4e..d869dbe 100644 --- a/world-id/yc.mdx +++ b/world-id/yc.mdx @@ -13,7 +13,7 @@ The World stack is a privacy-preserving trust layer for companies that need to k | --- | --- | --- | | Who can participate? | **World ID** | Prove a user is a real, unique human. | | Who is present right now? | **Selfie Check** | Confirm that a human is approving an important action. | -| Who meets the requirements? | **Identity Attestations** | Verify an attribute such as age, nationality, residency, or document validity without collecting the underlying document. | +| Who meets the requirements? | **Identity Check (Preview)** | Verify supported document-backed attributes—minimum age, nationality, document type, or issuing country—without collecting the underlying document. | | When can an agent act? | **AgentKit** | Let an AI agent act after the required human trust checks are satisfied. | ## Why startups use World ID @@ -47,7 +47,7 @@ The World stack is a privacy-preserving trust layer for companies that need to k Choose the one action where abuse would most change the outcome—such as creating an account, claiming a reward, receiving a referral benefit, voting, or accessing a scarce resource. Start there, then add stronger trust signals only when the risk calls for them. - World ID helps you know that a unique human can participate. Use Selfie Check when you need a signal that someone is present now, Identity Attestations when you need to know whether they meet a requirement, and AgentKit when an agent needs to act on their behalf. + World ID helps you know that a unique human can participate. Use Selfie Check when you need a signal that someone is present now, Identity Check (Preview) when you need to know whether they meet a supported requirement, and AgentKit when an agent needs to act on their behalf. ## Ready to build?