Master key versus sub-account key

If you're new to Binance Crypto-as-a-Service (CAAS / Link), one mistake shows up constantly:

using the wrong API key for the job.

CAAS is built on a simple account tree:

• Master account = the partner's Binance account (holds the CAAS permission).
• Sub-account = one Binance account per end user (balances, orders, deposit address).

That tree gives you two different credentials, and they are not interchangeable.

Master account API key = "run the broker"#

Use the master key for partner operations — basically everything under /sapi/v1/broker/*:

• Create / manage sub-accounts
• Issue, permission, IP-restrict, and delete sub-account API keys
• Enable Futures on a sub (before you create that sub's key)
• Move funds between master and subs (and, with the right setup, between subs)
• Set revenue-share commission / read rebates
• If you're on Markup: fee groups and markup reporting (also master-only)

Public docs also put external withdrawals on the master key. A sub-account cannot withdraw off-exchange. The usual pattern is: transfer sub → master, then withdraw from master.

Keep the master key on your backend only. It can create and delete accounts.

Sub-account API key = "act as one end user"#

Use the sub key for that one user's day-to-day crypto ops:

• Spot / futures / margin trading (main /api, /fapi, /dapi APIs — not the broker API)
• Fetch that user's deposit address and deposit history
• Open that user's user data stream (balances, orders, fills)

Important constraints newbies miss:

1. KYC first. You cannot create a sub API key until that sub's KYC has passed. Until then the sub is reduce-only (cut positions / withdraw paths as documented) — not a full trading account.
2. Enable Futures (or fund margin) before creating the key. futuresTrade / marginTrade are set at key creation. Create the key too early and Futures simply won't work — you'll need a new key.
3. No mega-stream. There is no single user-data stream for all your end users. Plan one stream per account per product family. Market data streams are different: public, no API key, one feed can serve everyone.
4. Options aren't in the CAAS sub-account permission set (docs: options not available to CAAS sub-accounts).

Mental model in one line#

Master key builds and funds the house. Sub key lives in one room and trades there.

Mixing them is the classic integration bug: calling broker endpoints with a sub key, or trying to trade / pull a deposit address with the master key "for" a user.

Capability matrix#

Public Binance Developer Docs only. A cell says Not stated where those docs are silent. This page does not fill the gap.

Yes means the docs say this key does it. No means the docs say it does not, or that it is the wrong key. N/A means it does not apply to that key's role. Separate means a different credential family, not the master or sub-account CAAS key.

The sections below are the full reading. On a narrow window the five-column tables scroll sideways.

Definitions · FAQ short rule · A. Accounts · B. Sub keys · C. Transfers · D. Deposits and withdrawals · E. Trading · F. Fees · G. KYC SaaS · H. Streams · I. Other · Not stated

How the docs define master vs sub#

Architecture, from the integration guide:

Your front end  →  Your backend  →  CAAS API (/sapi/v1/broker/*)     [master account API key]
                       └──────────►  Trading APIs (/api, /fapi, /dapi) [sub-account API key]

The docs call mixing the two credentials the most common integration mistake.

Short rule from the FAQ#

That is the FAQ's "Which API key do I use for which call?" The rows in A–I are the longer public-docs reading of the same split.

A. Account lifecycle (partner ops)#

B. Sub-account API key management (always master → broker)#

C. Internal fund movement (master ↔ sub / sub ↔ sub)#

D. External deposits & withdrawals (Wallet /sapi/v1/capital/*)#

E. Trading (main trading APIs — not /broker/*)#

F. Fees — revenue share vs Markup#

G. KYC SaaS (gates key creation)#

H. Streams & market data#

I. Other modules / ops notes#

57 capability rows, numbered 1–57, in sections A–I. The definition table and the FAQ short rule are not part of that count.

What the public docs do not state#

1. Full exhaustive permission bit list on a master key for non-broker routes. The docs focus on broker calls, withdrawals, and streams. A general line about "all secure routes" is security text, not a CAAS permission matrix.
2. Whether a sub key can call any /sapi/v1/broker/* endpoint. The docs say broker calls use the master key. They do not publish a negative permission dump.
3. The exact Travel Rule key for every /localentity/* path versus every /localentity/broker/* path, beyond "a partner can submit on an end user's behalf" and the FAQ's move of withdrawal to localentity/withdraw/apply.
4. Whether the master key can fetch a sub's deposit address on the capital endpoints. The docs prescribe the sub key for the address and for deposit history. Broker depositHist is the master read path.
5. How Institutional Buy/Sell Open API credentials map onto master versus sub CAAS keys. The docs describe a separate developer-account credential exchange.
6. The spot FAQ on Ed25519, HMAC, and RSA key types is not a master-versus-sub role matrix. The two topics are orthogonal.
7. Generic sub-account product intro pages are not the CAAS broker guide. For Link/CAAS, use the CAAS integration guide and the FAQ.

Tiny checklist#

• Master authenticates to broker info
• Sub created → KYC PASS → wallets enabled → then sub API key
• Sub key: narrow permissions + IP allowlist
• Deposits: sub address · Withdrawals: master (after sub→master transfer)
• Streams: one per account (plus public market data separately)

If you're screening CAAS as a buyer/builder, a structured diligence pass helps before you wire credentials: Getting started with Binance CaaS.

Independent personal project. Based on public Binance Developer Docs only. Not affiliated with Binance.