For developers. This page covers the technical integration. For what YaaS is, the model, and how
to apply, see the Yield-as-a-Service overview.
Prerequisites
- Crypto Lending enabled where it runs. Lending is available on the main account with B2B access; on sub-accounts it is not enabled by default — request enablement for each end-user sub-account via the account manager (see the overview). Until it is enabled, the lending endpoints are not available on that sub-account.
- A sub-account per end user, each with its own type:2 API key (info, trading, deposits, withdraws) — type:2 is required to run lending on a sub-account.
- Funds in the main account’s Main balance to allocate to each sub-account.
- HMAC-signed requests — see Authentication.
Integration building blocks
1. Provision a sub-account per end user
Create one sub-account per end user and issue that sub-account a type:2 API key. Sign both requests with the main-account key. Build with Sub-Accounts for account creation and key management, and the Embedded Trading integration guide for the full walkthrough (per-customer keys, KYC URLs).
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.
The 14-day deactivation of unused keys applies to sub-account keys too, and any
authenticated request with the key resets the timer. See API key lifecycle.
The partner’s backend enrolls each end user with the sub-account and API key steps of WaaS Wallet creation, plus the deposit-address step where the sub-account takes crypto deposits.
2. Fund the sub-account
Move funds from the main account’s Main balance to the end user’s sub-account with a fee-free transfer, signed with the main-account key.
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.
Run the check with POST /api/v4/sub-account/transfer/history, as in WaaS
Crypto purchases with fiat.
For crypto deposits to a sub-account, the partner’s backend polls the deposit history with the sub-account’s key, as in the deposit flow. Webhooks are optional.
3. Offer yield inside the sub-account
Run the Crypto Lending lifecycle — fetch plans, invest, track, withdraw — signed with the sub-account’s own key, so investments and Flex interest stay with that sub-account. The request and response fields are in the Crypto Lending quickstart (Flex) and, for Fixed, in the API reference linked from the Crypto Lending technical overview.The
main-account/ path segment addresses the signing account’s own Main balance — for a
sub-account key, that is the sub-account’s balance, not the main account’s. This is why a sub-account key
runs the lending lifecycle against that end user’s funds.
The partner’s backend places each investment in a flexible or a fixed plan and signs every call with the sub-account’s own key.
4. Reconcile earnings per user
Each sub-account’s investments and payment history are that end user’s earnings. There is no aggregated cross-sub report, so attribution is per sub-account — read each sub-account with its own key. An investment debits the sub-account’s Main balance (see Balances), andPOST /api/v4/sub-account/balances reports only the main, spot and collateral balances. The partner’s backend
reads open investments through the investments endpoints below.
The partner’s backend signs each lending call below with the sub-account’s own key and gets back only that sub-account’s records.
The partner’s backend reconciles each sub-account on a schedule against that end user’s ledger.
5. Redeem investments and pay out
The partner’s backend, signing with the sub-account’s key, withdraws part of a Flex investment or closes it by plan ID, and closes a Fixed investment by investment ID. Early closure of a Fixed investment follows the early-withdrawal terms in Crypto Lending plan types. From the sub-account’s Main balance, the funds follow the WaaS payment and payout flows:- Fiat payout — a transfer to the main account, then a payout from the partner’s own system, as in Crypto sales for fiat.
- Crypto withdrawal — created with the sub-account’s key and confirmed by the main account, as in Sub-account withdrawal approval. Available where the account manager has enabled sub-account withdrawals.
- Payout in another currency — Convert on the sub-account first, as in Conversion.
6. Offboard an end user
Invested funds do not show inPOST /api/v4/sub-account/balances (see
Reconcile earnings per user). Offboarding therefore starts with the sub-account’s
key. The partner’s backend lists and closes every active investment, then follows
End-user offboarding to empty and block the sub-account. A Fixed
investment closed before maturity follows the early-withdrawal terms in
Crypto Lending plan types. The sub-account’s key creates the final withdrawal
and the main account confirms it, as in
Sub-account withdrawal approval. The final
withdrawal is available where the account manager has enabled sub-account withdrawals.
Testing
WhiteBIT does not offer a public testnet or sandbox. Test on the live API with minimum amounts, and check available plans and per-plan minimums via the plans endpoints first.Reference
- Sub-Accounts — create and manage per-user accounts and keys.
- Crypto Lending — Fixed and Flex plan mechanics, supported assets, and the full endpoint reference.
- Crypto Lending quickstart — the invest, track, and withdraw lifecycle.
What’s next
FAQ
How B2B yield differs from the single-account flow.
Crypto Lending
Plan mechanics, supported assets, and the endpoint reference.
Sub-Accounts
Create and manage the per-user accounts this program provisions.