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

# Trades API

> Trade는 계정 또는 사용자의 Whop 관리형 지갑에 대한 하나의 요청입니다.

무기한 선물(perpetual)에 대한 `order`는 트레이딩 잔액으로 거래하며, 잔액이 부족하면 먼저 지갑에서 필요한 USDT0를 브리지합니다. 현물(spot)에 대한 `order`는 지갑에서 USDT0와 자산 간에 스왑합니다. `close`는 한 시장의 전체 포지션을 청산하며, 그 결과 계정에 포지션이 없으면 `withdraw` 거래가 트레이딩 잔액을 지갑으로 되돌려 보냅니다. `deposit` 또는 `withdraw`는 지갑과 트레이딩 잔액 간에 자금을 이동합니다. 무기한 선물은 Hyperliquid에서 거래됩니다.

Trades API를 사용하면 거래 가능한 시장 목록을 조회하고, 주문을 넣고, 포지션을 청산하고, 자금을 이동하고, 각 거래가 끝날 때까지 추적할 수 있습니다. 거래는 백그라운드에서 실행됩니다. 자금을 브리지해 들여왔지만 체결되지 않은 주문은 해당 자금을 지갑으로 되돌려 보내며, `funds_location`은 자금이 어디에 있는지 알려 줍니다.

계정과 사용자의 `include_trading`을 포함한 트레이딩 API는 베타 단계입니다. 새 API 버전 날짜 없이 변경될 수 있습니다.

## 엔드포인트

| 엔드포인트 | 요청 |
| - | - |
| [거래 목록 조회](https://docs.whop.com/ko/api-reference/trades/list-trades.md) | GET `/trades` |
| [거래 조회](https://docs.whop.com/ko/api-reference/trades/retrieve-trade.md) | GET `/trades/{id}` |
| [캔들 목록 조회](https://docs.whop.com/ko/api-reference/trades/list-candles.md) | GET `/trades/candles` |
| [시장 목록 조회](https://docs.whop.com/ko/api-reference/trades/list-markets.md) | GET `/trades/markets` |
| [거래 생성](https://docs.whop.com/ko/api-reference/trades/create-trade.md) | POST `/trades` |
| [거래 취소](https://docs.whop.com/ko/api-reference/trades/cancel-trade.md) | POST `/trades/{id}/cancel` |

## 시장

[시장 목록 조회](https://docs.whop.com/ko/api-reference/trades/list-markets.md)는 Whop에서 거래할 수 있는 모든 시장을 반환합니다.

* **현물:** 심볼별로 나열됩니다: `BTC`, `SOL`, `XAUT`(금).
* **무기한 선물:** `BTC` 등이 있으며, Hyperliquid의 `xyz` 거래소에서 제공하는 주식 및 원자재 무기한 선물(예: `xyz:TSLA`)도 포함됩니다. 거래를 생성할 때 `id`를 `market`으로 전송하세요.

같은 심볼이 무기한 선물과 현물로 각각 한 번씩, 두 번 나타날 수 있으므로 `id`와 `instrument_type`을 함께 사용하여 구분하세요. 결과는 `id`, 그다음 `instrument_type` 순으로 정렬됩니다.

이 엔드포인트는 공개되어 있습니다. API 키가 필요 없으며, 각 IP 주소는 분당 최대 60건의 요청을 보낼 수 있습니다.

무기한 선물 주문의 `size`는 소수점 이하 최대 `size_decimals`자리까지 가능하며, `leverage`는 최대 `max_leverage`까지 가능합니다. 현물 시장의 경우 `max_leverage`는 `null`입니다.

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

시장 목록은 트레이딩 API의 나머지 부분과 마찬가지로 베타 단계이며, 새 API 버전 날짜 없이 변경될 수 있습니다.

## 속성

**id** `string` *required*

`tint_` 접두사가 붙은 거래 ID입니다.

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

트레이딩 지갑을 소유한 계정으로, `biz_` 접두사가 붙습니다. 사용자가 소유한 경우
`null`입니다.

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

입금, 현물 매수 또는 트레이딩 잔액이 부족한 무기한 선물 주문이 지갑에서 보내는
USDT0, 또는 출금이 되돌려 보내는 USDC로, 기본 단위의 십진수 문자열입니다.
`all` 출금은 완료되면 실제로 보낸 금액을 표시합니다. 그 외에는 `null`입니다.

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

주문의 평균 체결 가격으로, USD 기준 십진수 문자열입니다. 현물의 경우
스왑 견적 가격입니다. 알 수 없으면 `null`입니다.

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

호출자가 지정한 거래 ID로, 계정 내에서 고유합니다. 보내지 않은 경우
`null`입니다.

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

거래가 완료 또는 실패로 종료된 시각으로, ISO 8601 타임스탬프입니다. 그 전에는
`null`입니다.

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

거래가 생성된 시각으로, ISO 8601 타임스탬프입니다.

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

Whop이 이 거래의 주문과 함께 거래소에 보내는 ID로, 거래소의 주문 업데이트를
거래와 대응시킬 수 있게 합니다. Hyperliquid에서는 `orderUpdates`에 보고되는 주문의
`cloid`이며, `0x` 접두사가 붙은 32자 16진수 문자열입니다. 호출자의
`client_order_id`가 아닙니다. 입금 또는 출금의 경우 `null`입니다.

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

거래가 실패한 이유이며, 없으면 `null`입니다.

사용 가능한 옵션: `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*

주문이 체결된 크기로, 시장 단위의 십진수 문자열입니다. 현물 매수의 경우
스왑 견적상 전달될 수량입니다. 체결되기 전까지는 `null`입니다.

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

거래가 요청대로 완료되지 않았을 때 자금이 있는 위치입니다. `wallet`, `trading_account`, 또는 담당자가 확인하는 동안은 `unknown`입니다. 그 외에는 `null`입니다.

사용 가능한 옵션: `wallet`, `trading_account`, `unknown`

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

주문의 경우 `perpetual` 또는 `spot`, 청산의 경우 `perpetual`입니다. 입금 또는 출금의 경우 `null`입니다.

사용 가능한 옵션: `perpetual`, `spot`

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

포지션을 여는 무기한 선물 주문 전에 설정된 교차 레버리지입니다. 현물 주문,
청산, 입금, 출금 또는 reduce-only 주문의 경우 `null`입니다.

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

시장으로, 예를 들어 무기한 선물은 `BTC`, 현물은 `XAUT`입니다. 입금 또는
출금의 경우 `null`입니다.

**metadata** `object` *required*

거래에 저장된 자유 형식의 문자열-문자열 주석입니다.

**object** `string` *required*

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

주문의 경우 `market`, `limit`, `take_profit` 또는 `stop_loss`입니다. 그 외에는 `null`입니다.

사용 가능한 옵션: `market`, `limit`, `take_profit`, `stop_loss`

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

주문과 함께 전송된 익절(take-profit) 또는 손절(stop-loss)의 경우, 해당 주문의 거래로
`tint_` 접두사가 붙습니다. 그 외에는 `null`입니다.

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

USD 기준 주문의 지정가입니다. 시장가 주문의 가격은 `slippage_bps`만큼 조정된 중간 가격이며, 익절 또는 손절의 가격은 트리거된 후 시장가 주문이 체결될 수 있는 최악의 가격입니다. 다른 유형의 경우 `null`입니다.

> [accordion] 속성
>
> **amount** `string` *required*
>
> 주 단위 금액이며, 정확한 십진수 문자열입니다. 예를 들어 `"10.00"`은 10달러입니다. 전송 중 부동소수점 반올림이 발생하지 않도록 문자열로 제공됩니다.
>
> **currency** `string` *required*
>
> 소문자로 된 세 글자 ISO 4217 통화 코드입니다.
>
> **decimals** `integer` *required*
>
> 금액이 갖는 소수 자릿수입니다. 실제 결제가 처리되는 정밀도입니다.
>
> **display\_decimals** `integer` *required*
>
> 표시할 소수 자릿수입니다. 일반적으로 `decimals`와 같지만, 의도적으로 항상 같지는 않습니다. COP는 센타보 단위로 청구되지만 페소 단위로 표기되므로 각각 `2`와 `0`입니다. 이 값을 사용하여 사용자의 로캘에 맞게 숫자를 포맷하세요.

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

주문이 포지션을 줄이기만 할 수 있는지 여부입니다. 다른 유형의 경우 `null`입니다.

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

주문의 경우 `buy` 또는 `sell`입니다. 그 외에는 `null`입니다.

사용 가능한 옵션: `buy`, `sell`

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

시장 단위의 주문 크기로, 십진수 문자열입니다. 다른 유형의 경우
`null`입니다.

**status** `string` *required*

거래가 시작될 때까지는 `pending`입니다. 실행 중에는 `processing`이며, 체결되지 않은 주문이 브리지해 들여온 자금을 지갑으로 되돌려 보내는 동안에도 마찬가지입니다. 요청한 작업을 수행하면 `completed`입니다. 그렇지 못하면 `failed`이며, `funds_location`이 자금 위치를 알려 줍니다. 결과를 알 수 없어 담당자가 확인하는 경우 `in_review`입니다.

사용 가능한 옵션: `pending`, `processing`, `in_review`, `completed`, `failed`

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

주문이 크기의 일부만 체결된 경우 `partial_fill`입니다. 그 외에는 `null`입니다.

사용 가능한 옵션: `partial_fill`

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

진행 중인 거래가 현재 수행 중인 작업입니다. `depositing`은 지갑의 USDT0를 브리지로 보내는 중, `landing`은 전송 후 트레이딩 잔액에 도달할 때까지, `placing`은 주문 또는 청산이 거래소에 있는 동안, `withdrawing`은 USDC가 지갑으로 돌아가는 중, `returning`은 체결되지 않은 주문이 브리지해 들여온 자금이 돌아가는 중입니다. 현물 주문은 스왑 가격을 산정하는 동안 `quoting`, 온체인에서 실행되는 동안 `swapping`, 새 잔액이 지갑에 표시될 때까지 `crediting`입니다. 거래가 더 이상 pending 또는 processing 상태가 아니면 `null`입니다.

사용 가능한 옵션: `depositing`, `landing`, `placing`, `withdrawing`, `returning`, `quoting`, `swapping`, `crediting`

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

익절 또는 손절이 시장가 주문을 보내는 USD 기준 가격입니다. 다른 주문 및 유형의 경우 `null`입니다.

> [accordion] 속성
>
> **amount** `string` *required*
>
> 주 단위 금액이며, 정확한 십진수 문자열입니다. 예를 들어 `"10.00"`은 10달러입니다. 전송 중 부동소수점 반올림이 발생하지 않도록 문자열로 제공됩니다.
>
> **currency** `string` *required*
>
> 소문자로 된 세 글자 ISO 4217 통화 코드입니다.
>
> **decimals** `integer` *required*
>
> 금액이 갖는 소수 자릿수입니다. 실제 결제가 처리되는 정밀도입니다.
>
> **display\_decimals** `integer` *required*
>
> 표시할 소수 자릿수입니다. 일반적으로 `decimals`와 같지만, 의도적으로 항상 같지는 않습니다. COP는 센타보 단위로 청구되지만 페소 단위로 표기되므로 각각 `2`와 `0`입니다. 이 값을 사용하여 사용자의 로캘에 맞게 숫자를 포맷하세요.

**type** `string` *required*

`order`는 하나의 주문을 넣습니다. 무기한 선물 주문은 트레이딩 잔액으로 거래하고, 현물 주문은 지갑에서 USDT0와 자산 간에 스왑합니다. `deposit`은 지갑의 USDT0를 트레이딩 잔액으로 브리지합니다. `withdraw`는 트레이딩 잔액의 USDC를 지갑으로 되돌려 보냅니다. `close`는 시장가 reduce-only 주문으로 한 시장의 전체 포지션을 청산하며, 그 결과 계정에 포지션이 없으면 `withdraw` 거래가 트레이딩 잔액을 지갑으로 되돌려 보냅니다.

사용 가능한 옵션: `close`, `order`, `deposit`, `withdraw`

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

거래가 마지막으로 변경된 시각으로, ISO 8601 타임스탬프입니다.

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

트레이딩 지갑을 소유한 사용자로, `user_` 접두사가 붙습니다. 계정이 소유한 경우
`null`입니다.

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