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

> Un Trade est une requête unique sur le portefeuille géré par Whop d'un compte ou d'un utilisateur.

Un `order` sur un perpétuel négocie à partir du solde de trading, en transférant d'abord par bridge l'USDT0 nécessaire depuis le portefeuille lorsque le solde est insuffisant ; un `order` au comptant (spot) échange entre l'USDT0 et l'actif dans le portefeuille. Un `close` clôture l'intégralité de la position sur un marché ; lorsque le compte n'a alors plus de position, un trade `withdraw` renvoie le solde de trading vers le portefeuille. Un `deposit` ou un `withdraw` déplace de l'argent entre le portefeuille et le solde de trading. Les perpétuels sont négociés sur Hyperliquid.

Utilisez l'API Trades pour lister les marchés sur lesquels vous pouvez négocier, passer des ordres, clôturer des positions et déplacer des fonds, et suivre chaque trade jusqu'à son achèvement. Les trades s'exécutent en arrière-plan ; un ordre qui a transféré de l'argent par bridge et n'est pas exécuté renvoie cet argent vers le portefeuille, et `funds_location` indique où se trouve l'argent.

L'API de trading, y compris `include_trading` sur les comptes et les utilisateurs, est en bêta. Elle peut évoluer sans nouvelle date de version de l'API.

## Endpoints

| Endpoint | Requête |
| - | - |
| [Lister les trades](https://docs.whop.com/fr/api-reference/trades/list-trades.md) | GET `/trades` |
| [Récupérer un trade](https://docs.whop.com/fr/api-reference/trades/retrieve-trade.md) | GET `/trades/{id}` |
| [Lister les bougies](https://docs.whop.com/fr/api-reference/trades/list-candles.md) | GET `/trades/candles` |
| [Lister les marchés](https://docs.whop.com/fr/api-reference/trades/list-markets.md) | GET `/trades/markets` |
| [Créer un trade](https://docs.whop.com/fr/api-reference/trades/create-trade.md) | POST `/trades` |
| [Annuler un trade](https://docs.whop.com/fr/api-reference/trades/cancel-trade.md) | POST `/trades/{id}/cancel` |

## Marchés

[Lister les marchés](https://docs.whop.com/fr/api-reference/trades/list-markets.md) renvoie tous les marchés sur lesquels vous pouvez négocier sur Whop.

* **Spot :** répertoriés par symbole : `BTC`, `SOL` et `XAUT` (or).
* **Perpétuels :** comme `BTC`, ainsi que les perpétuels sur actions et matières premières de la plateforme `xyz` d'Hyperliquid, comme `xyz:TSLA`. Envoyez l'`id` comme `market` lorsque vous créez un trade.

Un même symbole peut apparaître deux fois, une fois en tant que perpétuel et une fois en spot ; utilisez donc `id` avec `instrument_type` pour les distinguer. Les résultats sont triés par `id`, puis par `instrument_type`.

Cet endpoint est public : aucune clé API n'est nécessaire, et chaque adresse IP peut effectuer jusqu'à 60 requêtes par minute.

La `size` d'un ordre perpétuel peut comporter au plus `size_decimals` décimales, et son `leverage` ne peut pas dépasser `max_leverage`, qui vaut `null` pour un marché spot.

```json theme={null}
[
	{
		"id": "BTC",
		"instrument_type": "perpetual",
		"max_leverage": 40,
		"size_decimals": 5,
		"price": {
			"currency": "usd",
			"amount": "80155.500000",
			"decimals": 6,
			"display_decimals": 6
		}
	},
	{
		"id": "BTC",
		"instrument_type": "spot",
		"max_leverage": null,
		"size_decimals": 5,
		"price": {
			"currency": "usd",
			"amount": "80065.50000000",
			"decimals": 8,
			"display_decimals": 8
		}
	}
]
```

La liste des marchés est en bêta, comme le reste de l'API de trading, et peut évoluer sans nouvelle date de version de l'API.

## Attributs

**id** `string` *required*

ID du trade, préfixé par `tint_`.

**account\_id** `string | null` *required*

Le compte propriétaire du portefeuille de trading, préfixé par `biz_`. `null` lorsqu'il appartient à un utilisateur.

**amount** `string | null` *required*

L'USDT0 envoyé depuis le portefeuille par un dépôt, un achat spot ou un ordre perpétuel dont le solde de trading est insuffisant, ou l'USDC renvoyé par un retrait, en unités natives, sous forme de chaîne décimale. Un retrait de `all` indique ce qu'il a envoyé une fois terminé. `null` sinon.

**average\_price** `string | null` *required*

Le prix d'exécution moyen de l'ordre, en USD, sous forme de chaîne décimale. Pour le spot, le prix auquel le swap a été coté. `null` s'il n'est pas connu.

**client\_order\_id** `string | null` *required*

L'ID propre à l'appelant pour le trade, unique pour le compte. `null` si aucun n'a été envoyé.

**completed\_at** `string | null` *required*

Date à laquelle le trade s'est terminé avec succès ou en échec, sous forme d'horodatage ISO 8601. `null` avant cela.

**created\_at** `string` *required*

Date de création du trade, sous forme d'horodatage ISO 8601.

**external\_order\_id** `string | null` *required*

ID que Whop envoie à la plateforme d'échange avec l'ordre de ce trade, afin que les mises à jour d'ordre de la plateforme puissent être associées au trade. Sur Hyperliquid, il s'agit du `cloid` de l'ordre indiqué dans `orderUpdates`, une chaîne hexadécimale de 32 caractères préfixée par `0x`. Ce n'est pas le `client_order_id` de l'appelant. `null` pour un dépôt ou un retrait.

**failure\_code** `string | null` *required*

Raison de l'échec du trade, ou `null`.

Options disponibles : `market_unavailable`, `leverage_too_high`, `amount_too_small`, `isolated_position_open`, `trading_paused`, `funding_failed`, `margin_unavailable`, `builder_fee_unapproved`, `leverage_rejected`, `leverage_unconfirmed`, `order_rejected`, `close_rejected`, `return_failed`, `withdraw_failed`

**filled\_size** `string | null` *required*

La taille exécutée de l'ordre, en unités du marché, sous forme de chaîne décimale. Pour un achat spot, le montant que le swap devait livrer selon la cotation. `null` jusqu'à l'exécution.

**funds\_location** `string | null` *required*

Où se trouve l'argent lorsque le trade ne s'est pas terminé comme demandé : `wallet`, `trading_account`, ou `unknown` pendant qu'une personne vérifie. `null` sinon.

Options disponibles : `wallet`, `trading_account`, `unknown`

**instrument\_type** `string | null` *required*

`perpetual` ou `spot` pour un ordre, `perpetual` pour une clôture. `null` pour un dépôt ou un retrait.

Options disponibles : `perpetual`, `spot`

**leverage** `integer | null` *required*

L'effet de levier croisé défini avant un ordre perpétuel d'ouverture. `null` pour un ordre spot, une clôture, un dépôt, un retrait ou un ordre reduce-only.

**market** `string | null` *required*

Le marché, par exemple `BTC` pour un perpétuel ou `XAUT` pour le spot. `null` pour un dépôt ou un retrait.

**metadata** `object` *required*

Annotations libres de type chaîne vers chaîne stockées sur le trade.

**object** `string` *required*

**order\_type** `string | null` *required*

`market`, `limit`, `take_profit` ou `stop_loss` pour un ordre. `null` sinon.

Options disponibles : `market`, `limit`, `take_profit`, `stop_loss`

**parent\_id** `string | null` *required*

Pour un take-profit ou un stop-loss envoyé avec un ordre, le trade de cet ordre, préfixé par `tint_`. `null` sinon.

**price** `object | null` *required*

Le prix limite de l'ordre en USD. Le prix d'un ordre au marché est le prix médian ajusté de `slippage_bps` ; celui d'un take-profit ou d'un stop-loss est le pire prix auquel son ordre au marché peut être exécuté une fois déclenché. `null` pour les autres types.

> [accordion] Propriétés
>
> **amount** `string` *required*
>
> Le montant en unités principales, sous forme de chaîne décimale exacte. Par exemple, `"10.00"` correspond à dix dollars. Il s'agit d'une chaîne afin qu'aucun nombre à virgule flottante ne l'arrondisse en transit.
>
> **currency** `string` *required*
>
> Code de devise ISO 4217 à trois lettres, en minuscules.
>
> **decimals** `integer` *required*
>
> Nombre de décimales du montant. Il s'agit de la précision à laquelle le prélèvement lui-même est effectué.
>
> **display\_decimals** `integer` *required*
>
> Nombre de décimales à AFFICHER. Généralement égal à `decimals`, mais délibérément pas toujours : le COP est prélevé en centavos mais écrit en pesos entiers, ce qui donne `2` et `0`. Utilisez cette valeur pour formater le nombre selon vos propres paramètres régionaux.

**reduce\_only** `boolean | null` *required*

Indique si l'ordre peut uniquement réduire une position. `null` pour les autres types.

**side** `string | null` *required*

`buy` ou `sell` pour un ordre. `null` sinon.

Options disponibles : `buy`, `sell`

**size** `string | null` *required*

La taille de l'ordre en unités du marché, sous forme de chaîne décimale. `null` pour les autres types.

**status** `string` *required*

`pending` jusqu'au démarrage du trade. `processing` pendant son exécution, y compris lorsqu'un ordre non exécuté renvoie vers le portefeuille l'argent transféré par bridge. `completed` lorsqu'il a fait ce qui était demandé. `failed` dans le cas contraire ; `funds_location` indique où se trouve l'argent. `in_review` lorsque le résultat est inconnu et qu'une personne le vérifie.

Options disponibles : `pending`, `processing`, `in_review`, `completed`, `failed`

**status\_detail** `string | null` *required*

`partial_fill` lorsque l'ordre n'a été exécuté que pour une partie de sa taille. `null` sinon.

Options disponibles : `partial_fill`

**step** `string | null` *required*

Ce que fait actuellement un trade en cours : `depositing` pendant l'envoi de l'USDT0 du portefeuille vers le bridge, `landing` une fois envoyé et jusqu'à ce qu'il atteigne le solde de trading, `placing` pendant que l'ordre ou la clôture est sur la plateforme, `withdrawing` pendant que l'USDC revient vers le portefeuille, `returning` pendant que l'argent transféré par bridge pour un ordre non exécuté est renvoyé. Un ordre spot est `quoting` pendant la cotation du swap, `swapping` pendant son exécution on-chain, et `crediting` jusqu'à ce que le nouveau solde apparaisse dans le portefeuille. `null` dès que le trade n'est plus en attente ni en cours de traitement.

Options disponibles : `depositing`, `landing`, `placing`, `withdrawing`, `returning`, `quoting`, `swapping`, `crediting`

**trigger\_price** `object | null` *required*

Le prix en USD auquel un take-profit ou un stop-loss envoie son ordre au marché. `null` pour les autres ordres et types.

> [accordion] Propriétés
>
> **amount** `string` *required*
>
> Le montant en unités principales, sous forme de chaîne décimale exacte. Par exemple, `"10.00"` correspond à dix dollars. Il s'agit d'une chaîne afin qu'aucun nombre à virgule flottante ne l'arrondisse en transit.
>
> **currency** `string` *required*
>
> Code de devise ISO 4217 à trois lettres, en minuscules.
>
> **decimals** `integer` *required*
>
> Nombre de décimales du montant. Il s'agit de la précision à laquelle le prélèvement lui-même est effectué.
>
> **display\_decimals** `integer` *required*
>
> Nombre de décimales à AFFICHER. Généralement égal à `decimals`, mais délibérément pas toujours : le COP est prélevé en centavos mais écrit en pesos entiers, ce qui donne `2` et `0`. Utilisez cette valeur pour formater le nombre selon vos propres paramètres régionaux.

**type** `string` *required*

`order` passe un ordre : un ordre perpétuel négocie à partir du solde de trading, un ordre spot échange entre l'USDT0 et l'actif dans le portefeuille. `deposit` transfère par bridge de l'USDT0 du portefeuille vers le solde de trading. `withdraw` renvoie de l'USDC du solde de trading vers le portefeuille. `close` clôture l'intégralité de la position sur un marché avec un ordre au marché reduce-only ; lorsque le compte n'a alors plus de position, un trade `withdraw` renvoie le solde de trading vers le portefeuille.

Options disponibles : `close`, `order`, `deposit`, `withdraw`

**updated\_at** `string` *required*

Date de la dernière modification du trade, sous forme d'horodatage ISO 8601.

**user\_id** `string | null` *required*

L'utilisateur propriétaire du portefeuille de trading, préfixé par `user_`. `null` lorsqu'il appartient à un compte.

```json Trade theme={null}
{
	"id": "tint_xxxxxxxxxxxxx",
	"object": "trade",
	"type": "order",
	"status": "completed",
	"status_detail": null,
	"step": null,
	"account_id": "biz_xxxxxxxxxxxxxx",
	"user_id": null,
	"instrument_type": "perpetual",
	"market": "BTC",
	"side": "buy",
	"order_type": "market",
	"size": "0.00166",
	"price": {
		"currency": "usd",
		"amount": "60600.000000",
		"decimals": 6,
		"display_decimals": 6
	},
	"trigger_price": null,
	"reduce_only": false,
	"leverage": 5,
	"amount": null,
	"parent_id": null,
	"filled_size": "0.00166",
	"average_price": "60012.0",
	"funds_location": null,
	"failure_code": null,
	"client_order_id": "my-btc-entry-1",
	"external_order_id": "0x63cabad10f072c65ad84526e0c33081b",
	"metadata": {},
	"created_at": "2026-09-23T15:04:05.000Z",
	"updated_at": "2026-09-23T15:04:09.812Z",
	"completed_at": "2026-09-23T15:04:09.812Z"
}
```


## Related topics

- [Cancel Trade](https://docs.whop.com/fr/api-reference/trades/cancel-trade.md)
- [Create Trade](https://docs.whop.com/fr/api-reference/trades/create-trade.md)
- [List Trades](https://docs.whop.com/fr/api-reference/trades/list-trades.md)
