Accounts & wallets

A user signs in with one or more identities. Funds sit in one of several places: a managed wallet sufwan-local-test 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 walletCopy Anchor Link

A person has one sufwan-local-test 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 sufwan-local-test 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 accountCopy Anchor Link

Each user gets a managed wallet with two addresses: evmAddress and svmAddress. sufwan-local-test 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; sufwan-local-test moves the funds to the venue it routes to.

const deposit = await client.getDepositAddresses();
if (deposit.ready) {
  console.log(deposit.evmAddress, deposit.svmAddress);
}

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 sufwan-local-test creates. sufwan-local-test still signs, through the authorization key you saved, with no user present. evmAddress is that Privy wallet. See Privy wallet provider.

Self-custodyCopy Anchor Link

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. sufwan-local-test 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 sufwan-local-test 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: sufwan-local-test 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 sufwan-local-test. sufwan-local-test 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. sufwan-local-test 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 sufwan-local-test recorded it in. For shares bought outside sufwan-local-test, sufwan-local-test 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.

Venue accountsCopy Anchor Link

Some balances live inside a single venue and can only be spent there.

• BetDEX hosted account. sufwan-local-test 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. sufwan-local-test 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 glanceCopy Anchor Link

Compare the trading flows in Choose your integration.

GlossaryCopy Anchor Link