Wallet Identity (Polymarket)
Consolidated trader profile for any Polymarket wallet — display name, proxy and base address mapping, lifetime volume, lifetime and windowed PnL (24h, 7d, 30d), open-position value, trade count, largest win, and account age. One call turns a bare address into a full trader profile, including the proxy wallet needed for positions and activity lookups.
/v2/wallet/{addr}/identityQuery Parameters
Wallet address — must match ^0x[a-fA-F0-9]{40}$. Lowercased before lookup.
Response Schema
Wallet address (lowercased).
True if the wallet has a real Polymarket footprint (name, trades, volume, positions, or a recorded win). Lets you distinguish an active trader from an address that has never traded in a single field.
Polymarket proxy wallet address. Use this for /v2/wallet/{addr}/positions and /v2/polymarket/activity — the base/EOA address returns no results.
Funding (EOA) address behind the proxy.
Primary EVM address linked to the profile.
Profile URL slug — username for named accounts, address for anonymous ones.
True when the wallet has no public Polymarket username.
Public Polymarket display name. Null for anonymous wallets.
Public identity handle (same value as display_name).
Lifetime trading volume in USDC. Null when unavailable for the wallet.
Cumulative lifetime PnL in USDC, net of trading fees — the same figure shown on the trader's Polymarket P&L chart. Null for low-activity or anonymous wallets.
Net PnL over the last 24 hours, in USDC.
Net PnL over the last 7 days, in USDC.
Net PnL over the last 30 days, in USDC.
Current USDC value of all open positions.
Number of open positions.
Total number of trades.
Largest single-position win in USDC.
Profile page view count.
Account creation timestamp.
Source and cache state.
Data source identifier.
Whether the response was served from cache (hit), freshly resolved (miss), or the last-known cached value (stale).
Unix timestamp the cached entry was written.
Cache lifetime in seconds.
Error Responses
All errors return the same envelope. The code field is stable and programmatically branchable; error and message are human-readable. errors[] is present only on validation failures with field-level detail. See the full error code reference →
Always `false` on error responses.
Short, human-readable title (e.g. 'Invalid API Key.').
Human-readable explanation for the error. Safe to surface in UIs.
Stable, hierarchical machine-readable code (e.g. 'validation.invalid_enum'). Use for programmatic handling.
Link to this code's entry in the Error Reference.
Optional. Present only on validation failures with field-level detail.
Name of the offending parameter.
Field-level machine code.
Human-readable explanation.
Authentication
API Key
To secure your requests, we strongly recommend passing your API key via the X-API-Key header. This prevents sensitive keys from being exposed in access logs or browser history.
X-API-Key: pmx_test_5e8f...Rate Limits
API rate limits are enforced based on the tier associated with your API key. Limits are tracked on two dimensions: requests per second and requests per month. Each completed request counts toward the global monthly quota. Separate endpoint-group monthly limits (matched markets, arbitrage, EV) only advance when the response body has success: true.
Usage is returned on responses via headers such as:
X-RateLimit-Limit-Second: 10X-RateLimit-Remaining-Second: 9X-RateLimit-Limit-Month: 1000X-RateLimit-Remaining-Month: 842Example (endpoint-group, when applicable)X-RateLimit-Limit-Arb-Month: 500X-RateLimit-Remaining-Arb-Month: 412If you exceed a rate limit, the API returns a 429 status with a Retry-After header indicating when you can resume.
Request
Live API Key
Parameters
Response
—Click EXECUTE to send a request →