Skip to main content
Glama
bybit-exchange

Bybit MCP Server

Official
by bybit-exchange
OverviewSchemaSourceRelated ServersScoreDiscussionsAdmin
TypeScript
Remote

querySubMembersV5

Read-only

List paginated sub-accounts for a Bybit master account, including status, type, and UTA mode, to manage and audit account configurations.

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 (normal=1 or custodial=6)

  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: ID of last sub-account if page is full, else 0

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

  8. Fetch account tags (UTA, UNIFIED, UTAPRO, UTAINVERSE) for account mode determination

  9. Filter sub-accounts: Only return type=1 (normal) and type=6 (custodial)

  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 6: Custodial sub-account - for institutional custody use (MEMBER_RELATION_TYPE_ENTRUST_TRADE)

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 UTAPRO=SUCCESS and UTAINVERSE=SUCCESS → UTA 2.0 Pro (6)

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

  3. If UTAPRO=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: Only shows type=1 and type=6 accounts

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?

The description goes far beyond the readOnlyHint annotation by disclosing pagination behavior (default/max page size, nextCursor meaning), response filtering (only type=1 and type=6), account mode determination logic, and special entrust trading team handling. It also details what data is returned and how the pagination cursor is computed. This is exceptionally transparent for a read-only query tool.

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 clear headers, but it is very long and contains implementation-level detail (e.g., 'GetMemberRelationByPageV3', 'member_relations table', 'member_login table') that an agent does not need to invoke the tool correctly. Some information is repeated across sections, so not every sentence earns its place. It is organized but not concise.

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?

Given the tool has no output schema, the description thoroughly covers what the response contains, including sub-account UID, username, type, status, mode, remarks, and nextCursor. It also explains permission requirements, pagination semantics, filtering rules, and edge cases like entrust trading team members. An agent has enough context to call this tool and interpret results correctly.

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?

Schema description coverage is 0%, so the description carries the full burden—and it delivers. It explains that pageSize defaults to 100, is auto-adjusted if invalid, errors if over 100, and that nextCursor should be 0 or omitted on the first request. It also clarifies that nextCursor returns 0 when no more pages exist, giving the agent everything needed to use both parameters correctly.

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 description clearly states the tool queries all sub-accounts of the master account with pagination support. It identifies the resource, action, and scope. However, it does not explicitly differentiate itself from closely related siblings like querySubMembers or subMemberListQuery, so it falls short of a 5.

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 usage context: only the master account can call the endpoint, the master account's API key must be used, and pagination is handled via cursor. It lists concrete use cases such as management dashboards and audits. However, it never explicitly explains when to choose this tool over sibling sub-account query tools, so it lacks exclusionary guidance.

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

Install Server

Other Tools