Multi-currency wallets

Multi-currency is off by default. Existing integrations keep their USD transfer and payout flows. A brand can opt in for its managed sub-accounts through its server-side Connect API key. Live and sandbox have separate preferences.

This feature is in a gated pilot. Saving an opt-in does not override platform availability, account restrictions, or payout permissions. Read the returned enabled value before offering new conversions. No conversion quote guarantees an exact future exchange rate or destination amount.

1. Read or change the brand preference

Use the base URL https://app.sideshift.app/api/embed. Keep the key on your server; do not put it in the widget, browser, or mobile app.

BASE_URL="https://app.sideshift.app/api/embed"
curl "$BASE_URL/settings/currencies" \
  -H "x-api-key: $SIDESHIFT_CONNECT_KEY"

For the examples below, set BASE_URL to the base URL above. A new integration returns this shape; rolloutAvailable depends on platform availability:

{
  "success": true,
  "data": {
    "environment": "live",
    "multiCurrencyEnabled": false,
    "rolloutAvailable": false,
    "enabled": false
  }
}

Enable it for the environment selected by your key:

curl -X PATCH "$BASE_URL/settings/currencies" \
  -H "x-api-key: $SIDESHIFT_CONNECT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"enabled":true}'

The response has the same shape as GET. When the preference, platform rollout, and existing payout permission are all enabled, both multiCurrencyEnabled and enabled are true. If multiCurrencyEnabled is true but enabled is false, the preference was saved but new conversions are not available yet.

Field	Meaning
`environment`	`live` for `sk_live_`, `sandbox` for `sk_test_`.
`multiCurrencyEnabled`	The brand’s saved preference; missing settings mean `false`.
`rolloutAvailable`	Whether SideShift has made the feature available to this integration.
`enabled`	Whether the brand can request new estimates, quotes, and conversions, subject to each account’s checks.

PATCH accepts only a JSON boolean enabled. Do not send a company ID, account ID, environment, rollout field, or the string "true". The API key determines the brand and environment. Repeating the same PATCH is safe. This setting applies to all managed sub-accounts in that environment, not to other brands or linked personal accounts. It does not change USD transfers or other Connect settings.

2. Choose an amount and its units

The wallet catalog covers 84 fiat currencies. Crypto, stablecoin, and gold-token wallets are outside this feature. A listed currency does not guarantee that Whop can convert a particular pair or pay a particular bank account. The provider’s quote determines eligibility for the account, amount, method, and country. Amounts are integers in the currency’s minor units. The API retains the *Cents field names for USD compatibility; those names do not mean every currency has two decimals.

Currency	`decimals`	Desired amount	Integer amount
USD	2	$28.64	`2864`
EUR	2	€25.00	`2500`
JPY	0	¥2,500	`2500`
KWD	3	KWD 25.123	`25123`

For quote and convert, amountCents uses the source currency. For estimate, destinationAmountCents uses the target currency, and the returned amountCents always uses USD cents. Supported inputs range from 1 to 20,000,000 minor units. Account limits also apply to executed conversions using a USD valuation. Do not add balances in different currencies together.

3. Estimate the USD needed before funding

This example asks how much USD is needed to convert into about €25 inside a managed sub-account. Replace the account ID with its SideShift ID, not a Whop biz_* ID.

curl -X POST "$BASE_URL/accounts/currencies" \
  -H "x-api-key: $SIDESHIFT_CONNECT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "action":"estimate",
    "accountId":"YOUR_SUB_ACCOUNT_ID",
    "destinationCurrency":"eur",
    "destinationAmountCents":2500
  }'

Illustrative response, not a current rate:

{
  "success": true,
  "data": {
    "currency": "usd",
    "destinationCurrency": "eur",
    "amountCents": 2864,
    "destinationAmountCents": 2500,
    "estimatedReceivedCents": 2501,
    "feeBps": 0,
    "rate": "0.8735",
    "estimatedAt": "2026-09-23T12:00:00.000Z",
    "rateLocked": false,
    "fundingFeesIncluded": false
  }
}

The estimate works with an empty sub-account. It does not move or reserve money. It rounds the USD amount up and checks it with a forward conversion quote. amountCents is the total USD needed for this conversion, not a shortfall calculated after subtracting existing USD or foreign-currency balances. The quoted conversion cost is included in the net output. Funding and withdrawal fees are separate. Rates can change before funding arrives or conversion executes.

4. Fund the sub-account in USD

Use the existing transfer endpoint. The amount below is only the illustrative estimate above; use the amount returned by your request.

curl -X POST "$BASE_URL/accounts/transfer" \
  -H "x-api-key: $SIDESHIFT_CONNECT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "toAccountId":"YOUR_SUB_ACCOUNT_ID",
    "destinationBalance":"withdrawal",
    "amountCents":2864,
    "idempotencyKey":"order-123-usd-funding",
    "metadata":{
      "obligationType":"creator_agreement",
      "obligationReference":"agreement-123",
      "description":"Approved payment for completed creator work",
      "approvalReference":"approval-456"
    }
  }'

Use real commercial references. Existing authorization, funding fees, transfer limits, records, and completion events apply. Wait for transfer completion, then read the available provider balance. Pending funds and internal wallet-only credits cannot be converted. A successful estimate does not authorize a transfer.

5. Read balances and preview conversion

curl "$BASE_URL/accounts/currencies?accountId=YOUR_SUB_ACCOUNT_ID" \
  -H "x-api-key: $SIDESHIFT_CONNECT_KEY"

The response is { "success": true, "data": { ... } }. Data fields:

Field	Meaning
`accountId`	Managed SideShift sub-account ID.
`enabled`	New conversions are enabled for this account.
`visible`	Show currency controls; false keeps the existing USD wallet.
`balances`	Separate rows with `currency`, `decimals`, `availableCents`, `pendingCents`, and `reserveCents`.
`activities`	Recent provider activity, or `null` if history is unavailable.

An enabled wallet receives the full currency catalog, including zero balances. A brand that has never opted in receives visible: false and no currency rows; the existing USD wallet continues to supply its balance. After opt-out, funded foreign balances remain accessible. Missing provider data is not replaced with invented zero balances. Refresh the quote after funding arrives:

{
  "action": "quote",
  "accountId": "YOUR_SUB_ACCOUNT_ID",
  "currency": "usd",
  "destinationCurrency": "eur",
  "amountCents": 2864
}

POST this to /accounts/currencies. The quote returns amountCents, both currency codes, estimatedReceivedCents, feeBps, and rate. Show the estimate to the user. It is not a locked quote and does not spend money.

6. Convert after explicit confirmation

POST to the same endpoint:

{
  "action": "convert",
  "accountId": "YOUR_SUB_ACCOUNT_ID",
  "currency": "usd",
  "destinationCurrency": "eur",
  "amountCents": 2864,
  "acceptExecutionRate": true,
  "idempotencyKey": "order-123-conversion"
}

Use a different key from the funding transfer. The conversion executes within the sub-account. It does not transfer money to another account. Creators can also convert through their managed payout widget. Reverse conversion uses the same API with the source and destination currencies exchanged.

Result status	Client action
`completed`	Show the actual `receivedCents` when present; refresh balances.
`pending`	Keep the request body and key. Repeat the exact POST to check or resume it. HTTP status is 202.
`failed`	Show the error and check account history before starting another request.
`manual_review`	Stop automatic retries and contact SideShift with the `operationId`.

HTTP200 alone is not proof of completion. A timeout is not proof of failure. Never make a new conversion key to work around an unknown outcome. The server retains permanent request identities and stops provider retries after 23 hours. Changing an amount, account, currency, or other field under the same key is a conflict. A pending conversion blocks another conversion on that source account. Funding and conversion are separate: a declined conversion does not reverse a completed USD transfer.

7. Withdraw from the chosen currency

Use the managed payout widget. When multi-currency is enabled, it lets the creator select a source balance, choose a saved payout method, and review fees and delivery before confirming. The widget’s existing user token is scoped to that creator; it cannot change the brand’s multi-currency preference.

Same currency: a EUR balance paid to an eligible EUR destination stays in EUR. There is no FX leg, but a withdrawal fee can still apply.
Different currency: the provider quote supplies an exchange rate and an expected destination amount. The UI shows both.
Unavailable method or quote: do not submit a payout. Let the creator choose another supported method or retry the quote.

The server selects the source balance explicitly, validates the signed payout quote’s money fields, and passes its token to Whop. The confirmed destination amount is retained on retry; a new quote below that amount is refused. The internal widget withdrawal route uses a user bearer session, not the brand’s Connect API key. Do not call it as a new server-to-server Connect payout API. KYC, account restrictions, country eligibility, bank support, payout limits, and fees still apply. A currency in the catalog is not a promise that any bank can receive it. Payouts and their existing withdrawal events remain asynchronous.

Disable multi-currency

curl -X PATCH "$BASE_URL/settings/currencies" \
  -H "x-api-key: $SIDESHIFT_CONNECT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"enabled":false}'

New estimates, quotes, and conversions stop. Existing foreign balances remain visible and withdrawable; opt-out does not auto-convert or forfeit funds. Pending conversions continue through their original request key and reconciliation. The other environment is unchanged. To convert remaining funds, opt back in.

Errors and sandbox testing

Errors use { "success": false, "error": { "code": "...", "message": "..." } }. Keep the original operation key when the outcome may be unknown.

HTTP status	What to check
400	Strict request fields, boolean opt-in, supported code, integer units, range, and rate acceptance.
401	API key or session authentication.
403	Brand preference, rollout availability, payout permission, or account restrictions.
404	Managed account ID and ownership.
409	Payment-account setup, available balance, another pending operation, or a changed request under the same key.
5xx	Provider or service failure. Do not assume an attempted conversion failed.

Use a sandbox key to save the sandbox preference; it never enables live currency operations. Conversions require actual provider sandbox accounts and available sandbox funds. Legacy simulated USD transfers do not create those provider balances. Sandbox currency withdrawals are currently unavailable. The pilot remains disabled until live settlement and recovery checks are complete. Public quote success and automated tests do not prove that a bank payout settled.

​1. Read or change the brand preference

​2. Choose an amount and its units

​3. Estimate the USD needed before funding

​4. Fund the sub-account in USD

​5. Read balances and preview conversion

​6. Convert after explicit confirmation

​7. Withdraw from the chosen currency

​Disable multi-currency

​Errors and sandbox testing

1. Read or change the brand preference

2. Choose an amount and its units

3. Estimate the USD needed before funding

4. Fund the sub-account in USD

5. Read balances and preview conversion

6. Convert after explicit confirmation

7. Withdraw from the chosen currency

Disable multi-currency

Errors and sandbox testing