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

> Un Trade es una solicitud sobre la billetera gestionada por Whop de una cuenta o un usuario.

Una `order` sobre un perpetuo opera desde el saldo de trading, transfiriendo primero por bridge el USDT0 que necesita desde la billetera cuando el saldo no alcanza; una `order` sobre spot intercambia entre USDT0 y el activo en la billetera. Un `close` cierra toda la posición en un mercado; cuando la cuenta queda sin posiciones, un trade `withdraw` devuelve el saldo de trading a la billetera. Un `deposit` o un `withdraw` mueve dinero entre la billetera y el saldo de trading. Los perpetuos se operan en Hyperliquid.

Usa la API de Trades para listar los mercados en los que puedes operar, colocar órdenes, cerrar posiciones y mover fondos, y hacer seguimiento de cada trade hasta que termine. Los trades se ejecutan en segundo plano; una orden que transfirió dinero por bridge y no se ejecuta devuelve ese dinero a la billetera, y `funds_location` indica dónde está el dinero.

La API de trading, incluido `include_trading` en cuentas y usuarios, está en beta. Puede cambiar sin una nueva fecha de versión de la API.

## Endpoints

| Endpoint | Solicitud |
| - | - |
| [Listar Trades](https://docs.whop.com/es/api-reference/trades/list-trades.md) | GET `/trades` |
| [Obtener Trade](https://docs.whop.com/es/api-reference/trades/retrieve-trade.md) | GET `/trades/{id}` |
| [Listar velas](https://docs.whop.com/es/api-reference/trades/list-candles.md) | GET `/trades/candles` |
| [Listar mercados](https://docs.whop.com/es/api-reference/trades/list-markets.md) | GET `/trades/markets` |
| [Crear Trade](https://docs.whop.com/es/api-reference/trades/create-trade.md) | POST `/trades` |
| [Cancelar Trade](https://docs.whop.com/es/api-reference/trades/cancel-trade.md) | POST `/trades/{id}/cancel` |

## Mercados

[Listar mercados](https://docs.whop.com/es/api-reference/trades/list-markets.md) devuelve todos los mercados en los que puedes operar en Whop.

* **Spot:** se listan por símbolo: `BTC`, `SOL` y `XAUT` (oro).
* **Perpetuos:** como `BTC`, y perpetuos de acciones y materias primas del exchange `xyz` de Hyperliquid, como `xyz:TSLA`. Envía el `id` como `market` cuando crees un trade.

El mismo símbolo puede aparecer dos veces, una como perpetuo y otra como spot, así que usa `id` junto con `instrument_type` para distinguirlos. Los resultados se ordenan por `id` y luego por `instrument_type`.

Este endpoint es público: no se necesita API key, y cada dirección IP puede hacer hasta 60 solicitudes por minuto.

El `size` de una orden de perpetuo puede tener como máximo `size_decimals` decimales, y su `leverage` puede ser como máximo `max_leverage`, que es `null` para un mercado 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 lista de mercados está en beta, como el resto de la API de trading, y puede cambiar sin una nueva fecha de versión de la API.

## Atributos

**id** `string` *required*

ID del trade, con el prefijo `tint_`.

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

La cuenta propietaria de la billetera de trading, con el prefijo `biz_`. `null` cuando su propietario
es un usuario.

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

El USDT0 que envía desde la billetera un depósito, una compra spot o una orden de perpetuo sin saldo
de trading suficiente, o el USDC que devuelve un retiro, en
unidades nativas, como cadena decimal. Un retiro de `all` muestra lo que envió una vez
que termina. `null` en otro caso.

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

El precio medio de ejecución de la orden, en USD, como cadena decimal. Para spot,
el precio al que se cotizó el swap. `null` cuando no se conoce.

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

El ID propio de quien llama para el trade, único para la cuenta. `null` cuando no
se envió ninguno.

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

Cuándo terminó el trade como completado o fallido, como marca de tiempo ISO 8601. `null`
antes de eso.

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

Cuándo se creó el trade, como marca de tiempo ISO 8601.

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

ID que Whop envía al exchange con la orden de este trade, para que las actualizaciones de órdenes
del exchange se puedan asociar al trade. En Hyperliquid, el `cloid` de la orden
informado en `orderUpdates`, una cadena hexadecimal de 32 caracteres con el prefijo `0x`. No es el
`client_order_id` de quien llama. `null` para un depósito o retiro.

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

Por qué falló el trade, o `null`.

Opciones 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*

El tamaño ejecutado de la orden, en unidades del mercado, como cadena decimal. Para una
compra spot, el importe que el swap se cotizó para entregar. `null` hasta que se ejecuta.

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

Dónde está el dinero cuando el trade no se completó como se pidió: `wallet`, `trading_account` o `unknown` mientras una persona lo revisa. `null` en otro caso.

Opciones disponibles: `wallet`, `trading_account`, `unknown`

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

`perpetual` o `spot` para una orden, `perpetual` para un cierre. `null` para un depósito o retiro.

Opciones disponibles: `perpetual`, `spot`

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

El apalancamiento cruzado definido antes de una orden de apertura de perpetuo. `null` para una orden
spot, un cierre, un depósito, un retiro o una orden de solo reducción.

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

El mercado, por ejemplo `BTC` para un perpetuo o `XAUT` para spot. `null` para un
depósito o retiro.

**metadata** `object` *required*

Anotaciones libres de cadena a cadena almacenadas en el trade.

**object** `string` *required*

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

`market`, `limit`, `take_profit` o `stop_loss` para una orden. `null` en otro caso.

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

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

Para un take-profit o stop-loss enviado con una orden, el trade de esa orden,
con el prefijo `tint_`. `null` en otro caso.

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

El precio límite de la orden en USD. El precio de una orden de mercado es el precio medio desplazado por `slippage_bps`; el de un take-profit o stop-loss es el peor precio al que puede ejecutarse su orden de mercado una vez activada. `null` para otros tipos.

> [accordion] Propiedades
>
> **amount** `string` *required*
>
> El importe en unidades principales, como cadena decimal exacta. Por ejemplo, `"10.00"`
> son diez dólares. Es una cadena para que ningún número de coma flotante lo redondee en tránsito.
>
> **currency** `string` *required*
>
> Código de divisa ISO 4217 de tres letras, en minúsculas.
>
> **decimals** `integer` *required*
>
> Cuántos decimales tiene el importe. Es la precisión con la que se ejecuta
> el propio cargo.
>
> **display\_decimals** `integer` *required*
>
> Cuántos decimales se deben MOSTRAR. Normalmente es igual a `decimals`, y deliberadamente no siempre: COP se cobra en centavos pero se escribe en pesos enteros, por lo que es `2` y `0`. Usa esto para dar formato al número en tu propia configuración regional.

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

Si la orden solo puede reducir una posición. `null` para otros tipos.

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

`buy` o `sell` para una orden. `null` en otro caso.

Opciones disponibles: `buy`, `sell`

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

El tamaño de la orden en unidades del mercado, como cadena decimal. `null` para otros
tipos.

**status** `string` *required*

`pending` hasta que el trade empieza. `processing` mientras se ejecuta, y también mientras una orden que no se ejecutó devuelve a la billetera el dinero que transfirió por bridge. `completed` cuando hizo lo que se pidió. `failed` cuando no lo hizo; `funds_location` indica dónde está el dinero. `in_review` cuando el resultado es desconocido y una persona lo revisa.

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

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

`partial_fill` cuando la orden solo se ejecutó en parte de su tamaño. `null` en otro caso.

Opciones disponibles: `partial_fill`

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

Lo que está haciendo ahora un trade en curso: `depositing` mientras el USDT0 de la billetera se envía al bridge, `landing` una vez enviado y hasta que llega al saldo de trading, `placing` mientras la orden o el cierre está en el mercado, `withdrawing` mientras el USDC vuelve a la billetera, `returning` mientras vuelve el dinero que una orden no ejecutada transfirió por bridge. Una orden spot está en `quoting` mientras se cotiza el swap, en `swapping` mientras se ejecuta on-chain y en `crediting` hasta que el nuevo saldo aparece en la billetera. `null` una vez que el trade ya no está pendiente ni en proceso.

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

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

El precio en USD al que un take-profit o stop-loss envía su orden de mercado. `null` para otras órdenes y tipos.

> [accordion] Propiedades
>
> **amount** `string` *required*
>
> El importe en unidades principales, como cadena decimal exacta. Por ejemplo, `"10.00"`
> son diez dólares. Es una cadena para que ningún número de coma flotante lo redondee en tránsito.
>
> **currency** `string` *required*
>
> Código de divisa ISO 4217 de tres letras, en minúsculas.
>
> **decimals** `integer` *required*
>
> Cuántos decimales tiene el importe. Es la precisión con la que se ejecuta
> el propio cargo.
>
> **display\_decimals** `integer` *required*
>
> Cuántos decimales se deben MOSTRAR. Normalmente es igual a `decimals`, y deliberadamente no siempre: COP se cobra en centavos pero se escribe en pesos enteros, por lo que es `2` y `0`. Usa esto para dar formato al número en tu propia configuración regional.

**type** `string` *required*

`order` coloca una orden: una orden de perpetuo opera desde el saldo de trading y una orden spot intercambia entre USDT0 y el activo en la billetera. `deposit` transfiere por bridge USDT0 desde la billetera al saldo de trading. `withdraw` envía USDC desde el saldo de trading de vuelta a la billetera. `close` cierra toda la posición en un mercado con una orden de mercado de solo reducción; cuando la cuenta queda sin posiciones, un trade `withdraw` devuelve el saldo de trading a la billetera.

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

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

Cuándo cambió el trade por última vez, como marca de tiempo ISO 8601.

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

El usuario propietario de la billetera de trading, con el prefijo `user_`. `null` cuando su propietario
es una cuenta.

```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

- [Versiones de la API](https://docs.whop.com/es/developer/api/versioning.md)
- [Descripción general de la API de Whop](https://docs.whop.com/es/api-reference/overview.md)
- [API de miembros](https://docs.whop.com/es/api-reference/members/member.md)
