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

# Wallet

> Drives an account's money surfaces. `deposit` returns live funding rails; `send` moves money to a recipient or creates a public claim link; `withdraw` collects a payout request; `balances` holds two faces — the holdings list, and the balance block drawing value over a window; `cards` lists issued cards; and `activity` lists ledger movements. Every surface but `deposit` can use the viewer's session when no token is provided.

<Info>**Upcoming** — generated from the latest merged element source; documents unreleased development. Use the channel picker at the top of the sidebar for the docs of a published release.</Info>

*In development — not yet part of a stable release.*

## Playground

Assemble the elements with sample data — drive the controls, add and arrange elements, and watch events fire live:

<div data-whop-demo-shell style={{ position: "relative", minHeight: "480px", transition: "min-height 200ms ease" }}>
  <div data-whop-demo-skeleton style={{ position: "absolute", inset: "0", borderRadius: "12px", background: "rgba(140, 140, 140, 0.12)", pointerEvents: "none", transition: "opacity 200ms ease" }} />

  <div data-whop-demo-native="playground:wallet" data-whop-elements-version="" style={{ position: "relative" }} />
</div>

## Usage

<div data-whop-usage="wallet/playground">
  <CodeGroup>
    ```tsx React theme={null}
    import { WhopElements, Wallet } from "@whop/elements-react";
    import { loadWhop } from "@whop/elements";

    function Example() {
      return (
        <WhopElements elements={loadWhop()}>
          <Wallet /* options */>
            {/* mount elements here */}
          </Wallet>
        </WhopElements>
      );
    }
    ```

    ```html Vanilla theme={null}
    <script src="https://js.whop.cloud/elements/amber/elements.js" data-whop-elements></script>
    <script type="module">
      const wallet = window.WhopElements().wallet.create({ /* options */ });
    </script>
    ```
  </CodeGroup>
</div>

## Options

Pass these to `whop.wallet.create({ … })` — or as props on `<Wallet>` in React.

<ResponseField name="currency" type="string">
  ISO currency the amount field displays in. An unknown code falls back to USD. Defaults to `"usd"`.
</ResponseField>

<ResponseField name="accountId" type="string" required>
  Whose money these surfaces read: an account's `biz_…` tag, or a user's own `user_…` tag — a user reads their own balance, so their tag only answers for the viewer themselves.
</ResponseField>

<ResponseField name="appearance" type="Appearance">
  Visual customization for this group's elements — overrides the global `WhopElements({ appearance })`; change it live with `update({ appearance })`.
</ResponseField>

<ResponseField name="locale" type="WhopElementsLocale">
  Locale for this group's element UI text — one of the app's built locales, overriding the global config; any other value falls back to the default locale.
</ResponseField>

## Events

Pass a callback in the create options / React props.

### `onLoadingChange`

Fired when the grouped loading state changes — `true` while any mounted element is still loading.

**Signature:** `((loading: boolean) => void)`

## Methods

Call these on the Wallet handle — the return of `whop.wallet.create({ … })` (vanilla) or `useWallet()` (React).

### `update`

Update the handle live: any of its options (`appearance` and `locale` included), propagated to every mounted element. React consumers never call it — updating the namespace component's props does the same.

**Signature:** `(options: Partial<WalletOptions>) => void`

## Returned objects

Live objects returned by the methods above — hold the reference and call it on your page; these are capabilities, not serializable data.

## `DepositSavedCard`

A card the consumer already holds for this account — the element renders it as a funding row and hands the choice back through `cardDepositRequested`; it never charges a card itself.

### `id`

Payment-method id echoed back in `cardDepositRequested`.

**Signature:** `string`

### `label`

Row label, e.g. `Visa •••• 4242`.

**Signature:** `string`

### `cardBrand`

Brand key used to pick the row icon — `visa`, `mastercard`, `amex`, `discover`, `jcb`.

**Signature:** `string | null | undefined`

## `DepositCardFee`

The public surface of `DepositCardFee`.

### `percentageFee`

Percentage POINTS, not a fraction: `2.9` means 2.9%.

**Signature:** `number`

### `fixedFee`

Flat fee in major units: `0.3` means \$0.30.

**Signature:** `number`

### `radarFee`

Fraud-screening fee in major units.

**Signature:** `number`

## `SendRecipient`

The public surface of `SendRecipient`.

### `id`

**Signature:** `string`

### `name`

**Signature:** `string | null`

### `username`

**Signature:** `string | null`

### `profilePicUrl`

**Signature:** `string | null`

### `kind`

**Signature:** `"user" | "business" | "email"`

## `WithdrawalQuoteSpeed`

The public surface of `WithdrawalQuoteSpeed`.

### `estimatedArrival`

**Signature:** `string | null | undefined`

### `fee`

**Signature:** `number`

### `totalReceived`

**Signature:** `number`

### `currency`

**Signature:** `string | undefined`

### `destinationCurrency`

**Signature:** `string | undefined`

### `exchangeRate`

**Signature:** `number | undefined`

### `minLimit`

**Signature:** `number | undefined`

### `maxLimit`

**Signature:** `number | null | undefined`

## `WithdrawalQuote`

The public surface of `WithdrawalQuote`.

### `amount`

**Signature:** `number`

### `currency`

**Signature:** `string`

### `destinationCurrency`

**Signature:** `string`

### `exchangeRate`

**Signature:** `number`

### `minLimit`

**Signature:** `number`

### `maxLimit`

**Signature:** `number | null | undefined`

### `standard`

**Signature:** `WithdrawalQuoteSpeed | null | undefined`

### `instant`

**Signature:** `WithdrawalQuoteSpeed | null | undefined`

## `WithdrawalMethod`

The public surface of `WithdrawalMethod`.

### `id`

**Signature:** `string`

### `nickname`

**Signature:** `string | null | undefined`

### `accountReference`

**Signature:** `string | null | undefined`

### `payerName`

**Signature:** `string | null | undefined`

### `destinationCurrency`

**Signature:** `string`

### `isDefault`

**Signature:** `boolean`

### `iconUrl`

**Signature:** `string | null | undefined`

### `deliveryType`

**Signature:** `string`

### `supportsStandard`

**Signature:** `boolean`

### `supportsInstant`

**Signature:** `boolean`

### `bankVerificationState`

**Signature:** `string | null | undefined`

### `feeStructure`

**Signature:** `{ percentage: number; fixedAmount: number; currency: string; } | null | undefined`

### `standardEstimatedArrival`

**Signature:** `string | null | undefined`

### `instantEstimatedArrival`

**Signature:** `string | null | undefined`

### `quote`

**Signature:** `WithdrawalQuote | null | undefined`

## `WithdrawalRequiredField`

The public surface of `WithdrawalRequiredField`.

### `id`

**Signature:** `string`

### `label`

**Signature:** `string`

### `inputType`

**Signature:** `string`

### `required`

**Signature:** `boolean`

### `sensitive`

**Signature:** `boolean`

### `placeholder`

**Signature:** `string | null | undefined`

### `validation`

**Signature:** `string | null | undefined`

### `options`

**Signature:** `string[] | null | undefined`

## `WithdrawalSupportedMethod`

The public surface of `WithdrawalSupportedMethod`.

### `id`

**Signature:** `string`

### `name`

**Signature:** `string | null | undefined`

### `iconUrl`

**Signature:** `string | null | undefined`

### `deliveryType`

**Signature:** `string`

### `supportsStandard`

**Signature:** `boolean`

### `supportsInstant`

**Signature:** `boolean`

### `supportsPlaid`

**Signature:** `boolean | undefined`

### `quotes`

**Signature:** `WithdrawalQuote[]`

### `requiredFields`

**Signature:** `WithdrawalRequiredField[]`

## `WithdrawalLimits`

The public surface of `WithdrawalLimits`.

### `standard`

**Signature:** `{ maxAmount: number; errorMessage?: string | null | undefined; }`

### `instant`

**Signature:** `{ maxAmount: number; dailyAmountRemaining?: number | null | undefined; errorMessage?: string | null | undefined; }`

## `WithdrawalCreateMethodInput`

The public surface of `WithdrawalCreateMethodInput`.

### `country`

**Signature:** `string`

### `supportedPayoutMethodId`

**Signature:** `string`

### `destinationCurrency`

**Signature:** `string`

### `nickname`

**Signature:** `string`

### `fields`

**Signature:** `Record<string, string>`

## `WithdrawalRequest`

The public surface of `WithdrawalRequest`.

### `amount`

**Signature:** `number`

### `currency`

**Signature:** `string`

### `payoutMethodId`

**Signature:** `string`

### `presentedFee`

**Signature:** `number`

### `speed`

**Signature:** `"standard" | "instant"`

### `acknowledgeBankWarning`

**Signature:** `boolean | undefined`

## `ActivityDateRangeOverride`

The public surface of `ActivityDateRangeOverride`.

### `start`

**Signature:** `string`

### `end`

**Signature:** `string`

### `includeTime`

**Signature:** `boolean | undefined`

### `postedAfter`

**Signature:** `string | undefined`

### `postedBefore`

**Signature:** `string | undefined`

### `displayPostedAfter`

**Signature:** `string | undefined`

### `displayPostedBefore`

**Signature:** `string | undefined`

## `LedgerActivity`

The public surface of `LedgerActivity`.

### `object`

**Signature:** `"ledger_activity"`

### `id`

Ledger activity ID.

**Signature:** `string`

### `line_type`

The ledger line category this activity was posted under.

**Signature:** `"ad_budget_release" | "ad_campaign_budget" | "ad_publisher_payout" | "ad_publisher_payout_received" | "ad_spend_charge" | "affiliate_fee" | "airdrop" | "airdrop_link_created" | "airdrop_link_redeemed" | "airdrop_link_returned" | "airdrop_reversal" | "application_fee" | "application_fee_payout" | "bank_transfer" | "billing_percentage_fee" | "buyer_fee" | "card_spend_authorization" | "card_spend_authorization_void" | "card_spend_refund" | "company_referral" | "cross_border_percentage_fee" | "currency_conversion_incoming" | "currency_conversion_outgoing" | "dispute_alert_fee" | "dispute_hold_adjustment" | "fraud_prevention_fee" | "fx_percentage_fee" | "high_risk_merchant_fee" | "installment_default" | "internal_balance_transfer_incoming" | "internal_balance_transfer_outgoing" | "legacy_crypto_payment" | "legacy_payment" | "legacy_payment_refund" | "license_sale" | "license_sale_commission" | "license_sale_revenue" | "misc_purchase" | "misc_refund" | "misc_reversal" | "onchain_deposit" | "onchain_swap_target" | "onchain_wallet_transfer_incoming" | "onchain_wallet_transfer_outgoing" | "orchestration_percentage_fee" | "passthrough_gmv" | "payment_dispute" | "payment_dispute_adjustment" | "payment_dispute_fee" | "payment_dispute_reversal" | "payment_gross" | "payment_gross_reversal" | "payment_processing_fixed_fee" | "payment_processing_percentage_fee" | "payment_referral" | "payment_referral_reversal" | "payment_refund" | "payment_refund_reversal" | "payment_revshare" | "payment_revshare_payout" | "payment_revshare_refund" | "payment_revshare_reversal" | "payout_fee" | "platform_affiliate_payment" | "platform_affiliate_payment_reversal" | "platform_balance_payment" | "platform_balance_payment_refund" | "platform_balance_transfer_incoming" | "platform_balance_transfer_outgoing" | "platform_covered_dispute" | "promo_reversal" | "referral_bonus" | "resolution_center_refund" | "revshare_percentage_fee" | "sales_tax_fee" | "sales_tax_remittance" | "sales_tax_remittance_reversal" | "software_rental_revshare" | "software_rental_transaction" | "stripe_domestic_processing_fee" | "stripe_international_processing_fee" | "three_ds_fixed_fee" | "topup" | "topup_fee" | "topup_reversal" | "treasury_payin" | "whop_processing_fee" | "withdrawal" | "withdrawal_clawback" | "withdrawal_clawback_reversal" | "withdrawal_reclassification" | "withdrawal_reversal"`

### `amount`

Signed amount in the currency's smallest precision units.

**Signature:** `string`

### `currency`

Currency for this ledger activity.

**Signature:** `{ code: string; precision: string; }`

### `posted_at`

When the activity posted to the ledger.

**Signature:** `string`

### `available_at`

ISO 8601 timestamp these funds became (or are scheduled to become) withdrawable: the posted time for already-settled funds, or 00:00:00 UTC on the scheduled release date for pending funds. Present only on inflows entering the balance (payments, top-ups, incoming transfers/affiliate); null on withdrawals, refunds, disputes and on-chain rows. The available\_after/before filters window on its UTC settlement date.

**Signature:** `string | null`

### `created_at`

When the activity record was created.

**Signature:** `string | null`

### `resource`

Resource associated with this ledger activity.

**Signature:** `{ object: "account"; id: string; title: string | null; route: string | null; logo_url: string | null; } | { object: "user"; id: string; name: string | null; username: string | null; profile_picture_url: string | null; } | { object: "bounty"; id: string; title: string; status: string; } | { object: "ledger_account"; id: string; owner: { object: "account"; id: string; title: string | null; route: string | null; logo_url: string | null; } | { object: "user"; id: string; name: string | null; username: string | null; profile_picture_url: string | null; } | null; } | { object: "payment_method"; id: string; payment_method_type: string | null; gateway_type: string | null; card: { brand: string | null; last4: string | null; exp_month: number | null; exp_year: number | null; } | null; bank: { bank_name: string | null; account_name: string | null; last4: string | null; account_type: string | null; } | null; email_identifier: string | null; } | { object: "payout_method"; id: string; nickname: string | null; institution_name: string | null; account_reference: string | null; provider: string | null; destination_currency_code: string | null; } | { object: "card_transaction"; id: string; card_id: string | null; merchant_name: string | null; merchant_icon_url: string | null; merchant_category: string | null; status: string | null; usd_amount: string | null; local_amount: string | null; local_currency: string | null; cashback_usd: string | null; authorized_at: string | null; posted_at: string | null; declined_reason: string | null; } | null`

### `source`

Source of this ledger activity.

**Signature:** `{ object: string; id: string; status?: string | null | undefined; reason?: string | null | undefined; claim_url?: string | null | undefined; amount_float?: number | null | undefined; created_at?: string | null | undefined; estimated_arrival?: string | null | undefined; payer_name?: string | null | undefined; payout_token_nickname?: string | null | undefined; tx_hash?: string | null | undefined; sender_address?: string | null | undefined; chain?: string | null | undefined; from_amount?: string | null | undefined; from_currency?: string | null | undefined; to_amount?: string | null | undefined; to_currency?: string | null | undefined; payout_destination?: { payer_name?: string | null | undefined; icon_url?: string | null | undefined; } | null | undefined; [key: string]: unknown; } | null`

### `account`

The viewer account that owns this row's ledger. Present only when the response aggregates owned accounts (include\_owned\_accounts=true); omitted otherwise.

**Signature:** `{ object: "account"; id: string; title: string | null; route: string | null; logo_url: string | null; } | { object: "user"; id: string; name: string | null; username: string | null; profile_picture_url: string | null; } | undefined`

### `ledger_account_id`

The ledger account (a ldgr\_ identifier) this row belongs to. Present only when the response aggregates owned accounts (include\_owned\_accounts=true); omitted otherwise. Pair it with `account` to scope drawers and dashboard links to the owning business.

**Signature:** `string | null | undefined`

## Elements

The elements this group mounts — each has its own page:

<CardGroup cols={2}>
  <Card title="DepositElement" href="/elements/upcoming/wallet/deposit">
    Funds a Whop account. Renders an amount field and the account's live funding rails — crypto (a per-network deposit address with its QR) and bank transfer (the wire fields for each settlement currency) — resolved from the account id with no credentials, so it works on any page. Pass `savedCards`, `allowNewCard`, or `showPlatformBalance` to offer rails you settle yourself: the element collects the amount and the choice, then emits `cardDepositRequested` / `addCardRequested` / `platformBalanceSelected` and waits for you to call `showStep({ step: 'amount' })` when your own screen is done.
  </Card>

  <Card title="SendElement" href="/elements/upcoming/wallet/send">
    Sends money from an account to a recipient — a user, another business, or a public claim link anyone can redeem. Renders its own recipient search resolved from the account id with no credentials beyond the account's own token. Needs an `accessToken` scoped to `payout:withdraw_funds`; business recipient search additionally needs `company:authorized_user:read` and `member:basic:read`, and business claim links need `airdrop_link:manage` — a host without one of those scopes should turn off the matching prop rather than leave a row that will 403.
  </Card>

  <Card title="CardsElement" href="/elements/upcoming/wallet/cards">
    Lists the account's active issued cards, most recently issued first. Needs an `accessToken`. The title and rows are click targets that emit events instead of navigating — a host wires up its own routing and card-detail UI.
  </Card>

  <Card title="WithdrawElement" href="/elements/upcoming/wallet/withdraw">
    Collects a withdrawal amount and saved payout method, groups standard and instant delivery choices with live fees and arrival estimates, collects a new payout method when needed, and presents a confirmation screen before emitting the final withdrawal request.
  </Card>

  <Card title="ActivityElement" href="/elements/upcoming/wallet/activity">
    Lists an account's ledger activity — every movement of money in or out — with a type and date-range filter the viewer can work with directly. Needs an `accessToken`. Rows are click targets that emit `activitySelected` instead of navigating — a host wires up its own routing and detail views. A host driving its own date-range picker (a chart brush selection, say) can call `setDateRange` to set the filter, and should listen for `dateRangeChanged` to know when the viewer overrides it directly.
  </Card>

  <Card title="Balances" href="/elements/upcoming/wallet/balances">
    An account's money as two faces: the holdings list, and the balance block — the figure, the line it moved along, and the window picker. Mount either or both; the wallet handle's account reaches both, and each takes its own token (or the viewer's session same-origin). *(sub-controller — 2 elements)*
  </Card>
</CardGroup>