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

# Gérer un programme de bounties

> Publiez des bounties rémunérées via l'API, financez le séquestre depuis le solde d'un compte, planifiez des répétitions, recueillez et examinez les soumissions, et annulez des bounties.

Publiez des tâches rémunérées depuis votre propre produit, financez-les depuis le solde d'un compte et intégrez la file des soumissions à votre propre interface. Ce guide couvre le cycle complet : créer une bounty, recueillir le travail, l'examiner et annuler.

> [!NOTE]
>
> Vous avez besoin d'une clé API disposant de `bounty:create` et `payout:transfer_funds`, car publier une bounty déplace de l'argent. La lecture des soumissions nécessite `bounty:basic:read`.

## Publier une bounty

[`POST /bounties`](https://docs.whop.com/fr/api-reference/bounties/create-bounty) nécessite un `title`, une `description` contenant les instructions que suit le participant, et un `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)
```

### Ce que vous coûte la récompense

`gross_reward_amount` est un montant en dollars américains entiers **par soumission acceptée**, et non par bounty. `accepted_submissions_limit` définit combien de soumissions peuvent l'emporter, et vaut `1` par défaut. Whop place sous séquestre le produit des deux, et ce total doit être d'au moins 5 $. L'exemple ci-dessus place 100 $ sous séquestre.

Les frais de plateforme et les parts d'affiliation sont prélevés sur le montant brut au lieu de s'y ajouter : une récompense de 25 $coûte donc 25$ au financeur.

### D'où vient l'argent

La cagnotte puise par défaut dans le solde personnel de l'appelant. Passez `account_id` pour la financer plutôt depuis le solde d'un compte, ce qui nécessite la permission de déplacer les fonds de ce compte.

### Où se trouve la bounty

`experience_id` place une bounty dans une expérience précise, publique pour une bounty ouverte ou privée pour une bounty sur invitation, et **il est obligatoire sauf si vous définissez `account_id`**. Lorsque vous définissez `account_id` et omettez l'expérience, la bounty est rattachée au forum public de ce compte.

### Déclarer l'objectif

`business_goal_type` indique ce que le travail est censé accomplir, et vous le déclarez une seule fois lors de la création de la bounty. Il accepte `clipping`, `post_engagement`, `owned_account_growth`, `ugc_content`, `local_activation`, `data_capture` ou `other`.

`capture_spec` n'est accepté que lorsque l'objectif est `data_capture`. L'envoyer avec un autre objectif échoue.

## Planifier et répéter

Une bounty est publiée dès sa création, sauf si vous définissez `publish_at`. Whop la crée alors sous forme de brouillon masqué, puis la finance et la publie à l'heure indiquée. `publish_at_timezone` est obligatoire dès que `publish_at` est défini.

`frequency` transforme une bounty planifiée en bounty récurrente. Il vaut `once` par défaut, accepte `hourly`, `daily`, `weekly` ou `monthly`, et **ne s'applique qu'avec `publish_at`**. Chaque occurrence est une bounty distincte avec ses propres soumissions et son propre séquestre.

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

## Modifier une bounty

Ce qu'accepte [`PATCH /bounties/{id}`](https://docs.whop.com/fr/api-reference/bounties/update-bounty) dépend de la publication ou non de la bounty. Un **brouillon planifié** accepte tout : la récompense, les places de gagnants, le calendrier et les champs de contenu.

Une **bounty publiée** n'accepte que le contenu, c'est-à-dire `title`, `description`, `allowed_country_codes` et `business_goal_type`. Même ces champs sont refusés dès que la bounty n'accepte plus de tentatives, ou dès qu'une soumission atteint `submitted` ou `approved`. La récompense, les places de gagnants et le calendrier sont tous figés une fois la bounty publiée.

`accepted_submissions_per_user_limit` plafonne le nombre de places qu'un participant peut remporter. Il vaut `1` par défaut, ne peut pas dépasser `accepted_submissions_limit`, et un participant mène une seule tentative à la fois.

## Recueillir des soumissions

[`POST /bounty_submissions`](https://docs.whop.com/fr/api-reference/bounty-submissions/create-bounty-submission) accepte le `bounty_id` et un `deliverable`. Combinez `urls`, `file_ids` et une `caption`, avec **au moins un lien ou un fichier**. Whop rejette un livrable vide. Sur une bounty standard, cet unique appel constitue tout le parcours du participant, et la soumission passe directement en examen. Les soumissions nécessitent des identifiants utilisateur, donc une clé API de compte ne peut pas en créer.

```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` limite qui peut travailler sur une bounty. Il accepte des codes ISO 3166 alpha-2. Une liste vide signifie le monde entier.

Un participant peut retirer sa propre tentative avec [`DELETE /bounty_submissions/{id}`](https://docs.whop.com/fr/api-reference/bounty-submissions/cancel-bounty-submission). Seul le participant qui l'a lancée peut le faire, et une clé API de compte ne peut pas le faire à sa place.

### Objectifs que votre intégration ne peut pas finaliser

Deux types d'objectifs accumulent leurs preuves en dehors de l'API. Sur une bounty `data_capture`, créez la soumission **sans** livrable : cela démarre une tentative réservée dont les clips s'accumulent côté serveur. La preuve d'une bounty de livestream passe par une interface que l'API publique n'expose pas. Votre intégration peut publier ces bounties et lire leurs files, mais le participant termine la tentative dans Whop.

## Examiner la file

Lisez les soumissions avec [`GET /bounty_submissions`](https://docs.whop.com/fr/api-reference/bounty-submissions/list-bounty-submissions), filtrées par `bounty_id` et éventuellement par `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)
```

Une soumission passe par quatre états :

| `status` | Signification |
| - | - |
| `in_progress` | Une tentative active qui n'a pas encore soumis de preuve |
| `submitted` | En attente d'une décision |
| `approved` | Acceptée, et la récompense sous séquestre est versée |
| `denied` | Rejetée. `denial_reason` contient la raison lorsqu'une raison présentable existe, et vaut `null` sinon |

> [!WARNING]
>
> L'approbation et le refus se font dans le tableau de bord Whop. L'API n'a pas d'opération d'approbation ou de refus : votre produit peut afficher la file et ses résultats, mais c'est une personne qui décide dans Whop.

Les bounties n'émettent aucun webhook. Pour refléter les résultats dans votre propre produit, interrogez régulièrement `GET /bounty_submissions` filtré sur la bounty. Une fois par minute convient à une file examinée par une personne. Espacez à toutes les quelques minutes lorsqu'une bounty n'a pas d'activité récente.

## Annuler une bounty

[`POST /bounties/{id}/cancel`](https://docs.whop.com/fr/api-reference/bounties/cancel) rembourse immédiatement le financeur lorsqu'aucun travail n'est en cours. Lorsque du travail est en cours d'examen, il bloque les nouvelles soumissions et annule une fois ce travail résolu et payé.

Répéter la requête n'a aucun effet. Une bounty qui a déjà versé toutes ses places renvoie une erreur `400`.

## Requêtes qui passent la validation mais échouent quand même

Quatre règles que le schéma de requête ne peut pas exprimer. Chacune renvoie une erreur même si le corps est bien formé :

* `experience_id` omis sans `account_id` défini.
* `frequency` envoyé sans `publish_at`.
* `capture_spec` envoyé lorsque `business_goal_type` est autre chose que `data_capture`.
* Un `deliverable` ne contenant ni lien ni fichier.

## Étapes suivantes

> [card] [Vue d'ensemble des bounties](https://docs.whop.com/fr/developer/bounties/overview.md)
>
> Les objets et la façon dont ils s'articulent.

> [card] [Téléverser des fichiers](https://docs.whop.com/fr/developer/guides/upload-files.md)
>
> Obtenez les ID de fichiers référencés par un livrable.

> [card] [Référence Bounties](https://docs.whop.com/fr/api-reference/bounties/bounty)
>
> Formats de requête et de réponse pour chaque endpoint.

> [card] [Référence des soumissions de bounty](https://docs.whop.com/fr/api-reference/bounty-submissions/retrieve-bounty-submission.md)
>
> L'objet soumission et ses filtres.


## Related topics

- [Bounties](https://docs.whop.com/fr/developer/bounties/overview.md)
- [API Bounties](https://docs.whop.com/fr/api-reference/bounties/bounty.md)
- [Gérer la fraude](https://docs.whop.com/fr/developer/guides/manage-fraud.md)
