> ## 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.

# 바운티 프로그램 운영하기

> API를 통해 유료 바운티를 게시하고, 계정 잔액으로 에스크로에 자금을 넣고, 반복 일정을 설정하고, 제출물을 받아 검토하며, 바운티를 취소하세요.

자체 제품에서 유료 작업을 게시하고, 계정 잔액으로 자금을 지원하며, 제출물 대기열을 자체 인터페이스로 가져오세요. 이 가이드는 바운티 생성, 작업 접수, 검토, 취소까지 전체 과정을 다룹니다.

> [!NOTE]
>
> 바운티를 게시하면 자금이 이동하므로 `bounty:create` 및 `payout:transfer_funds` 권한이 있는 API 키가 필요합니다. 제출물을 읽으려면 `bounty:basic:read`가 필요합니다.

## 바운티 게시하기

[`POST /bounties`](https://docs.whop.com/ko/api-reference/bounties/create-bounty)에는 `title`, 작업자가 따를 지침을 담은 `description`, `gross_reward_amount`가 필요합니다.

```typescript TypeScript theme={null}
import { WhopClient } from "@whop/sdk";

const client = new WhopClient({ token: process.env.WHOP_API_KEY });

const bounty = await client.bounties.create({
	title: "Clip our launch stream",
	description: "Cut a 30 to 60 second vertical clip and post it to TikTok. Include the product name in the caption.",
	gross_reward_amount: 25,
	accepted_submissions_limit: 4,
	business_goal_type: "clipping",
	account_id: "biz_XXXXXXXX",
	allowed_country_codes: ["US", "CA"],
});

console.log(bounty.id);
```

```python Python theme={null}
import os
from whop_sdk import Whop

client = Whop(token=os.environ["WHOP_API_KEY"])

bounty = client.bounties.create(
    title="Clip our launch stream",
    description="Cut a 30 to 60 second vertical clip and post it to TikTok. Include the product name in the caption.",
    gross_reward_amount=25,
    accepted_submissions_limit=4,
    business_goal_type="clipping",
    account_id="biz_XXXXXXXX",
    allowed_country_codes=["US", "CA"],
)

print(bounty.id)
```

### 보상 비용

`gross_reward_amount`는 바운티당이 아니라 **승인된 제출물당** 미국 달러 정수 금액입니다. `accepted_submissions_limit`은 몇 개의 제출물이 당선될 수 있는지 설정하며, 기본값은 `1`입니다. Whop은 두 값을 곱한 금액을 에스크로하며, 그 총액은 최소 $5여야 합니다. 위의 예시는 $100를 에스크로합니다.

플랫폼 수수료와 제휴 수수료는 추가로 부과되지 않고 총액에서 차감되므로, $25 보상은 자금 제공자에게 $25의 비용이 듭니다.

### 자금 출처

풀은 기본적으로 호출자의 개인 잔액에서 인출됩니다. 대신 계정 잔액으로 자금을 지원하려면 `account_id`를 전달하세요. 이를 위해서는 해당 계정의 자금을 이동할 권한이 필요합니다.

### 바운티 위치

`experience_id`는 바운티를 특정 경험에 배치합니다. 공개 바운티는 공개 경험에, 초대 바운티는 비공개 경험에 배치하며, **`account_id`를 설정하지 않는 한 필수입니다**. `account_id`를 설정하고 경험을 생략하면 바운티는 해당 계정의 공개 포럼에 고정됩니다.

### 목표 지정하기

`business_goal_type`은 작업이 달성해야 할 목표를 나타내며, 바운티를 생성할 때 한 번 지정합니다. `clipping`, `post_engagement`, `owned_account_growth`, `ugc_content`, `local_activation`, `data_capture`, `other`를 받습니다.

`capture_spec`은 목표가 `data_capture`인 경우에만 허용됩니다. 다른 목표와 함께 전송하면 실패합니다.

## 일정 및 반복

바운티는 `publish_at`을 설정하지 않으면 생성하자마자 게시됩니다. 설정하면 Whop은 바운티를 숨겨진 초안으로 생성한 다음 지정한 시간에 자금을 지원하고 게시합니다. `publish_at`이 설정된 경우 `publish_at_timezone`이 필수입니다.

`frequency`는 예약된 바운티를 반복 바운티로 바꿉니다. 기본값은 `once`이며, `hourly`, `daily`, `weekly`, `monthly`를 받고, **`publish_at`과 함께 사용할 때만 적용됩니다**. 각 회차는 자체 제출물과 자체 에스크로를 가진 별도의 바운티입니다.

```typescript TypeScript theme={null}
const weekly = await client.bounties.create({
	title: "Weekly product clip",
	description: "One vertical clip per week featuring a different product from the catalog.",
	gross_reward_amount: 50,
	account_id: "biz_XXXXXXXX",
	business_goal_type: "clipping",
	publish_at: "2026-09-01T15:00:00Z",
	publish_at_timezone: "America/New_York",
	frequency: "weekly",
});
```

```python Python theme={null}
weekly = client.bounties.create(
    title="Weekly product clip",
    description="One vertical clip per week featuring a different product from the catalog.",
    gross_reward_amount=50,
    account_id="biz_XXXXXXXX",
    business_goal_type="clipping",
    publish_at="2026-09-01T15:00:00Z",
    publish_at_timezone="America/New_York",
    frequency="weekly",
)
```

## 바운티 편집하기

[`PATCH /bounties/{id}`](https://docs.whop.com/ko/api-reference/bounties/update-bounty)가 받는 항목은 바운티가 게시되었는지에 따라 다릅니다. **예약된 초안**은 보상, 당선 슬롯, 일정, 콘텐츠 필드 등 모든 것을 받습니다.

**게시된 바운티**는 콘텐츠만 받습니다. 즉 `title`, `description`, `allowed_country_codes`, `business_goal_type`입니다. 이마저도 바운티가 시도를 더 이상 받지 않거나, 제출물이 `submitted` 또는 `approved`에 도달하면 거부됩니다. 보상, 당선 슬롯, 일정은 바운티가 게시되면 모두 고정됩니다.

`accepted_submissions_per_user_limit`은 한 작업자가 당선될 수 있는 슬롯 수의 상한을 정합니다. 기본값은 `1`이며, `accepted_submissions_limit`을 초과할 수 없고, 작업자는 한 번에 하나의 시도만 진행합니다.

## 제출물 받기

[`POST /bounty_submissions`](https://docs.whop.com/ko/api-reference/bounty-submissions/create-bounty-submission)는 `bounty_id`와 `deliverable`을 받습니다. `urls`, `file_ids`, `caption`을 조합하되, **최소 하나의 링크 또는 하나의 파일**이 있어야 합니다. Whop은 빈 결과물을 거부합니다. 일반 바운티에서는 이 단일 호출이 작업자 흐름의 전부이며, 제출물은 바로 검토로 넘어갑니다. 제출물에는 사용자 자격 증명이 필요하므로 계정 API 키로는 작성할 수 없습니다.

```typescript TypeScript theme={null}
const submission = await client.bountySubmissions.create({
	bounty_id: "bnty_XXXXXXXX",
	deliverable: {
		urls: ["https://www.tiktok.com/@creator/video/1234567890"],
		file_ids: ["file_XXXXXXXX"],
		caption: "Vertical cut, 42 seconds.",
	},
});
```

```python Python theme={null}
submission = client.bounty_submissions.create(
    bounty_id="bnty_XXXXXXXX",
    deliverable={
        "urls": ["https://www.tiktok.com/@creator/video/1234567890"],
        "file_ids": ["file_XXXXXXXX"],
        "caption": "Vertical cut, 42 seconds.",
    },
)
```

`allowed_country_codes`는 바운티 작업이 가능한 사람을 제한합니다. ISO 3166 alpha-2 코드를 받습니다. 빈 목록은 전 세계를 의미합니다.

작업자는 [`DELETE /bounty_submissions/{id}`](https://docs.whop.com/ko/api-reference/bounty-submissions/cancel-bounty-submission)로 자신의 시도를 철회할 수 있습니다. 시도를 시작한 작업자만 가능하며, 계정 API 키로 대신할 수 없습니다.

### 연동에서 완료할 수 없는 목표

두 가지 목표 유형은 API 외부에서 증빙을 축적합니다. `data_capture` 바운티에서는 결과물 **없이** 제출물을 생성하세요. 그러면 클립이 서버 측에 축적되는 시도가 시작됩니다. 라이브스트림 바운티의 증빙은 공개 API가 노출하지 않는 인터페이스를 통해 처리됩니다. 연동에서 이러한 바운티를 게시하고 대기열을 읽을 수는 있지만, 작업자는 Whop에서 시도를 완료합니다.

## 대기열 검토하기

[`GET /bounty_submissions`](https://docs.whop.com/ko/api-reference/bounty-submissions/list-bounty-submissions)로 제출물을 읽으며, `bounty_id`와 선택적으로 `status`로 필터링하세요.

```typescript TypeScript theme={null}
const queue = await client.bountySubmissions.list({
	bounty_id: "bnty_XXXXXXXX",
	status: "submitted",
});

for (const submission of queue.data) {
	console.log(submission.id, submission.status);
}
```

```python Python theme={null}
queue = client.bounty_submissions.list(
    bounty_id="bnty_XXXXXXXX",
    status="submitted",
)

for submission in queue.data:
    print(submission.id, submission.status)
```

제출물은 네 가지 상태를 거칩니다:

| `status` | 의미 |
| - | - |
| `in_progress` | 아직 증빙을 제출하지 않은 진행 중인 시도 |
| `submitted` | 결정 대기 중 |
| `approved` | 승인되었으며, 에스크로된 보상이 지급됩니다 |
| `denied` | 거부되었습니다. 제시할 수 있는 사유가 있으면 `denial_reason`에 사유가 담기며, 그렇지 않으면 `null`입니다 |

> [!WARNING]
>
> 승인과 거부는 Whop 대시보드에서 이루어집니다. API에는 승인 또는 거부 작업이 없으므로, 제품에서 대기열과 결과를 표시할 수는 있지만 결정은 사람이 Whop에서 내립니다.

바운티는 웹훅을 발생시키지 않습니다. 자체 제품에 결과를 반영하려면 해당 바운티로 필터링한 `GET /bounty_submissions`를 폴링하세요. 사람이 검토하는 대기열에는 1분에 한 번이 적합합니다. 최근 활동이 없는 바운티는 몇 분에 한 번으로 간격을 늘리세요.

## 바운티 취소하기

[`POST /bounties/{id}/cancel`](https://docs.whop.com/ko/api-reference/bounties/cancel)은 진행 중인 작업이 없으면 자금 제공자에게 즉시 환불합니다. 검토 중인 작업이 있으면 새 제출을 중단하고, 해당 작업이 처리되어 지급된 후 취소합니다.

요청을 반복해도 아무 일도 일어나지 않습니다. 이미 모든 슬롯에 지급한 바운티는 `400`을 반환합니다.

## 검증을 통과해도 실패하는 요청

요청 스키마로 표현할 수 없는 네 가지 규칙이 있습니다. 본문 형식이 올바르더라도 각각 오류를 반환합니다:

* `account_id`가 설정되지 않은 상태에서 `experience_id` 생략.
* `publish_at` 없이 `frequency` 전송.
* `business_goal_type`이 `data_capture`가 아닌데 `capture_spec` 전송.
* 링크도 파일도 없는 `deliverable`.

## 다음 단계

> [card] [바운티 개요](https://docs.whop.com/ko/developer/bounties/overview.md)
>
> 객체와 그 관계.

> [card] [파일 업로드하기](https://docs.whop.com/ko/developer/guides/upload-files.md)
>
> 결과물이 참조하는 파일 ID를 가져오세요.

> [card] [바운티 레퍼런스](https://docs.whop.com/ko/api-reference/bounties/bounty)
>
> 모든 엔드포인트의 요청 및 응답 형태.

> [card] [바운티 제출물 레퍼런스](https://docs.whop.com/ko/api-reference/bounty-submissions/retrieve-bounty-submission.md)
>
> 제출물 객체와 필터.


## Related topics

- [바운티](https://docs.whop.com/ko/developer/bounties/overview.md)
- [Whop Partners API](https://docs.whop.com/ko/developer/partners/overview.md)
- [Whop API 핵심 개념](https://docs.whop.com/ko/developer/concepts.md)
