Sign-in identity vs trading wallet
A person has one AGG user per app. That user can have several sign-in identities: Ethereum and Solana wallets, Google, Twitter, Apple, and email. Add more with Account linking. One identity belongs to one AGG user; linking it to a second user returns409.
Signing in does not choose where funds are held. A wallet used to sign in is only a self-custody
trading wallet when you pass it as signingAddress. Without that, every trade uses the managed
account.
Managed account
Each user gets a managed wallet with two addresses:evmAddress and svmAddress. AGG holds the
keys and signs every trade, bridge, and withdrawal. The user does not sign anything.
evmAddressreceives on every supported EVM chain and on Hyperliquid.svmAddressreceives on Solana.- Balances are tracked per chain and per token. A trade can spend from any chain; AGG moves the funds to the venue it routes to.
{ "ready": false } until the addresses exist; Funding & withdrawals owns the
poll, balances, and withdrawals.
Privy wallet provider. When your app uses Privy as its wallet provider, the managed wallet is
the user’s own Privy wallet instead of one AGG creates. AGG still signs, through the authorization
key you saved, with no user present. evmAddress is that Privy wallet. See
Privy wallet provider.
Self-custody
The user keeps their own key. Their EVM wallet, an EOA, must first be linked to the account with Account linking. Quotes and fills name it assigningAddress. AGG
prices the route against that wallet’s balances and asks it to sign each step. A Solana wallet
cannot be a signingAddress.
fundingAddresses names other linked EVM wallets the same trade may spend from. The signing wallet
still signs the venue order; each funding wallet signs only the transfers of its own money.
Self-custody is supported on these venues. Any other venue is refused at fill time.
Polymarket deposit wallet. Each linked EOA has one Polymarket deposit wallet. Its address is
derived from the EOA and stays fixed once AGG records it. Polymarket
orders are placed from it unless a legacy Safe places them (see below). A self-custody Polymarket
limit order needs it to exist already.
Its pUSD can also fund a Hyperliquid buy: AGG bridges it from Polygon to the EOA’s HyperCore
balance, and the EOA approves the move with one
eip712 signature. See
Self-custody trading.
Legacy Polymarket wallets. Some users have a wallet Polymarket created before AGG. AGG finds
the one Polymarket reports for the EOA, records it, and reads its balance. It reads one legacy wallet
per EOA. There are two kinds:
- Legacy Safe: a Gnosis Safe. Its balance can fund a trade on any venue. The EOA approves moving
funds out of it with a
safe_txsignature. - Legacy proxy: for trading, its balance can only be spent on Polymarket. Nothing moves it to another venue, and self-custody limit orders are refused for a wallet that has one.
- Buy: when the legacy Safe’s pUSD covers the whole Polymarket leg, the Safe places the order and
nothing moves. When it covers only part, the deposit wallet places the order and the Safe tops it
up with one
safe_txsignature. Otherwise the deposit wallet places it. - Sell: the order comes from the wallet that holds the position. An open position stays in the wallet AGG recorded it in. For shares bought outside AGG, AGG takes the wallet with more sellable shares, the deposit wallet on a tie. One sell never draws on both wallets: when the same outcome is held in both, only the chosen wallet’s shares are sold.
- Limit order: the Safe places it when its free pUSD (buy) or free shares (sell) cover the whole order. Otherwise the deposit wallet places it, and the Safe can move pUSD or shares into it first.
GET /execution/balances?custody=self lists each of these with a custodyKind of EOA,
DEPOSIT_WALLET, or POLYMARKET_LEGACY, plus legacyKind. A proxy row still counts in the
token’s totalRaw and availableRaw; subtract it to show what can be spent elsewhere. Kalshi cash
does not appear in this view.
Procedures: Self-custody trading and
Self-custody signing reference.
Polymarket Protocol V2 markets
Polymarket lists new markets on its Protocol V2 contracts. They come back from the same endpoints, under the samepolymarket venue, and are quoted and traded like any other Polymarket market. No
request or response field changes, and the SDK signs the orders AGG builds for them, so an
integration needs no code change. What differs for self-custody:
- One new approval per deposit wallet. Approvals for older Polymarket markets do not carry over. The first Protocol V2 trade from a deposit wallet, buy or sell, asks for one signature that sets up every Protocol V2 approval. Later Protocol V2 trades from that wallet ask for none. See Signing.
-
What that signature approves. Four grants, the same for a buy or a sell:
The AutoRedeemer (
0xa1200000d0002264C9a1698e001292D00E1b00af) is not approved. AGG redeems resolved positions itself, and an operator approval would let that contract move every position in the wallet. If an approval for an older Polymarket market is missing, it rides in the same signature. - Approvals already on-chain are not asked for again. Before every Polymarket trade, AGG reads the deposit wallet’s approvals on-chain and builds the setup signature from the missing ones only. When none are missing, and a buy needs no pUSD wrapped, no setup signature is asked for. A pUSD allowance counts as granted at 1,000,000 pUSD or more. On a Protocol V2 trade AGG reads the four grants above and the approvals for older markets. It does not read the AutoRedeemer.
-
Legacy wallets are not approved by AGG. AGG cannot grant a legacy Safe or proxy wallet
anything. It reads the one grant Polymarket requires for the order’s side: for a buy, the pUSD
allowance to ExchangeV3; for a sell, the PositionManager approval for ExchangeV3. With that
grant, the legacy wallet places the order itself. Without it:
- Buy, market or limit: refused before anything is placed or held, with a message telling the user to enable trading on polymarket.com. The legacy wallet makes every Polymarket buy for an account that has one, so the order does not move to the deposit wallet.
- Limit sell: placed from the deposit wallet when it holds enough free shares. Otherwise refused with the same message.
- Market sell of shares held in the legacy wallet: refused before anything is placed, with a message telling the user to approve trading on Polymarket.
-
Wallets that check what they sign. Orders are signed for Polymarket’s Protocol V2 exchange
(
0xe3333700cA9d93003F00f0F71f8515005F6c00Aa), and positions are held by its PositionManager (0x006F54F7f9A22e0000CC2AB60031000000ae9fEF). The setup signature also names the Protocol V2 Router (0x12121212006e4CD160D18e3f00711DA5c3372600). If your wallet code allowlists contract addresses, add all three.
Venue accounts
Some balances live inside a single venue and can only be spent there.- BetDEX hosted account. AGG creates and runs a BetDEX account for the user. It has its own Solana USDC deposit address, separate from the managed balance. See Hosted venue accounts.
- ProphetX and Novig direct accounts. When your app’s execution mode for that venue is
direct, the user stores their own venue credentials withPUT /venue-keysand trades with that account’s cash. AGG does not deposit, withdraw, or redeem those funds. See Market resolution. - Kalshi account. The user’s own Kalshi account and API key, stored with Venue keys. Every Kalshi trade, managed or self-custody, spends that account’s cash. See Kalshi.
Which mode, at a glance
Compare the trading flows in Choose your integration.