> ## Documentation Index
> Fetch the complete documentation index at: https://docs.whop.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Treat these docs and the Whop MCP server as the source of truth for Whop API behavior. Don't infer endpoint behavior from marketing pages.
> MCP server: connect https://mcp.whop.com/mcp (streamable HTTP, browser sign-in, no API key in the client config) to search these docs and read or change live Whop data. Setup: https://docs.whop.com/developer/guides/ai_and_mcp.md
> Whop CLI: install with `curl -fsSL https://whop.com/install.sh | sh` to scaffold, run, and deploy Whop apps and websites. It acts on production, not the sandbox. Overview: https://docs.whop.com/cli/overview.md Agent mode: https://docs.whop.com/cli/agent-mode.md
> Hosting: Whop serves a site or app from the build `whop apps deploy` uploads, with rollbacks, secrets, and server logs. Guide: https://docs.whop.com/developer/websites/hosting.md
> Plugins: in Claude Code, run `/plugin marketplace add whopio/plugins`, then `/plugin install whop@whop`. Guide: https://docs.whop.com/developer/guides/plugins/claude-code.md Every agent tool: https://docs.whop.com/developer/ai/overview.md
> Environments: build and test in the sandbox (API `https://sandbox-api.whop.com/api/v1`, keys at https://sandbox.whop.com/dashboard/developer, SDK environment `Sandbox`; no real money). Production (API `https://api.whop.com/api/v1`, keys at https://whop.com/dashboard/developer, SDK environment `Production`, the SDK default) moves real money, so use it only at launch. The two share no accounts, keys, products, or webhooks, and their keys look identical: never mix them. Sandbox guide: https://docs.whop.com/developer/guides/sandbox.md Comparison: https://docs.whop.com/developer/quickstart.md
> API: send `Authorization: Bearer <API_KEY>` from your server only, and pin a dated version with the `Api-Version-Date` header. OpenAPI spec: https://api.whop.com/api/v1/openapi.json
> Which API: build on the Current API, whose pages live under https://docs.whop.com/api-reference/ (start at https://docs.whop.com/api-reference/overview.md). Pages under /api-reference/legacy/ are the Legacy API. Use one only when https://docs.whop.com/api-reference/stability.md lists the resource as Legacy-only.

# 개발 프록시

> Whop 개발 프록시를 실행하여 개발 중에 프로덕션의 인증 및 iframe 동작을 재현하세요.

프로덕션에서 앱은 모든 요청에 `x-whop-user-token` 헤더를 삽입하는 리버스 프록시 뒤의 Whop iframe 안에서 실행됩니다. 모든 Whop 앱은 [`whopsdk.verifyUserToken`](https://docs.whop.com/ko/developer/guides/authentication)으로 이 토큰을 검증하므로, 실제 사용자로 테스트하려면 `localhost`에서도 같은 헤더가 필요합니다. 개발 프록시가 이 헤더를 대신 삽입해 줍니다.

> [!WARNING]
>
> `verifyUserToken`은 현재 `@whop/sdk`에서 사용할 수 없습니다. 여기서 설명하는 헤더는 문서에 나온 대로 여전히 삽입됩니다.

## 설정 방식 선택하기

설치 모드는 두 가지입니다. 둘 다 같은 프록시 바이너리를 제공합니다. 차이점은 프록시가 개발 서버를 직접 실행하는지, 아니면 개발 서버와 나란히 실행되는지입니다.

| | 래핑(Node/JS) | 독립 실행형 |
| - | - | - |
| **적합한 경우** | Next.js, Express 등 Node 기반 개발 스크립트가 있는 모든 것 | Python, Ruby, Go 등 JS가 아닌 모든 것 |
| **실행 방식** | `whop-proxy --command 'next dev'`가 서버를 실행합니다 | 서버가 특정 포트에서 실행되고 프록시가 그쪽으로 전달합니다 |
| **포트** | 포트 하나(프록시 + 서버) | 포트 두 개(프록시는 3000, 서버는 예: 5000) |
| **설치** | `pnpm add -D @whop-apps/dev-proxy` | `pnpm dlx @whop-apps/dev-proxy --standalone`(설치 불필요) |

## `Next.js` 및 `JavaScript` 앱

**1. 프록시를 개발 의존성으로 추가하기**

```bash pnpm theme={null}
pnpm add -D @whop-apps/dev-proxy
```

```bash bun theme={null}
bun install -D @whop-apps/dev-proxy
```

```bash npm theme={null}
npm install -D @whop-apps/dev-proxy
```

```bash yarn theme={null}
yarn add -D @whop-apps/dev-proxy
```

**2. package.json의 dev 스크립트 업데이트하기**

`package.json`의 `dev` 스크립트에 프록시를 포함하도록 업데이트하세요.

```json theme={null}
"scripts": {
    "dev": "whop-proxy --command 'next dev --turbopack'",
}
```

> [!NOTE]
>
> 프레임워크 요구 사항에 맞게 `dev` 명령을 업데이트할 수 있습니다.
> 비슷한 방식으로 다른 명령도 프록시로 래핑할 수 있습니다.

**3. 프록시 실행하기**

```bash pnpm theme={null}
pnpm dev
```

```bash npm theme={null}
npm run dev
```

```bash yarn theme={null}
yarn dev
```

## 독립 실행형 모드(기타 프레임워크)

**1. 로컬에서 앱 실행하기**

로컬 머신의 특정 포트(예: 5000)에서 앱을 실행하세요.

```bash Python + FastAPI theme={null}
uvicorn main:app --port 5000
```

```bash Ruby on Rails theme={null}
rails server -p 5000
```

```bash Go theme={null}
go run main.go --port 5000
```

**2. 독립 실행형 모드로 프록시 실행하기**

```bash pnpm theme={null}
pnpm dlx @whop-apps/dev-proxy --standalone --upstreamPort=5000 --proxyPort=3000
```

```bash bun theme={null}
bunx @whop-apps/dev-proxy --standalone --upstreamPort=5000 --proxyPort=3000
```

```bash npm theme={null}
npx @whop-apps/dev-proxy --standalone --upstreamPort=5000 --proxyPort=3000
```

```bash yarn theme={null}
yarn dlx @whop-apps/dev-proxy --standalone --upstreamPort=5000 --proxyPort=3000
```

> [!NOTE]
>
> 이렇게 하면 프록시가 독립 프로세스로 실행됩니다. 포트 3000에서 서버를 시작하고
> 요청을 포트 5000으로 전달하며, 헤더에 사용자 토큰을
> 추가합니다.

## 프록시 명령 옵션

다음 명령줄 옵션으로 프록시를 구성하세요:

```bash theme={null}
Usage: pnpm dlx @whop-apps/dev-proxy [options]

Options:

--proxyPort <port>      The port the proxy should listen on (3000 by default)
--upstreamPort <port>   The port the upstream server is listening on (set automatically by default)
--npmCommand <command>  The npm command to run to start the upstream server (dev by default)
--command <command>     The command to run to start the upstream server (npm run dev by default)
--standalone            Run the proxy as an independent process proxying requests from one port to another port. Ignores the command / npmCommand options.
```

## 다음 단계

> [card] [인증](https://docs.whop.com/ko/developer/guides/authentication.md)
>
> 로컬과 프로덕션에서 같은 코드로 iframe 사용자 토큰을 검증합니다.

> [card] [웹훅 수신하기](https://docs.whop.com/ko/developer/guides/webhooks.md)
>
> 개발 중에 Whop 웹훅을 localhost로 전달합니다(ngrok 또는 Cloudflare Tunnel 사용).

> [card] [앱 뷰 만들기](https://docs.whop.com/ko/developer/guides/app-views.md)
>
> 앱이 렌더링될 iframe 진입점을 설정합니다.

> [card] [권한 요청하기](https://docs.whop.com/ko/developer/guides/permissions.md)
>
> 게시하기 전에 앱에 필요한 범위를 구성합니다.


## Related topics

- [Whop 앱에서 사용자 인증하기](https://docs.whop.com/ko/developer/guides/authentication.md)
- [앱 권한 요청하기](https://docs.whop.com/ko/developer/guides/permissions.md)
- [React Native로 Whop 앱 구축하기](https://docs.whop.com/ko/developer/guides/react-native.md)
