Wallet Mapping

Why Polymarket perps accounts use a different address than the profile you see, and how polynode resolves it for you automatically.

If you take a wallet address from a Polymarket profile, a leaderboard, or from polynode’s prediction-market endpoints and ask the perps exchange about it, you will usually get nothing back. This page explains why, and what polynode does about it.

Two addresses per user

Most Polymarket users trade prediction markets through a proxy wallet — a small smart contract deployed for them on Polygon. That contract address is their public identity: it is what appears on their profile page, on leaderboards, and in every prediction-market dataset (including polynode’s /v3 wallet endpoints).

The perps exchange identifies users differently: by the signer — the private-key account that controls the proxy. The signer is not shown on the Polymarket frontend, and there is no public endpoint that translates one into the other.

So a user’s prediction-market history lives under one address, and their perps account lives under another. Without the mapping, you cannot connect them.

What polynode does

Every perps wallet endpoint accepts either address form and resolves it server-side:

# Polymarket profile (proxy) address — resolved to the perps account automatically
curl "https://api.polynode.dev/v3/perps/wallets/0x09b428f7c2b469786286214aa5c90dd9015f7320?key=$KEY"

The response always tells you what was resolved:

{
  "input": "0x09b428f7c2b469786286214aa5c90dd9015f7320",
  "wallet_type": "deposit",
  "signer": "0x509e390373f5bde0bb02c1019ee39cf0ef23a1a4",
  "registered": false
}

The relationship between a proxy and its signer never changes, so once an address has been seen, repeat lookups are instant.

Wallet types

Polymarket has used a few different wallet types over the years, depending on how an account signed up. wallet_type tells you which one you’re looking at, using Polymarket’s own names:

wallet_type	Who has one	Resolution
eoa	Users trading with a plain wallet, no Polymarket contract at all.	The address is its own perps account.
deposit	Every new Polymarket account — the deposit wallet is the current standard.	Resolved automatically.
safe	Older accounts that signed up by connecting a browser wallet (MetaMask etc.) — these got a Gnosis Safe.	Resolved automatically.
proxy	Older accounts that signed up with an email login — these got a Polymarket Proxy.	Resolved automatically — see below.

”Deposit wallet” vs “beacon wallet”

If you’ve seen both terms: they’re the same thing. The deposit wallet is Polymarket’s current wallet type, and the newer ones are built so Polymarket can upgrade all of them at once — that upgradeable variant is what gets called a “beacon wallet”. There’s also an earlier, standalone variant from before that change. Both behave identically, both resolve automatically, and this API reports both simply as deposit — you never need to tell them apart.

Proxy wallets

Email-login accounts use a Polymarket Proxy wallet. These resolve automatically too — we maintain our own proxy-to-owner index covering these accounts from the beginning of Polymarket to the current block:

{
  "input": "0xf0318c32136c2db7fec88b84869aee6a1106c80c",
  "wallet_type": "proxy",
  "signer": "0x14dd4e61e9559e47277ffd19528ce8403ad9e861",
  "registered": false
}

In the rare case a proxy isn’t in the index yet (the index tails the chain continuously, so this window is small), the API returns a 422 instead of guessing:

{
  "error": "polymarket proxy wallet",
  "detail": "this is a Polymarket Proxy wallet (email-login accounts); its owner isn't in the owner index yet — pass the account's signer address directly",
  "address": "0x..."
}

If you have the account’s signer address from another source, pass it directly — everything works from there. A 422 address upgrades to full resolution automatically once the index covers it — just retry later.

Registration

Having a signer does not mean the user trades perps. Most Polymarket users have never activated a perps account. Check cheaply with:

curl "https://api.polynode.dev/v3/perps/wallets/0x.../registered?key=$KEY"

Once an account shows registered: true it stays that way; accounts that were false are picked up within minutes of activating, so newly onboarded perps users appear quickly.