> ## Documentation Index > Fetch the complete documentation index at: https://docs.agg.market/llms.txt > Use this file to discover all available pages before exploring further. > ## Agent Instructions > To integrate AGG, start with Quickstart: REST (https://docs.agg.market/quickstart/rest), then Order lifecycle & statuses (https://docs.agg.market/concepts/order-lifecycle). > Track every trade until it reaches a terminal status. Before retrying a failed or timed-out call, read Errors, retries & idempotency (https://docs.agg.market/concepts/errors). > The API reference is generated from https://docs.agg.market/openapi/openapi.json. # Get user balances ## OpenAPI ````yaml /openapi/openapi.json get /apps/{appId}/users/{userId}/balances openapi: 3.0.2 info: title: AGG API version: 1.0.0 description: >- Prediction market aggregator REST API — authentication, users, venue events, venue markets, orderbooks, charts, and execution workflows. servers: - url: https://api.agg.market description: Production security: [] tags: - name: Authentication description: Sign users in and manage their session tokens. - name: Markets description: Find events, markets and outcomes to trade. - name: Market Data description: Live orderbooks, prices, charts and scores for those markets. - name: Trading description: Quote, place, sign, track and cancel orders. - name: Portfolio description: A user's orders, positions, balances and activity. - name: Funding description: Deposit addresses, withdrawals, balance refills and fiat on-ramp. - name: Users description: The signed-in user's profile, linked accounts, KYC and venue keys. - name: Hosted Venue Accounts description: Provision, fund and withdraw from venue accounts hosted for the user. - name: Webhooks description: Configure and operate webhook delivery to your server. - name: Partner Admin description: Server-side reads across your app's users, orders and analytics. - name: Paper Trading description: Simulated accounts and orders for testing without real funds. - name: News description: News feeds linked to markets. - name: Correlated Markets description: Markets related to a given market and the effect of its resolution. paths: /apps/{appId}/users/{userId}/balances: get: tags: - Partner Admin summary: Get user balances operationId: getAppUserBalances parameters: - name: appId in: path required: true schema: type: string - name: userId in: path required: true schema: type: string responses: '200': description: '200' content: application/json: schema: $ref: '#/components/schemas/UnifiedBalanceResponse' '401': description: '401' content: application/json: schema: $ref: '#/components/schemas/ErrorMessage' '403': description: '403' content: application/json: schema: $ref: '#/components/schemas/ErrorMessage' '404': description: '404' content: application/json: schema: $ref: '#/components/schemas/ErrorMessage' security: - appApiKey: [] components: schemas: UnifiedBalanceResponse: type: object required: - cash - positions properties: cash: description: Stablecoin cash, one entry per token, with per-chain rows. type: array items: $ref: '#/components/schemas/WalletTokenBalance' positions: description: Value of open positions, one entry per venue. type: array items: type: object required: - venue - balance - costBasis - unrealizedPnl - realizedPnl - priceSource - bookQuality properties: venue: allOf: - $ref: '#/components/schemas/Venue' description: Venue these positions are on. balance: description: >- Market value of the open positions on this venue. USD, as a float. type: number costBasis: description: >- What the priced positions cost to open (negative for short legs). USD, as a float. Excludes positions with an unknown cost; see `costBasisUnknown`. type: number unrealizedPnl: description: >- `balance` minus `costBasis` over the priced positions. USD, as a float. type: number realizedPnl: description: >- Profit or loss already locked in by sells and settlements. USD, as a float. type: number priceSource: $ref: '#/components/schemas/PriceSource' bookQuality: $ref: '#/components/schemas/BookQuality' migrationPending: description: >- Present and `true` when some Polymarket shares have not yet moved to the user's deposit wallet. Show them as pending rather than tradable. type: boolean costBasisUnknown: description: >- Present and `true` when at least one open position came from shares acquired outside AGG with no known entry price. `balance` still counts them, but `costBasis` and `unrealizedPnl` cover only the positions with a known entry; show P&L as partial. type: boolean realizedPnlIncomplete: description: >- Present and `true` when `realizedPnl` misses a sell or settlement of shares with no known entry price. Stays set once set. type: boolean venueCash: description: >- Cash held inside venue accounts, separate from on-chain `cash`. Omitted when no such venue is available. type: array items: type: object required: - venue - balanceCents - updatedAt properties: venue: allOf: - $ref: '#/components/schemas/Venue' description: Venue holding the cash (kalshi, prophetx or betdex). balanceCents: description: Cash held at the venue. USD, as integer cents (1234 = $12.34). type: integer transferable: description: >- `false` when this cash cannot be moved out through AGG (ProphetX). type: boolean executionBackend: description: >- ProphetX only. `direct`: the user's own ProphetX account. `clearinghouse`: trading through AGG's ProphetX account. type: string enum: - clearinghouse - direct accountModel: description: 'BetDEX only: the account is hosted by the platform.' type: string enum: - platform-hosted asset: description: 'BetDEX only: cash asset.' type: string enum: - USDC decimals: description: 'BetDEX only: decimals of the *Raw fields.' type: number enum: - 6 balanceRaw: pattern: ^-?[0-9]+$ description: >- BetDEX only: total balance, in 6-decimal atomic units (1000000 = $1). Can be negative. type: string availableRaw: pattern: ^[0-9]+$ description: 'BetDEX only: spendable balance, in 6-decimal atomic units.' type: string unmatchedExposureRaw: pattern: ^[0-9]+$ description: >- BetDEX only: cash tied up in unmatched orders, in 6-decimal atomic units. type: string portfolioValueCents: description: 'Kalshi only: value of open positions. USD, as integer cents.' type: integer updatedAt: description: ISO-8601 time the balance was read. type: string paper: description: Paper-account summary. Present only in paper mode. type: object required: - startingBalance - cashBalance - positionsValue - realizedPnl - unrealizedPnl - earnings properties: startingBalance: description: Balance the paper account started with. USD, as a float. type: number cashBalance: description: Simulated cash available to trade. USD, as a float. type: number positionsValue: description: Market value of open paper positions. USD, as a float. type: number realizedPnl: description: P&L locked in by closed paper trades. USD, as a float. type: number unrealizedPnl: description: P&L on open paper positions at current prices. USD, as a float. type: number earnings: description: '`realizedPnl` + `unrealizedPnl`. USD, as a float.' type: number ErrorMessage: type: object required: - message properties: message: type: string WalletTokenBalance: type: object required: - tokenSymbol - totalRaw - decimals - chains properties: tokenSymbol: description: 'Canonical token, e.g. "USDC" (paper accounts: "PAPER_USD").' type: string totalRaw: description: >- Total across all chains. Integer string in the token's atomic units, scaled by `decimals` (6 for stablecoins: 1000000 = $1). type: string availableRaw: description: >- Spendable now across all chains. Integer string in the token's atomic units, scaled by `decimals` (6 for stablecoins: 1000000 = $1). type: string reservedRaw: description: >- Held for pending orders or withdrawals. Integer string in the token's atomic units, scaled by `decimals` (6 for stablecoins: 1000000 = $1). type: string decimals: description: Decimals that scale this token's *Raw totals. type: number chains: description: >- Per-chain rows that make up the totals. Each row has its own `decimals`. type: array items: type: object required: - chainId - tokenAddress - balanceRaw - decimals - lastSyncedAt properties: chainId: description: Chain id the balance sits on (e.g. 137 Polygon). type: number tokenAddress: description: >- Token contract address (SPL mint on Solana, token id on Hyperliquid). type: string balanceRaw: description: >- Balance on this chain. Token atomic units as an integer string, scaled by this row's `decimals` (6 for most stablecoins, so 1000000 = 1 USDC; 18 on BNB Chain). type: string heldRaw: description: >- Part of `balanceRaw` held for pending orders or withdrawals. Token atomic units as an integer string, scaled by this row's `decimals` (6 for most stablecoins, so 1000000 = 1 USDC; 18 on BNB Chain). type: string availableRaw: description: >- Spendable now: `balanceRaw` minus `heldRaw`. Token atomic units as an integer string, scaled by this row's `decimals` (6 for most stablecoins, so 1000000 = 1 USDC; 18 on BNB Chain). type: string decimals: description: Decimals of this row's token; scales the *Raw fields. type: number lastSyncedAt: description: ISO-8601 time the balance was last read. type: string tokenSymbol: description: >- On-chain symbol of this row's token when it differs from the parent `tokenSymbol` it is rolled up under (e.g. USDC.e under USDC). type: string address: description: >- Wallet address holding this balance (`custody=self` responses). Absent for cash held in a venue account, which is identified by `venueAccountId` instead. type: string custodyKind: description: >- What holds this balance: `EOA` the user's own wallet, `DEPOSIT_WALLET` the user's Polymarket deposit wallet, `POLYMARKET_LEGACY` a Polymarket wallet created before AGG (see `legacyKind`), `VENUE_ACCOUNT` cash inside a venue account. type: string enum: - EOA - DEPOSIT_WALLET - POLYMARKET_LEGACY - VENUE_ACCOUNT venue: allOf: - $ref: '#/components/schemas/Venue' description: >- With `custodyKind: "VENUE_ACCOUNT"`: the venue holding this cash. It can only be spent on that venue until withdrawn. venueAccountId: description: AGG id of the venue account holding this cash. type: string externalAccountId: description: The venue's own identifier for that account. type: string isFresh: description: >- Venue-account cash only. `false` when the last reading is stale: the balance is still shown but `availableRaw` is 0 until it refreshes. type: boolean legacyKind: description: >- With `custodyKind: "POLYMARKET_LEGACY"`. A `safe` balance can fund any venue; a `proxy` balance can only be spent on Polymarket. `proxy` rows are still counted in the parent token's `totalRaw` and `availableRaw`, so subtract them to get what can be spent elsewhere. type: string enum: - safe - proxy Venue: type: string enum: - kalshi - polymarket - limitless - opinion - predict - pred - tiprun - probable - myriad - hyperliquid - novig - prophetx - betdex PriceSource: description: >- Where the current price came from. `orderbook`: the live book. `settled`: the market resolved, so the price is the payout (1 or 0). `cached`: a recent stored price, used when the live book was unavailable. `entry`: no price was available, so the entry price is used and P&L is not meaningful. On totals, the worst source across legs. type: string enum: - orderbook - cached - entry - settled BookQuality: description: >- How trustworthy the order book behind a price is. `healthy`: two-sided with a normal spread. `wide_spread`: two-sided but the spread is wide, so the midpoint overstates what you could sell for. `bid_only` / `ask_only`: one side of the book is empty. `endpoint_stub`: only placeholder quotes at the price bounds. `crossed`: best bid is at or above best ask. `empty`: no book (also reported for settled positions, which need none). type: string enum: - healthy - bid_only - ask_only - endpoint_stub - wide_spread - crossed - empty securitySchemes: appApiKey: type: apiKey in: header name: x-app-api-key description: App-scoped API key for programmatic app management. ````