polymarket-mcp-server

Overview Schema Source Related Servers Discussions Admin

Get Polymarket wallet positions

polymarket_get_positions

Read-onlyIdempotent

Retrieve open positions and profit/loss for any public wallet address, including entry price, current value, and total portfolio value.

Instructions

Get the open positions and P&L for a public wallet address ("how is this wallet doing").

Returns each position's entry price, current price, current value and profit/loss, plus the wallet's total portfolio value. Read-only and public — anyone's positions are visible by address.

Args:

wallet (string): 0x… address (42 chars). The on-chain proxy wallet, not a username.
limit (number): max positions, 1-100 (default 25).
min_value (number): hide positions worth less than this USD (default 1, filters dust).
redeemable_only (boolean): only resolved positions ready to redeem (default false).
response_format ('markdown' | 'json'): default 'markdown'.

Returns: { wallet, portfolioValue, openPositions, totalCurrentValue, totalCashPnl, positions:[{ title, slug, outcome, conditionId, tokenId, size, avgPrice, curPrice, initialValue, currentValue, cashPnl, percentPnl, realizedPnl, redeemable, endDate }] }.

Errors: an invalid address is rejected before any request; an unknown wallet returns 0 positions.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`limit`	No	Max positions to return (1-100, default 25).
`wallet`	Yes	Public wallet address (0x…, 42 chars). This is the on-chain proxy wallet, not a username.
`min_value`	No	Hide positions whose current value is below this USD amount (default $1, filters dust).
`redeemable_only`	No	Only show resolved positions that can be redeemed (default false).
`response_format`	No	Output format: 'markdown' (concise, human-readable; default) or 'json' (full structured data).	markdown

Output Schema

TableJSON Schema

Name	Required	Description	Default
`wallet`	Yes
`positions`	Yes
`totalCashPnl`	Yes
`openPositions`	Yes
`portfolioValue`	Yes
`totalCurrentValue`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

First observedv1.0.0Sep 28, 2026

TDQS

A4.2/5.0

Behavior4/5

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

Annotations already cover the safety profile (readOnly, idempotent, openWorld, non-destructive), and the description adds genuinely useful context: public by address, invalid address rejected before any request, unknown wallet returns 0 positions, and dust filtering defaults. It doesn't cover pagination or rate limits, so it's short of a 5.

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

Conciseness4/5

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

Front-loaded with the purpose, then cleanly sectioned into Args and Returns. It is efficient, though the Args and Returns blocks largely duplicate the schema and output schema, costing a little redundancy.

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?

Covers purpose, all parameters, error conditions, and default behaviors; an output schema exists, so the extra Returns block is optional but harmless. Nothing needed to invoke this tool correctly is missing.

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

Parameters3/5

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

Schema description coverage is 100%, so the schema already documents every parameter including defaults, ranges and the proxy-vs-username caveat. The Args section essentially restates the schema without adding new semantics, which is the baseline 3 case.

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

Purpose5/5

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

States a specific verb and resource (get open positions and P&L for a wallet) plus the practical intent ("how is this wallet doing"). The word "open" implicitly distinguishes it from the sibling polymarket_get_closed_positions, and "public wallet address" separates it from activity/market tools.

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?

Clearly frames the use case (checking how an arbitrary public wallet is doing) and notes read-only/public visibility, which tells the agent it is safe to call on any address. However, it never names an alternative (e.g. get_closed_positions or get_user_activity) or states when NOT to use this tool.

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