get_positions
Retrieve real-time position details for authenticated users on Bybit, filtering by category, symbol, base coin, or settle coin. Simplify trading analysis with structured data output.
Instructions
Get positions information for the authenticated user
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| baseCoin | No | Base coin. Used to get all symbols with this base coin | |
| category | Yes | Product type | |
| limit | No | Maximum number of results (default: 200) | |
| settleCoin | No | Settle coin. Used to get all symbols with this settle coin | |
| symbol | No | Trading symbol, e.g., BTCUSDT |
Implementation Reference
- src/tools/GetPositions.ts:79-133 (handler)The `toolCall` method provides the execution logic for the 'get_positions' tool: validates input using Zod schema, prepares parameters, fetches position data from Bybit API, formats the response, and handles errors.async toolCall(request: z.infer<typeof CallToolRequestSchema>) { try { this.logInfo("Starting get_positions tool call") // Parse and validate input const validationResult = inputSchema.safeParse(request.params.arguments) if (!validationResult.success) { throw new Error(`Invalid input: ${validationResult.error.message}`) } const { category, symbol, baseCoin, settleCoin, limit = "200" } = validationResult.data this.logInfo(`Validated arguments - category: ${category}, symbol: ${symbol}, limit: ${limit}`) // Prepare request parameters const params: PositionInfoParamsV5 = { category, symbol, baseCoin, settleCoin, limit: parseInt(limit, 10) } // Execute API request with rate limiting and retry logic const response = await this.executeRequest(async () => { return await this.getPositionsData(params) }) // Format response const result: FormattedPositionsResponse = { category, symbol, baseCoin, settleCoin, limit: parseInt(limit, 10), data: response.list, timestamp: new Date().toISOString(), meta: { requestId: crypto.randomUUID() } } this.logInfo(`Successfully retrieved positions data${symbol ? ` for ${symbol}` : ''}`) return this.formatResponse(result) } catch (error) { this.logInfo(`Error in get_positions: ${error instanceof Error ? error.message : String(error)}`) return this.handleError(error) } }
- src/tools/GetPositions.ts:39-70 (schema)The `toolDefinition` property defines the input schema, description, and metadata for the 'get_positions' tool, used for MCP tool listing and validation.toolDefinition: Tool = { name: this.name, description: "Get positions information for the authenticated user", inputSchema: { type: "object", properties: { category: { type: "string", description: "Product type", enum: ["linear", "inverse"], }, symbol: { type: "string", description: "Trading symbol, e.g., BTCUSDT", }, baseCoin: { type: "string", description: "Base coin. Used to get all symbols with this base coin", }, settleCoin: { type: "string", description: "Settle coin. Used to get all symbols with this settle coin", }, limit: { type: "string", description: "Maximum number of results (default: 200)", enum: ["1", "10", "50", "100", "200"], }, }, required: ["category"], }, }
- src/utils/toolLoader.ts:23-81 (registration)The `loadTools` function dynamically scans the src/tools directory, imports and instantiates tool classes like GetPositions, validating they extend BaseToolImplementation, and returns the list of loaded tools for registration.export async function loadTools(): Promise<BaseToolImplementation[]> { try { const toolsPath = await findToolsPath() const files = await fs.readdir(toolsPath) const tools: BaseToolImplementation[] = [] for (const file of files) { if (!isToolFile(file)) { continue } try { const modulePath = `file://${join(toolsPath, file)}` const { default: ToolClass } = await import(modulePath) if (!ToolClass || typeof ToolClass !== 'function') { console.warn(JSON.stringify({ type: "warning", message: `Invalid tool class in ${file}` })) continue } const tool = new ToolClass() if ( tool instanceof BaseToolImplementation && tool.name && tool.toolDefinition && typeof tool.toolCall === "function" ) { tools.push(tool) console.info(JSON.stringify({ type: "info", message: `Loaded tool: ${tool.name}` })) } else { console.warn(JSON.stringify({ type: "warning", message: `Invalid tool implementation in ${file}` })) } } catch (error) { console.error(JSON.stringify({ type: "error", message: `Error loading tool from ${file}: ${error instanceof Error ? error.message : String(error)}` })) } } return tools } catch (error) { console.error(JSON.stringify({ type: "error", message: `Failed to load tools: ${error instanceof Error ? error.message : String(error)}` })) return [] } }
- src/tools/GetPositions.ts:72-77 (helper)Private helper method `getPositionsData` that calls the Bybit API's `getPositionInfo` endpoint to retrieve raw position data.private async getPositionsData( params: PositionInfoParamsV5 ): Promise<APIResponseV3WithTime<{ list: PositionV5[] }>> { this.logInfo(`Fetching positions with params: ${JSON.stringify(params)}`) return await this.client.getPositionInfo(params) }
- src/index.ts:134-135 (registration)In the main function, `loadTools()` is called to load tools including 'get_positions', and `createToolsMap` populates the toolsMap used by MCP request handlers for tool listing and execution.const tools = await loadTools() toolsMap = createToolsMap(tools)