Skip to main content
For developers. This page covers the technical integration. For what WaaS is, the verification variants at a business level, and how to apply, see the WaaS overview.
WaaS runs on Model A, a partner-operated sub-account per end user (see Integration models). Account creation, per-sub-account API keys, and KYC URLs are documented in Account architecture and Customer onboarding flow; this guide covers the wallet flows on top.

​
Prerequisites

  • Approved WaaS partner enrollment — see the WaaS overview for what WaaS provides and how to apply.
  • A chosen verification variant — managed sub-accounts, KYC reliance, or shared-KYC sub-accounts; see Build path per variant.
  • API access — HMAC-signed requests; a type: 2 API key (deposits and withdrawals) on each sub-account; crypto deposits to sub-accounts and the sub-account withdrawal endpoints enabled for the account by the account manager.
  • Sub-account limit — a main account holds up to 50 sub-accounts by default; the assigned account manager raises the limit on request.

​
Build path per variant

  • Managed sub-accounts. The partner creates a sub-account per end user under the main account (POST /api/v4/sub-account/create with shareKyc: false), and WhiteBIT verifies each end user through a KYC URL. Build with Sub-Accounts for account creation and management, and the customer onboarding flow for the KYC URL and per-customer API keys.
  • Sub-accounts with KYC reliance. The same sub-account architecture as the managed variant, but the partner performs end-user KYC instead of WhiteBIT, under a Compliance-approved agreement. Build with the same Embedded Trading integration guide; complete Institutional Onboarding first to establish the reliance agreement. See KYC reliance eligibility below for the conditions.
  • Shared-KYC sub-accounts. The partner creates a sub-account per end user with shareKyc: true, and each sub-account carries the main account’s verification. WhiteBIT verifies the partner during Institutional Onboarding (KYB); the partner verifies its own end users. No KYC URL or email confirmation applies, and the sub-account accepts permissions at creation. Build with Sub-Accounts and the Embedded Trading integration guide, skipping its end-customer KYC steps.
Commercial terms for the program: Revenue-share terms depend on the program. Embedded Trading partners earn a share of the trading fees that referred customers generate across all products, with payouts initiated by the partner, most commonly once per month — see WhiteBIT Embedded Trading for current rates. Other partner programs confirm commercial terms during onboarding.

​
KYC reliance eligibility

KYC reliance — WhiteBIT relying on the partner’s own customer verification — may be available, but is not enabled by default. It is never automatic, and operates as a delegation: responsibility for customer verification is never transferred. Eligibility is assessed case by case. Reliance is available only to partners that are supervised AML-obligated entities (for example EMI, PI, VASP, or MiCA-CASP license holders) in an adequate jurisdiction, applying broadly equivalent customer due diligence, under a written agreement and an individual WhiteBIT Compliance assessment. A confirmed entry on the relevant public register establishes the licensing basis; a confirmed EU/MiCA entity is additionally required when EU users are in scope. Licensing regimes and entity structures vary, and the examples above may not capture every case. Describe your licence(s), jurisdiction, and customer due-diligence approach in full in your application so the WhiteBIT Compliance team can review your specific situation and make a determination.

​
Payment and payout flows

Fund-movement mechanics, with parameters and code examples, are in the Sub-Accounts quickstart and the Payment Integration guide. Each diagram below covers one end user’s sub-account and names the key that signs each request: the main-account key or the sub-account’s own key.
Fiat deposits and withdrawals operate on the main account (institutional fiat access), from and to the partner’s own bank account only. End users’ fiat stays in the partner’s own system.
Compliance requirements that affect the requests:
  • EEA withdrawals require a travelRule object; in the sub-account models the partner submits it for each sub-account withdrawal it initiates. Inbound EEA/Turkey deposits are held until verification completes. See Travel Rule.
  • For EEA users, use USDC or EURI, not USDT. See Regulatory Compliance.

​
Wallet creation

Wallet creation runs once per end user: the sub-account, its type: 2 API key, and a deposit address per ticker and network. Managed sub-accounts add the KYC URL step from the customer onboarding flow, and shared-KYC sub-accounts skip it. WhiteBIT and the partner agree the KYC reliance setup during onboarding; see Build path per variant.

​
Deposits

The diagram follows one deposit from the address shown to the end user to a final status. A sub-account counts as a separate account and can have its own webhook. Webhook delivery is retried but has no replay, so poll the deposit history of each sub-account on a schedule as well, even when a webhook is configured. Use POST /api/v4/main-account/history with transactionMethod: 1, signed with the sub-account’s API key. Deduplicate by uniqueId. Act on each deposit status as the Deposit status state machine describes. Not every deposit ends credited: some end canceled, and some stay in status 21 (on hold) or 22 (uncredited) before reaching a final status. See Webhooks for signatures and delivery semantics. API rate limits apply per endpoint. A main account holds up to 50 sub-accounts by default; the assigned account manager raises the limit on request.

​
Crypto purchases with fiat

In a purchase, the partner debits the end user’s fiat in the partner’s own system and transfers the crypto from the main account to the sub-account. The transfer request takes no idempotency key. After a timeout or a 5xx response, check the transfer history for a record that matches the request and was created after the failed request was sent. Resend the transfer only when no such record exists. See Retry strategy by error type for the retry rule of each error type.

​
Crypto sales for fiat

In a sale, the partner transfers the crypto from the sub-account to the main account and credits the end user’s fiat once WhiteBIT confirms the transfer. The same transfer-history check applies before any resend.

​
Withdrawals

The sub-account’s type: 2 key creates each withdrawal, and the main-account key confirms it before processing starts. The account manager enables the sub-account withdrawal endpoints. Sub-account withdrawal approval gives the request for each approval step. Act on each withdrawal status as the Withdrawal status state machine describes.

​
Conversion

Conversion on a sub-account uses the requests in Convert balances and Conversion in the withdrawal flow, signed with the sub-account’s key, on the sub-account’s Trade balance. The partner transfers the source currency from the Main balance to the Trade balance and requests the estimate after the transferred amount shows on the Trade balance. Before a withdrawal, the partner transfers the converted amount back to the Main balance. The transfer to Trade needs the sub-account’s spot permission (spotEnabled). The main account’s one-time acceptance of the Convert terms on whitebit.com covers its sub-accounts; sub-accounts do not accept the terms separately.

​
API key lifecycle

The 14-day deactivation of unused keys applies to sub-account keys too, and any authenticated request, such as a deposit history poll, resets the timer. Only the create response returns the API secret. After a create request without a response, the partner checks the key list, deletes any key the request created, and creates the key again.

​
End-user offboarding

Offboarding empties the sub-account through a final withdrawal or a sale, then the main-account key blocks it. The sub-account’s key creates the final withdrawal and the main account confirms it, as in Withdrawals. A sale follows Crypto sales for fiat. The partner keeps the end user’s mapping to the sub-account and its addresses.

​
More flows

Additional use cases (conversion payouts, refunds, exact-amount payouts, multichain payouts) are catalogued in Recipes, with the full parameter reference in the Payment Integration guide. Travel Rule (programmatic): submit originator data via travel-rule/deposit/verification and fetch the VASP list via travel-rule/vasps (EEA and Turkey). See Travel Rule.

​
Testing

WhiteBIT does not offer a public testnet or sandbox. Test on the live API with minimum amounts, and check per-asset minimums via the Asset Status endpoint first. The WhiteBIT Codes flow is a low-risk way to try a real signed call on a small amount (see Recipes).

​
What’s next

WaaS Recipes

Runnable examples and the starter repo.

Payment Integration

Endpoint-level reference for every payment and payout flow.

FAQ

Scope, verification variants, onboarding, and compliance questions.