Skip to main content
A user signs in with one or more identities. Funds sit in one of several places: a managed wallet AGG signs for, the user’s own wallet, or an account on a single venue. This page names each one and links to the page that owns its procedure.

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 returns 409. 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.
  • evmAddress receives on every supported EVM chain and on Hyperliquid.
  • svmAddress receives 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.
Get deposit addresses. It returns { "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 as signingAddress. 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_tx signature.
  • 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.
Both kinds can be withdrawn from: pUSD in either can be paid out to any destination a self-custody withdrawal supports. A proxy wallet qualifies only when the EOA owns it. Proxy wallets from a Polymarket email login are owned by that login’s key, so they cannot be withdrawn from here. Which wallet places a Polymarket order. AGG picks one wallet per order, and the shares a buy fills land in that wallet:
  • 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_tx signature. 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 same polymarket 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.
    If the approval cannot be read, the order is refused with a retryable 503.
  • 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 with PUT /venue-keys and 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.

Glossary