Skip to main content
Glama
bybit-exchange

Bybit MCP Server

Official
by bybit-exchange
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Remote

querySubMembersV5

Read-only

Retrieve a paginated list of all sub-accounts under a Bybit master account, including status, type, and UTA mode. Use the returned cursor to fetch additional pages.

Instructions

Query all sub-accounts of the master account with pagination support. Use master account's API key.

Important notes (from official Bybit V5 documentation):

  • Only master account can call this endpoint

  • Returns paginated list of sub-accounts with comprehensive information

  • Supports cursor-based pagination

  • Includes account status, type, and configuration details

  • Shows UTA (Unified Trading Account) mode for each sub-account

Required Permissions:

  • Master API key with appropriate permissions

Pagination:

  • Default page size: 100 (auto-set if not provided or <= 0)

  • Maximum page size: 100

  • Use nextCursor for fetching next page

  • Returns 0 as nextCursor when no more pages

  • First request: Use nextCursor=0 or omit

What information is returned:

  1. ✅ Sub-account UID and username

  2. ✅ Account type (1/4/6/14/15/16, see memberType field)

  3. ✅ Account status (normal, banned, frozen, deleted)

  4. ✅ Account mode (Classic, UTA 1.0/2.0, UTA Pro, Unified)

  5. ✅ Remark/notes for each sub-account

  6. ✅ Next cursor for pagination

Process Flow:

  1. Parse metadata from request context to get master account ID

  2. Validate pageSize (auto-adjust to 100 if invalid, error if > 100)

  3. If first page (nextCursor=0): Check for entrust trading team sub-accounts

    • Query "SPECIAL_EXCHANGE_MEMBER" tag to identify exchange members

    • Get entrust trading team sub-accounts via QueryEntrustMembersByExchangeID

    • Fetch their relationship data from member_relations table

  4. Get paginated sub-accounts via GetMemberRelationByPageV3

    • Adjusted page size = requested pageSize - entrust accounts count

    • Fetch from member_relations table ordered by ID

  5. Combine entrust accounts + regular sub-accounts

  6. Calculate nextCursor based on the DB-fetched count (before type=4 tag filtering): ID of last fetched sub-account if the fetched page is full (>= pageSize), else 0. Note: type=4 filtering happens after this step, so the finally returned count may be less than pageSize even when nextCursor is non-zero

  7. Fetch login names for all sub-accounts from member_login table

  8. Fetch 7 account tags in one query: UTA, UNIFIED, UTA_PRO, UTA_INVERSE, copytrade_upgrade, copytrade_mt5, enrolled_series_game. Account-mode uses UTA/UNIFIED/UTA_PRO/UTA_INVERSE; type=4 filtering uses 5 of them (copytrade_upgrade, copytrade_mt5, UTA, enrolled_series_game, UTA_INVERSE) — note UTA and UTA_INVERSE are shared by both determination

  9. Filter sub-accounts: return type=1/4/6/14/15/16; type=4 only when it has any of the 5 tags copytrade_upgrade/copytrade_mt5/UTA/enrolled_series_game/UTA_INVERSE

  10. Calculate account mode based on tag combinations

  11. Return sub-account list with nextCursor

Account Types:

  • Type 1: Normal sub-account - standard trading sub-account (MEMBER_RELATION_TYPE_OWN)

  • Type 4: Copy trading leader sub-account, only when it has any of the type-4 tags (MEMBER_RELATION_TYPE_COPY_TRADE_LEADER)

  • Type 6: Custodial sub-account - for institutional custody use (MEMBER_RELATION_TYPE_ENTRUST_TRADE)

  • Type 14: General AI sub-account (MEMBER_RELATION_TYPE_AI)

  • Type 15: Bycustody sub-account (MEMBER_RELATION_TYPE_BYCUSTODY)

  • Type 16: Bybit AI sub-account (MEMBER_RELATION_TYPE_INNER_AI)

Account Status:

  • Status 1: Normal (active)

  • Status 2: Login banned

  • Status 4: Frozen

  • Status 8: Deleted (soft delete)

Account Mode Determination Logic: The account mode is determined by checking member tags in the following priority:

  1. If both UTA_PRO=SUCCESS and UTA_INVERSE=SUCCESS → UTA 2.0 Pro (6)

  2. If UTA_INVERSE=SUCCESS → UTA 2.0 (5)

  3. If UTA_PRO=SUCCESS → UTA 1.0 Pro (4)

  4. If UTA=SUCCESS → UTA 1.0 (3)

  5. If UNIFIED=SUCCESS → Unified (7)

  6. Otherwise → Classic (1)

Special Features:

  • Entrust Trading Team Support: First page includes entrust trading team sub-accounts

  • Tag-based Mode Detection: Uses member_tags table to determine UTA status

  • Cursor-based Pagination: Efficient for large sub-account lists

  • Filtered Results: shows type=1/4/6/14/15/16 accounts (type=4 only when it has any of the type-4 tags)

Use Cases:

  • List all sub-accounts for management dashboard

  • Check sub-account statuses and modes

  • Audit sub-account configurations

  • Monitor UTA upgrade status across sub-accounts

  • Paginate through large numbers of sub-accounts

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
pageSizeNo
nextCursorNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv2.1.11

TDQS

A4.4/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already mark this as read-only, and the description adds substantial behavioral detail: cursor-based pagination semantics, page-size clamping and error behavior, type=4 tag filtering, account-mode priority logic, and special first-page entrust-team handling. It also discloses permission requirements. No contradiction with the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with headers, bullets, and numbered process steps, and the core purpose is front-loaded. However, it is very long and repeats several facts, such as type=4 filtering conditions and master-account restrictions, more times than necessary.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description compensates by listing exactly what is returned: sub-account UID, username, account type, status, mode, remark, and nextCursor. It also covers pagination details, account type/status mappings, and mode-determination logic, making the tool fully invocable.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema provides only types, defaults, and bounds; the description explains real semantics: pageSize is auto-set to 100 when invalid or <=0, errors if >100, nextCursor=0 starts the first page, and nextCursor=0 means no more pages. This is meaningful context the schema alone does not provide.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The opening sentence clearly states the action and resource: query all sub-accounts of the master account with pagination support. However, it does not differentiate this tool from similar siblings like querySubMembers, subMemberListQuery, or queryEscrowSubMembersV5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context: only master accounts can call, master API key is required, and it lists several concrete use cases. It does not mention alternatives or when not to use this tool, so it falls short of a 5.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server

Other Tools