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

# Een bountyprogramma uitvoeren

> Plaats betaalde bounties via de API, financier de escrow vanuit een accountsaldo, plan herhalingen, ontvang en beoordeel inzendingen en annuleer bounties.

Plaats betaalde taken vanuit je eigen product, financier ze vanuit het saldo van een account en haal de wachtrij met inzendingen naar je eigen interface. Deze gids behandelt de volledige cyclus: een bounty aanmaken, werk ontvangen, het beoordelen en annuleren.

> [!NOTE]
>
> Je hebt een API-sleutel nodig met `bounty:create` en `payout:transfer_funds`, omdat er bij het plaatsen van een bounty geld wordt verplaatst. Voor het lezen van inzendingen is `bounty:basic:read` nodig.

## Een bounty plaatsen

[`POST /bounties`](https://docs.whop.com/nl/api-reference/bounties/create-bounty) heeft een `title` nodig, een `description` met de instructies die een worker volgt, en een `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)
```

### Wat de beloning je kost

`gross_reward_amount` is in hele Amerikaanse dollars **per geaccepteerde inzending**, niet per bounty. `accepted_submissions_limit` bepaalt hoeveel inzendingen kunnen winnen en is standaard `1`. Whop houdt het product van die twee in escrow, en dat totaal moet ten minste $5 zijn. Het voorbeeld hierboven houdt $100 in escrow.

Platformkosten en affiliate-aandelen worden van het brutobedrag afgehaald in plaats van erbovenop te komen, dus een beloning van $25 kost de financier $25.

### Waar het geld vandaan komt

De pot wordt standaard gefinancierd uit het persoonlijke saldo van de aanroeper. Geef `account_id` mee om de pot in plaats daarvan te financieren uit het saldo van een account. Daarvoor heb je toestemming nodig om het geld van dat account te verplaatsen.

### Waar de bounty staat

`experience_id` plaatst een bounty in een specifieke experience, openbaar voor een open bounty of privé voor een bounty op uitnodiging, en **is vereist tenzij je `account_id` instelt**. Wanneer je `account_id` instelt en de experience weglaat, komt de bounty in het openbare forum van dat account te staan.

### Het doel aangeven

`business_goal_type` geeft aan wat het werk moet opleveren, en je geeft dit één keer op wanneer je de bounty aanmaakt. Het accepteert `clipping`, `post_engagement`, `owned_account_growth`, `ugc_content`, `local_activation`, `data_capture` of `other`.

`capture_spec` wordt alleen geaccepteerd wanneer het doel `data_capture` is. Met elk ander doel mislukt het verzoek.

## Plannen en herhalen

Een bounty wordt gepubliceerd zodra je hem aanmaakt, tenzij je `publish_at` instelt. Whop maakt hem dan aan als verborgen concept en financiert en publiceert hem op het tijdstip dat je hebt opgegeven. `publish_at_timezone` is vereist wanneer `publish_at` is ingesteld.

`frequency` maakt van een geplande bounty een terugkerende bounty. De standaardwaarde is `once`, het accepteert `hourly`, `daily`, `weekly` of `monthly` en **geldt alleen in combinatie met `publish_at`**. Elke herhaling is een aparte bounty met eigen inzendingen en een eigen escrow.

```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",
)
```

## Een bounty bewerken

Wat [`PATCH /bounties/{id}`](https://docs.whop.com/nl/api-reference/bounties/update-bounty) accepteert, hangt ervan af of de bounty al is gepubliceerd. Een **gepland concept** accepteert alles: de beloning, de winnaarsplekken, de planning en de inhoudsvelden.

Een **gepubliceerde bounty** accepteert alleen inhoud, namelijk `title`, `description`, `allowed_country_codes` en `business_goal_type`. Zelfs die worden geweigerd zodra de bounty geen pogingen meer accepteert, of zodra een inzending `submitted` of `approved` bereikt. De beloning, de winnaarsplekken en de planning liggen allemaal vast zodra een bounty is gepubliceerd.

`accepted_submissions_per_user_limit` beperkt hoeveel plekken één worker kan winnen. De standaardwaarde is `1`, de waarde kan `accepted_submissions_limit` niet overschrijden, en een worker voert één poging tegelijk uit.

## Inzendingen ontvangen

[`POST /bounty_submissions`](https://docs.whop.com/nl/api-reference/bounty-submissions/create-bounty-submission) accepteert de `bounty_id` en een `deliverable`. Combineer `urls`, `file_ids` en een `caption`, met **ten minste één link of één bestand**. Whop weigert een lege deliverable. Bij een standaardbounty is deze ene aanroep de volledige flow voor de worker, en gaat de inzending direct ter beoordeling. Inzendingen vereisen gebruikersreferenties, dus met een Account API-sleutel kun je er geen maken.

```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` beperkt wie aan een bounty kan werken. Het accepteert ISO 3166 alpha-2-codes. Een lege lijst betekent wereldwijd.

Een worker kan de eigen poging intrekken met [`DELETE /bounty_submissions/{id}`](https://docs.whop.com/nl/api-reference/bounty-submissions/cancel-bounty-submission). Alleen de worker die de poging is gestart kan dat, en een Account API-sleutel kan het niet namens hem doen.

### Doelen die je integratie niet kan voltooien

Bij twee doeltypen wordt het bewijs buiten de API verzameld. Maak bij een `data_capture`-bounty de inzending aan **zonder** deliverable: daarmee start een geclaimde poging waarvan de clips server-side worden verzameld. Bewijs voor een livestreambounty loopt via een omgeving die de openbare API niet beschikbaar stelt. Je integratie kan deze bounties plaatsen en de wachtrijen ervan lezen, maar een worker rondt de poging af in Whop.

## De wachtrij beoordelen

Lees inzendingen met [`GET /bounty_submissions`](https://docs.whop.com/nl/api-reference/bounty-submissions/list-bounty-submissions), gefilterd op `bounty_id` en optioneel op `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)
```

Een inzending doorloopt vier statussen:

| `status` | Betekenis |
| - | - |
| `in_progress` | Een actieve poging waarvoor nog geen bewijs is ingediend |
| `submitted` | Wacht op een beslissing |
| `approved` | Geaccepteerd, en de beloning in escrow wordt uitbetaald |
| `denied` | Afgewezen. `denial_reason` bevat de reden wanneer er een toonbare reden is, en is anders `null` |

> [!WARNING]
>
> Goedkeuren en afwijzen gebeurt in het Whop-dashboard. De API heeft geen bewerking om goed te keuren of af te wijzen, dus je product kan de wachtrij en de uitkomsten tonen, maar een persoon beslist in Whop.

Bounties versturen geen webhooks. Om uitkomsten in je eigen product te tonen, poll je `GET /bounty_submissions`, gefilterd op de bounty. Eén keer per minuut past bij een wachtrij die een persoon beoordeelt. Schaal terug naar eens per paar minuten wanneer een bounty geen recente activiteit heeft.

## Een bounty annuleren

[`POST /bounties/{id}/cancel`](https://docs.whop.com/nl/api-reference/bounties/cancel) betaalt de financier direct terug wanneer er geen werk loopt. Wanneer er werk in beoordeling is, stopt het nieuwe inzendingen en wordt de bounty geannuleerd zodra dat werk is afgehandeld en uitbetaald.

Het verzoek herhalen doet niets. Een bounty die al elke plek heeft uitbetaald, retourneert een `400`.

## Verzoeken die door de validatie komen en toch mislukken

Vier regels die het verzoekschema niet kan uitdrukken. Elk ervan retourneert een fout, ook al is de body correct opgebouwd:

* `experience_id` weggelaten zonder dat `account_id` is ingesteld.
* `frequency` verzonden zonder `publish_at`.
* `capture_spec` verzonden wanneer `business_goal_type` iets anders is dan `data_capture`.
* Een `deliverable` zonder link en zonder bestand.

## Volgende stappen

> [card] [Overzicht van bounties](https://docs.whop.com/nl/developer/bounties/overview.md)
>
> De objecten en hoe ze samenhangen.

> [card] [Bestanden uploaden](https://docs.whop.com/nl/developer/guides/upload-files.md)
>
> Haal de bestands-ID's op waarnaar een deliverable verwijst.

> [card] [Bounties-referentie](https://docs.whop.com/nl/api-reference/bounties/bounty)
>
> Verzoek- en responsstructuren voor elk endpoint.

> [card] [Referentie voor bounty-inzendingen](https://docs.whop.com/nl/api-reference/bounty-submissions/retrieve-bounty-submission.md)
>
> Het inzendingsobject en de filters ervan.


## Related topics

- [Bounties](https://docs.whop.com/nl/developer/bounties/overview.md)
- [Terugbetalingen en geschillen](https://docs.whop.com/nl/developer/guides/refunds-and-disputes.md)
- [Permissions API](https://docs.whop.com/nl/api-reference/permissions/permission.md)
