get_user_positions
Retrieve current outcome share positions for any Hyperliquid user by providing their wallet address.
Instructions
Get current outcome share positions for a user
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| address | Yes | User wallet address |
Implementation Reference
- mcp-server.ts:221-222 (registration)Registration of the 'get_user_positions' tool with the MCP server via server.tool().
server.tool( 'get_user_positions', - mcp-server.ts:220-246 (handler)Handler function for 'get_user_positions'. Calls HL API 'spotClearinghouseState' and 'allMids', filters for outcome coins (# prefix) with non-zero balances, computes share values, and returns formatted text output.
// --- get_user_positions --- server.tool( 'get_user_positions', 'Get current outcome share positions for a user', { address: z.string().describe('User wallet address') }, async ({ address }) => { const [spotState, mids] = await Promise.all([ hlInfo<{ balances: { coin: string; total: string }[] }>({ type: 'spotClearinghouseState', user: address }), hlInfo<Record<string, string>>({ type: 'allMids' }), ]); const positions = spotState.balances .filter(b => b.coin.startsWith('#') && parseFloat(b.total) !== 0) .map(b => { const shares = parseFloat(b.total); const price = mids[b.coin] ? parseFloat(mids[b.coin]) : 0; const value = shares * price; return `${b.coin}: ${shares.toFixed(0)} shares @ ${(price * 100).toFixed(1)}% = $${value.toFixed(2)}`; }); if (positions.length === 0) { return { content: [{ type: 'text', text: 'No outcome positions.' }] }; } return { content: [{ type: 'text', text: positions.join('\n') }] }; }, ); - mcp-server.ts:224-224 (schema)Input schema: accepts a single 'address' parameter (string) describing the user wallet address.
{ address: z.string().describe('User wallet address') }, - mcp-server.ts:21-29 (helper)The hlInfo helper function used to make all HL API calls, including those in get_user_positions.
async function hlInfo<T>(body: object): Promise<T> { const res = await fetch(`${API_URL}/info`, { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(body), }); if (!res.ok) throw new Error(`HL API error: ${res.status}`); return res.json() as Promise<T>; }