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

# Transfers API

> Transfer는 Whop 잔액 간에 자금을 이동합니다. 한 계정이나 사용자에서 다른 계정이나 사용자로, 계정의 지갑에서 개인이나 주소로, 또는 URL을 가진 누구나 수령할 수 있는 수령 링크로 이동합니다.

Transfers API를 사용하면 송금하고, 지급 가능한 수취인을 찾고, 자금 이동을 대사할 때 이체 목록을 조회하거나 개별 이체를 조회하고, 수령 링크를 미리 보거나 수령할 수 있습니다.

결과를 폴링하는 대신 `transfer.completed` 및 `transfer.failed`를 구독하세요. 참여하는 각 계정은 이 이벤트를 구독할 수 있습니다. `transfer.created`도 처리가 시작될 때가 아니라 성공 시에 발생합니다. 실패한 이체는 동일한 ID로 재시도되어 나중에 성공할 수 있으므로, 이체를 조회하여 현재 상태를 대사하세요.

성공한 잔액 이체는 릴리스 날짜가 적용되지 않는 한 수취인의 사용 가능 잔액에 입금됩니다. 대기 중 잔액에서 충당된 이체는 릴리스 날짜를 유지하며 대기 중 잔액에 입금됩니다. 해당되는 수취인 준비금이나 사기 방지 보류로 인해 자금을 사용할 수 없는 상태가 유지될 수 있습니다. `succeeded`는 이체가 완료되었음을 확인할 뿐, 모든 자금을 출금할 수 있음을 의미하지는 않습니다.

## 엔드포인트

| 엔드포인트 | 요청 |
| - | - |
| [수령 링크 조회](https://docs.whop.com/ko/api-reference/transfers/retrieve-claim-link.md) | GET `/claim_links/{id}` |
| [이체 목록 조회](https://docs.whop.com/ko/api-reference/transfers/list-transfers.md) | GET `/transfers` |
| [이체 조회](https://docs.whop.com/ko/api-reference/transfers/retrieve-transfer.md) | GET `/transfers/{id}` |
| [이체 수취인 목록 조회](https://docs.whop.com/ko/api-reference/transfers/list-transfer-recipients.md) | GET `/transfers/recipients` |
| [수령](https://docs.whop.com/ko/api-reference/transfers/claim.md) | POST `/claim_links/{id}/claim` |
| [이체 생성](https://docs.whop.com/ko/api-reference/transfers/create-transfer.md) | POST `/transfers` |

## 속성

**id** `string` *required*

이체 ID입니다.

**amount** `object | null` *required*

수취인에게 입금된 금액입니다. 이체가 성공하기 전까지는 null입니다.

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

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

이체가 생성된 시각입니다.

**destination** `object | null` *required*

이체를 받는 비즈니스 계정 또는 사용자입니다.

> [accordion] 속성
>
> **id** `string` *required*
>
> 계정 또는 사용자 ID입니다.
>
> **logo\_url** `string | null` *required*
>
> 비즈니스 로고 또는 사용자 아바타 URL입니다. 사용 가능한 이미지가 없으면 null입니다.
>
> **name** `string | null` *required*
>
> 비즈니스 또는 사용자 표시 이름입니다.
>
> **object** `string` *required*
>
> 프로필이 비즈니스 계정인지 사용자인지 여부입니다.
>
> 사용 가능한 옵션: `account`, `user`

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

기록된 실패 시각입니다. 이체가 실패한 경우가 아니면 null입니다.

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

기계가 읽을 수 있는 실패 코드입니다. 이체가 실패한 경우가 아니면 null입니다.

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

실패 설명입니다. 이체가 실패한 경우가 아니면 null입니다.

**fee** `object | null` *required*

플랫폼 마크업을 포함한 적용 가능한 모든 이체 수수료입니다. 권위 있는 합계를 사용할 수 없으면 null입니다.

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

**metadata** `object` *required*

이체에 첨부된 사용자 정의 메타데이터입니다.

**notes** `string | null` *required*

이체 메모입니다.

**object** `string` *required*

객체 유형입니다.

**origin** `object | null` *required*

이체를 보내는 비즈니스 계정 또는 사용자입니다.

> [accordion] 속성
>
> **id** `string` *required*
>
> 계정 또는 사용자 ID입니다.
>
> **logo\_url** `string | null` *required*
>
> 비즈니스 로고 또는 사용자 아바타 URL입니다. 사용 가능한 이미지가 없으면 null입니다.
>
> **name** `string | null` *required*
>
> 비즈니스 또는 사용자 표시 이름입니다.
>
> **object** `string` *required*
>
> 프로필이 비즈니스 계정인지 사용자인지 여부입니다.
>
> 사용 가능한 옵션: `account`, `user`

**status** `string` *required*

현재 이체 상태입니다. 이체는 `processing` 상태로 생성된 뒤 몇 초 후에 정산될 수 있습니다. 생성 응답을 최종 결과로 간주하지 말고, Retrieve Transfer를 폴링하거나 `transfer.completed` 및 `transfer.failed` 웹훅을 수신하세요. `succeeded`와 `failed`는 최종 상태입니다.

사용 가능한 옵션: `processing`, `succeeded`, `failed`

**status\_changed\_at** `string | null` *required*

현재 상태 전환이 기록된 시각입니다. 과거 전환 시각을 알 수 없으면
null입니다.

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

기록된 성공 시각입니다. 알 수 없으면 null입니다.

**tracking\_url** `string` *required*

이체 추적 페이지입니다. 보려면 로그인과 해당 이체에 대한 접근 권한이
필요합니다.

```json Transfer theme={null}
{
	"id": "ctt_xxxxxxxxxxxxxx",
	"object": "transfer",
	"status": "succeeded",
	"origin": {
		"id": "biz_xxxxxxxxxxxxxx",
		"object": "account",
		"name": "Pickaxe",
		"logo_url": null
	},
	"destination": {
		"id": "user_xxxxxxxxxxxxx",
		"object": "user",
		"name": "Alex Rivera",
		"logo_url": null
	},
	"amount": {
		"amount": "50.00",
		"currency": "usd",
		"decimals": 2,
		"display_decimals": 2
	},
	"fee": {
		"amount": "1.00",
		"currency": "usd",
		"decimals": 2,
		"display_decimals": 2
	},
	"created_at": "2026-06-01T12:00:00.000Z",
	"status_changed_at": null,
	"succeeded_at": null,
	"failed_at": null,
	"failure_code": null,
	"failure_reason": null,
	"notes": "Creator bonus",
	"metadata": {
		"external_transfer_id": "transfer_123"
	},
	"tracking_url": "https://whop.com/ctt_xxxxxxxxxxxxxx/"
}
```
