Getting started with Binance CaaS

Getting started with Binance CaaS is gated. The public overview says availability depends on institutional onboarding, jurisdiction, the contracting entity, and the approved commercial model. That page points interested parties to link@binance.com or an account manager. This primer compresses that public documentation into the decisions a desk has to make before it spends engineering time. The product belongs to a third party. Primer Desk does not operate it, does not onboard anyone onto it, and does not speak for the publisher of the docs.

Who this is for#

Bank and broker product leads who have to place a white-label crypto API inside an existing control framework, and the family offices and crypto-native managers asked to approve that rail. The job is the meeting memo: which key signs which call, whether a sandbox exists, and whether a client account can withdraw. The seats are described on For desks. Custody, OTC, and fiat are a different screen, still empty on purpose: Custody, OTC, and fiat: the scorecard.

What this is not#

This is not official Binance documentation. Primer Desk is not affiliated with, partnered with, or employed by Binance. It is not an integration tutorial, a sandbox account, or a recommendation to use the product. A citation of the public CAAS pages is not access. Whether a buyer can use the product still depends on the vendor's onboarding, the buyer's jurisdiction, and the commercial model the vendor approves.

What you are buying#

CAAS is a backend API white-label. The overview describes a platform offering crypto functions without building an exchange, custody, wallet, trading, or settlement stack. Your application calls the vendor from your own backend. You build the front end. There is no vendor-hosted interface for end users.

The account model is a master plus sub-accounts.

• The master is the partner's own account. It holds the CAAS permission and parents every end-user account.
• Each end user is a sub-account created through the API. The overview treats that sub-account as a wallet with its own deposit address. Balances and orders sit there.
• A sub-account API key is a separate credential, scoped to that one user.

"We will white-label the exchange" is incomplete until someone can say which calls use the master key and which use the sub key.

Optional modules sit on that base and are enabled per partner. The overview names three: KYC SaaS, Markup, and the Institutional Crypto Buy/Sell Solution. Spot and futures are part of the base surface it lists. Travel rule applies only when sub-accounts sit under a local entity. A module named in a pitch and missing from that list stays out of scope until it has a public endpoint. Do not fill the gap from a slide.

The change log entry for 10 September 2026 is a documentation rename, not a behaviour change. "Exchange Link" is now presented as CAAS. "Link and Trade" is presented as OMS Toolkit. Paths moved under /products/caas/. The change log says old links redirect. A previously bookmarked Exchange Link introduction has also been observed to 404. Use the CAAS overview, and confirm any saved URL still resolves.

Get-started order#

The getting-started page publishes the sequence.

1. Finish onboarding and confirm the commercial model. Revenue share or markup. Not both.
2. Map each end user to one sub-account.
3. Create the sub-account. Store the id the call returns.
4. Run KYC and confirm it has passed.
5. Enable extra wallets, including futures, before the key. Margin has no enable endpoint. Getting started says the margin wallet is created by transferring any amount of an asset into it. Options are not available on CAAS sub-accounts.
6. Create the sub-account API key, then set permissions and IP restrictions.
7. Open user data streams for the accounts you need events from.
8. Prove operational readiness on a small set of real accounts before you onboard at volume.

KYC gates the key. The integration guide says key creation before a pass returns -9000 with a message that KYC has not been approved, and it gives a seven-day window to finish KYC and re-enable the sub-account. Until then the account is reduce-only: it can cut margin and futures positions and withdraw, and it cannot do the rest. The FAQ is sharper. Deposits are restricted. New spot orders are blocked and existing spot orders are cancelled. Futures and margin cannot open new risk. A non-KYC sub-account can send funds to the master or to a KYC'd sub-account, and cannot send them to another non-KYC sub-account. The master cannot deposit into a non-KYC sub-account.

The guide's path is share-kyc-data, then check-kyc-status, both under /bapi/ekyc/v2/public/ekyc/customer/. Pass means kycStatus of PASS on the current level.

Three KYC facts belong in the meeting, not in a later sprint.

• notifyUrl is mandatory. The FAQ says a single dot means "no notifications." The URL is bound to the KYC user id, there is no update endpoint, and a resubmission after rejection does not reset it. A dot sent to get moving cannot be replaced with a real webhook for that user. Point it at a stable endpoint you control. Failed deliveries retry at the 3rd, 5th, and 10th minute. Verify the signature before acting.
• The starting route is one-way. A record opened on the KYC URL cannot later move to KYC Sharing. A record opened through Sharing can be reset and redone on the page. If the hosted page might be needed, do not start on the URL.
• bizEntityKey is the partner's entity key, issued at onboarding, one per partner, required on every KYC SaaS call. entityCustomerId is your user id. Letters, numbers, and plus, hyphen, underscore, at-sign only. Keep it stable. One KYC user maps to one of those ids, and one person can be linked to at most five accounts.

-9000 is reused. The same code covers a missing parent-child link, and markup uses it when a sub-account has no fee group. Read the message.

Master key versus sub key#

The integration guide calls mixing the two credentials the most common integration mistake.

The master key signs every /sapi/v1/broker/ call — create accounts, transfer, commission — and it submits withdrawals. You create that key yourself. The onboarding checklist says the vendor does not issue it. It can create and delete accounts. It stays on your backend. Never in a browser or a mobile build.

The sub-account key trades for that one user, fetches that user's deposit address, and opens that user's stream. It does not withdraw to an external address.

Every CAAS endpoint is signed. There are no public CAAS endpoints. The key goes in X-MBX-APIKEY. Keys and secrets are case sensitive. Sign the exact bytes you send: re-encoding after the signature breaks it, and a space must be %20, not a plus. Sub-account keys may be HMAC, or Ed25519 or RSA if you pass publicKey at creation. The 18 April 2025 change log records that and links a public FAQ. IP restriction on the key you create is still your job. The guide names POST /sapi/v2/broker/subAccountApi/ipRestriction.

There is no CAAS sandbox#

CAAS, KYC SaaS, and Markup have no separate test environment. The readiness section says you verify on production, on a few real sub-accounts, with minimal balances.

Institutional Buy/Sell is the exception. It has a QA environment, and the docs say to start there. Ask the vendor's CaaS team for the QA base URLs. That QA covers the buy/sell module only. The CAAS accounts underneath are still production. A plan that treats those accounts as fake is wrong.

IP allowlisting follows the same split. CAAS itself does not require you to register calling IPs at onboarding. KYC SaaS and Institutional Buy/Sell do. Restrict every sub-account key anyway, and prove a caller outside the list is rejected before go-live.

Revenue share or markup, not both#

The model is fixed in onboarding and it changes which API you build. Getting started says revenue share or markup. The overview, the FAQ, and the markup guide all say the two cannot run together. Activating markup switches the referral rebate off. There is no dual-running period. Get the choice in writing before anyone designs a fee.

Revenue share#

Commission is set per sub-account API key, separately for spot, USD-M, and COIN-M. Rebates are queried, not assumed: one recent-record endpoint for spot and margin, another for futures. The FAQ says credit is ongoing rather than on a payout calendar, usually about 30 minutes after the trade. If a rebate is missing, check the delay, the link to the master, and eligibility including VIP level. Still missing after 24 hours, the FAQ says call the account manager.

The markup overview points at the 6 April 2022 Link tier announcement as the description of this system, and it works an example at 40 percent: the end client pays 0.10 percent maker/taker, 0.04 percent returns to the partner, 0.06 percent stays with the venue. That is the document's illustration. It is not a rate this primer says you will be offered. Read the announcement and confirm the live schedule.

Markup#

Case by case, on application through the address the overview names. Spot order book only. The same page's illustration marks the client up to 0.30 percent maker/taker, leaves 0.10 percent with the venue, and keeps 0.20 percent. Same caveat. An illustration, not an offer.

You do not set a rate on a user. You put users in a fee group and rate the group. Maker and taker are separate decimals: 0.002 is 0.2 percent. Both are required on an update.

• The Link team has to uplift markup on the master before the endpoints exist. Until then they are closed.
• Default cap is 3 fee groups, raisable to 20 on request. The maximum rate is per partner and is not published. Get it before you design tiers.
• The venue assigns groupCode. You do not. Later calls use the code, not the name. There is no rename. Persist the code.
• Members are spot UIDs, not the CAAS sub-account id. CAAS calls the id subAccountId. Markup calls it subUserId. Read uid from GET /api/v3/account using that sub-account's own key.
• Assign and unassign accept at most 10 ids. A larger batch returns -1102 and a message that looks like a missing parameter. Count the batch before you debug the JSON.
• HTTP 200 can be a partial assign. Read failedList. A sub-account in no group is not rejected. It trades at the base rate, with no markup and no rebate. The miss is silent. Querying that member returns -9000, "Markup configuration not found", which is an expected empty — and the same code also means the id is wrong or the account is not yours.
• Success is a wrapper whose code is nine zeros, 000000000, plus status, type, and data. Six zeros marks every success as a failure. Errors use the ordinary numeric envelope. Unwrap data. The 10 September 2026 change log records the correction.
• On JSON-body writes, sign the query string only. Signing the body as well returns -1022. Create-group is the exception: form body, and that body is part of the signature. The receive window may not exceed 60000.
• No BNB fee discount under a markup group. Only filled, settled spot trades accrue. tradeType on a detail row is the fill side that set the rate, not the order type you sent.
• Reporting is T-1 and requires an explicit window. Key a row by date, sub-account, and fee group together. Income lands on the master in USDT. Non-USDT pairs convert at the 00:00 UTC close of the trade date, and the partner bears that move — reconcile markupConvertRate, not a rate you recompute. A group that still has members cannot be deleted.

Withdrawals leave from the master#

Deposits can land on a sub-account. Fetch the deposit address with that sub-account's key. The master has a separate read-only deposit history. Withdrawals cannot. The integration guide and the FAQ agree: move funds from the sub-account to the master, then withdraw with the master key on POST /sapi/v1/capital/withdraw/apply.

Travel-rule entities do not use that plain call. The FAQ says to use POST /sapi/v1/localentity/withdraw/apply, which carries the travel-rule fields. Calling it for an entity outside the regime returns 103191203, "Not supported entity", and the FAQ says that result is expected. You cannot infer the tag from the registration country. Confirm it with the account manager. End-user tags need not match the master's. The integration guide also points at local-entity broker paths so a partner can file travel-rule data for an end user.

Internal transfers are four endpoints, not one.

• Spot, master to one sub-account or back: POST /sapi/v1/broker/transfer. Accepts clientTranId.
• Futures, same shape: POST /sapi/v1/broker/transfer/futures, with a type for USD-M or COIN-M. Accepts clientTranId.
• Across wallet types, or between two sub-accounts: POST /sapi/v1/broker/universalTransfer. The only one of the four that moves sub-to-sub. The sub-account key needs universal-transfer permission first. Account types are only SPOT, USDT_FUTURE, and COIN_FUTURE. Accepts clientTranId.
• Master against one sub-account's futures balance: POST /sapi/v1/broker/futures/accountTransfer. No clientTranId. A retry cannot be de-duplicated. Added in the change log on 22 September 2025.

clientTranId is the idempotency key wherever the endpoint accepts it. The change log caps it at 32 characters. Send one, and confirm history echoes it. The futures account-transfer call is the hole in that rule.

Streams, and what reconcile means#

CAAS publishes no stream of its own and none across end users. Each account opens its own, with its own key, per product. Spot plus USD-M is two sockets. The master's stream is treasury, not the client tape.

Spot uses the WebSocket API, with no listen-key URL. USD-M is wss://fstream.binance.com/private/ws/ plus the listen key — /private is required, because that host serves market data on other paths. COIN-M is wss://dstream.binance.com/ws/ plus the listen key. A public market-data socket is not a substitute.

A futures listen key lasts 60 minutes. PUT extends it. -1125 means it is gone. POST while one is live returns the same key. The socket dies at 24 hours anyway, so keepalive and reconnect are separate jobs. Missed events are not replayed. After every reconnect, re-read balances and open orders from REST. Do not share a listen key across accounts.

The buyer screen#

A blank line is a reason to stop. It is not a phase-two item.

Jurisdiction and entity#

• Contracting entity, and the entity tag on sub-accounts. The FAQ says you cannot infer the tag from registration country.
• Whether end-user tags match the master's.
• Which travel-rule regime applies, and therefore which withdrawal endpoint.
• Whether this seat can clear gated onboarding at all.

Commercial model#

• Revenue share or markup, in writing.
• Revenue share: live schedule, the rebate queries, the 30-minute lag, the 24-hour escalation.
• Markup: rebate confirmed off, uplift confirmed on the master, the unpublished rate cap, 3 groups or a written raise toward 20, income in USDT on the master, no BNB discount in the model.

Modules enabled#

• Spot, USD-M, COIN-M, margin, KYC SaaS, markup, institutional buy/sell. Optional modules are per partner.
• Options: not available.
• Buy/sell QA URLs in hand, with a note that the CAAS accounts under them are production.
• Anything named in a pitch and absent from the public overview: out of scope.

KYC path#

• Sharing or the KYC URL, with the one-way door understood.
• notifyUrl on an endpoint you control. Not a dot.
• bizEntityKey issued. entityCustomerId legal and stable.
• No API key until kycStatus is PASS. The seven-day reduce-only window is an operating procedure, including the 30-day appeal path for a deposit to an old address.

IP allowlists#

• Onboarding allowlist for KYC SaaS and for institutional buy/sell.
• CAAS itself does not require that registration. Restrict every sub-account key anyway.
• A recorded rejection of a caller outside the list, before go-live.

Idempotency#

• clientTranId on every transfer that accepts it, at most 32 characters, echoed in history.
• A different retry for futures account transfer, which has none.
• A 5XX is query-then-decide, not send-again.
• Markup assigns judged by failedList, not by HTTP 200.
• Markup income keyed by date, sub-account, and fee group, and by the convert rate when the asset is not USDT.

Stream reconnection#

• One stream per account per product, on that account's key. Master streams kept off the client trading path.
• 60-minute keepalive, and a 24-hour reconnect that does not rely on it.
• REST balances and open orders after every reconnect. Missed events are not replayed.
• USD-M on /private. COIN-M on the bare listen-key path.

If those seven blocks are not answerable from the public docs plus a written vendor reply, there is no integration plan. There is a demo.