> ## 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.

# Changelog

> Release history for the @agg-build SDK, hooks, UI, and auth packages.

<Note>
  These notes are generated from the published package changelogs. The four
  `@agg-build` packages are version-linked, so a release usually bumps them
  together. Tags below show which packages shipped each version.
</Note>

<Update label="2.1.2" tags={["Patch", "sdk", "hooks", "ui", "auth"]}>
  * Improve live trading and resolved-market handling across the AGG React packages.
    * `@agg-build/hooks`
      * invalidate and optimistically refresh cached market, balance, position, and activity data when `market_resolved` WebSocket events arrive
      * export venue-attributed live best-price candidate helpers/hooks so UI surfaces can keep the displayed venue logo aligned with the freshest live price
    * `@agg-build/ui`
      * add shared claim-winnings and resolved-market claim hooks for resolved positions
      * show the new resolved-market earnings/claim state in the event market flow
      * add `onBeforePrimaryAction` so partners can run a pre-submit gate before normal order execution
      * keep market detail outcome prices and venue logos in sync with live best-price updates
    * `@agg-build/sdk`
      * no direct SDK source or API changes landed in this push
      * patch bump only to keep the linked public package versions aligned for release/publishing with the updated hooks and UI peers
</Update>

<Update label="2.1.1" tags={["Patch", "hooks", "ui"]}>
  * Add provider-level AGG UI trading execution mode config.

    `AggProvider` now accepts `config.trading.executionMode` so hosted UI surfaces can share a global live or paper trading mode without threading `executionMode` through every page or order panel. `PlaceOrder`, `HomePage`, `EventMarketPage`, and `UserProfilePage` use the configured mode by default while preserving explicit component-level overrides.

    The shared balance provider now also uses the configured paper mode, so `ConnectButton` header totals and `UserProfilePage` balance/positions value cards read paper balances instead of falling back to live-mode zeroes.

    Paper balances are labeled as Paper in the user profile network breakdown, use a shared paper-mode icon, and show a tooltip warning when the app is running with simulated paper funds.
</Update>

<Update label="2.1.0" tags={["Minor", "sdk", "hooks", "ui"]}>
  * Add safe midpoint batching for component-driven market pages.

    `AggClient.getMidpoints` now splits large `/midpoints` GET requests into smaller batches and merges the responses, defaulting to 75 venue market IDs per request to stay below common CDN URL limits. React hooks and UI components read the same default through `config.market.maxMidpointIdsPerRequest`, and direct hook/SDK callers can override the cap when needed.
</Update>

<Update label="2.0.0" tags={["Major", "sdk", "hooks", "ui", "auth"]}>
  * **sdk, hooks:** Narrow recurrence filters to the documented public cadence enum and expose the full supported venue-event cadence list through `RECURRENCE_CADENCES`, including `PT10M`, `P1M`, and `P1Y`.

    Migration guidance: replace dynamic recurrence-catalog calls with the SDK `RECURRENCE_CADENCES` export or the OpenAPI enum. Pass the literal `"null"` only when filtering one-off venue events. `listRecurringCryptoMarkets` remains limited to deterministic crypto durations: `PT5M`, `PT15M`, `PT1H`, and `P1D`.
</Update>

<Update label="1.3.0" tags={["Minor", "sdk", "hooks", "ui"]}>
  * Frontend feature round-up since the last release: live arbitrage signals, nested category navigation, event-tile price gaps, paper-trading mode, and position/redeem fixes.
    * **Live arbitrage (`@agg-build/sdk`, `@agg-build/hooks`, `@agg-build/ui`)**
      * SDK added `subscribeArb` and `subscribeArbFeed`, with the supporting wire types (`WsArbMarketUpdate`, `WsArbFeedBatch`, `WsArbFeedEntry`), socket dispatch, reconnect, and refcount handling, and documented the new arb actions in the `WsClientMessage` union.
      * Hooks added `useMarketArb` (live per-market arb) and `useArbFeed` (event-level MAX rollup), exported with their `UseMarketArbResult` / `UseArbFeedResult` types.
      * UI brought back the arbitrage sort option and added event-list filters; event tiles and lists now surface arb-driven ordering.
    * **Nested categories (`@agg-build/hooks`, `@agg-build/ui`)**
      * Hooks added `useCategoryChildren` (with `UseCategoryChildrenOptions`) for fetching subcategories.
      * UI renders the category `displayName` on home tabs and event-list filters, supports nested subcategories, and `EventListProps` gained `onCategoryRootChange`. `HomePageCategory` now carries an optional `displayName`.
    * **Event-tile price gaps (`@agg-build/hooks`, `@agg-build/ui`)**
      * Hooks exported the `computePriceGaps` helper plus `MAX_PRICE_GAP_PCT` / `MIN_PRICE_GAP_PCT` and the `ComputePriceGapsOptions` / `PriceGapValue` types.
      * A new `enablePriceGap` feature flag and `priceGap` label gate compact price-gap signals on aggregated event tiles; tiles wait for midpoints before computing gaps to avoid flicker.
    * **Paper-trading mode (`@agg-build/sdk`, `@agg-build/hooks`, `@agg-build/ui`)**
      * SDK introduced the `ExecutionMode` (`"live" | "paper"`) type and threaded an optional `mode` through `ExecuteManagedParams`, smart-route params, positions/orders queries, and `ManagedBalancesParams`.
      * UI's place-order panel accepts an `executionMode` prop and reports the chosen `mode` back through `onPrimaryAction`.
    * **Positions, redeem, and claim fixes (`@agg-build/hooks`, `@agg-build/ui`)**
      * Hooks exported `invalidateUserClaimState` and now walk the active bucket when counting redeem-eligible positions; auto-settled HL winners are reported as redeemed rather than ineligible.
      * UI user-profile tabs trust server-provided position buckets, redeem payout renders from the 6-decimal `totalPayoutRaw` (no longer derived from `legs[0]` decimals), and a new partner-overridable `claim` label group powers claim lifecycle notifications.
    * **Withdrawals & misc (`@agg-build/sdk`, `@agg-build/ui`)**
      * SDK added the `WithdrawalSourceTokenSymbol` type to support pUSD withdrawal sources; `WithdrawManagedSourceItem.tokenSymbol` now accepts `pUSD`.
      * UI event-list skeletons can render the discovery sidebar (`withSidebar`), with refreshed event-tile coloring, volume sort, and updated `sort-volume-24hr` / `shield-trust` icons.
</Update>

<Update label="1.2.13" tags={["Patch", "sdk"]}>
  * Add `email: string | null` to the typed `accounts.created` webhook event payload so partners can read email addresses supplied by magic-link or OAuth sign-in.
</Update>

<Update label="1.2.12" tags={["Patch", "hooks", "ui"]}>
  * Expand the trading labels surface with 9 new partner-overridable keys
    for execution failure messaging (`sellNoOnchainPosition`,
    `venueQuoteUnfillable`, `venueMinOrderSize`, `sourceBalanceChanged`,
    `venueMarketResolved`, `dflowWalletUnverified`, `venueNoQuotePath`,
    `solanaBlockhashExpired`, `venueRateLimited`, `serviceBlockedOrder`),
    and wire matching patterns into `normalizePlaceOrderErrorMessage` so
    the SDK renders friendly copy for every `UserActionableStepError`
    reason code the trade-executor now emits.

    Also rewrites the venue-terminated pattern coverage to handle
    Limitless's `FAILED` / `UNMATCHED` settlement statuses with
    dedicated friendly copy (`"Order didn't settle on-chain"` and
    `"No liquidity matched your order at the quoted price"`), and extends
    the min-order-size pattern to recognize predict.fun's existing
    `predict_min_quantity` user-actionable copy.
  * Centralize execution failure labels and clean up place-order error normalization for venue outages and expired submission deadlines.
</Update>

<Update label="1.2.11" tags={["Patch", "sdk", "hooks", "ui", "auth"]}>
  * Deposit & withdraw UX overhaul:
    * New `useWithdrawEstimate` hook surfaces per-route fee and ETA estimates before submit.
    * Refreshed deposit and withdraw flows, including new amount/method/success screens, transfer fee summary, and friendly error states.
    * `WithdrawManagedResponse` now exposes `completedAmountRaw`, and the WS `WithdrawalLifecycleEvent` includes `requestedAmountRaw` and `completedAmountRaw` so consumers can render the terminal settled amount.
    * New balance/activity invalidation helpers (`invalidateUserActivityQueries`, `invalidateUserMoneyState`, `userActivityQueryKeys`) exported from `@agg-build/hooks`.
    * User profile activity rows and balance cards updated with refined states; new `spinner` and `circle-xmark` icons; tooltip primitive tweaks.
</Update>

<Update label="1.2.10" tags={["Patch", "ui"]}>
  * Fix a bug in geo-blocking behavior for order splitting
</Update>

<Update label="1.2.9" tags={["Patch", "ui"]}>
  * UI updates for Positions tab and removed hardcoded colors
</Update>

<Update label="1.2.8" tags={["Patch", "ui"]}>
  * Added new prop in tooltip for gap and UI adjustments
</Update>

<Update label="1.2.7" tags={["Patch", "ui"]}>
  * Fix a bug in geo-blocking behavior for order splitting
</Update>

<Update label="1.2.6" tags={["Patch", "ui"]}>
  * UI updates in the withdraw modal and claim flow for design QA
</Update>

<Update label="1.2.5" tags={["Patch", "ui"]}>
  * Bug fix for nullable venueMarketOutcomeId
</Update>

<Update label="1.2.4" tags={["Patch", "ui"]}>
  * Bug fix for nullable venueMarketOutcomeId
  * Update network chain logos to prediction-markets CDN paths; fix Solana missing from deposit modal network list
</Update>

<Update label="1.2.3" tags={["Patch", "ui"]}>
  * removed redundant div from venue selection
</Update>

<Update label="1.2.2" tags={["Patch", "ui"]}>
  * Sorting user positions
</Update>

<Update label="1.2.1" tags={["Patch", "ui"]}>
  * Market details UX updates
</Update>

<Update label="1.2.0" tags={["Minor", "sdk", "hooks", "ui", "auth"]}>
  * Added smart-route fee breakdown support across AGG packages.

    * `@agg-build/sdk` now includes optional `feeBreakdown` data on smart-route quote responses so integrators can display venue fees, bridge fees, execution gas, and total fees.
    * `@agg-build/hooks` adds `features.showFeesBreakdown` to UI config and new label keys for fees and updated positions table/status copy.
    * `@agg-build/ui` adds optional fee breakdown display in the place-order flow, updates route ordering to prioritize better executable value, improves mobile event-market trade opening from outcome selection, and upgrades positions UX (active/closed filtering, status/result badges, and claim-state handling).

    These changes are backward compatible and require no migration for existing integrations unless you want to enable the new fee breakdown UI (`showFeesBreakdown`).
</Update>

<Update label="1.1.0" tags={["Minor", "ui"]}>
  * Added xs size for icons and geo block updates for order
</Update>

<Update label="1.0.2" tags={["Patch", "hooks", "ui", "auth"]}>
  * Refresh published package metadata and fixes for the AGG SDK package stack.

    Updates:

    * @agg-build/hooks: fix midpoint price calculation in `useViewportMidpoints`; minor adjustments to UI-config labels and the `useWithdrawFlow` hook.
    * @agg-build/ui: settlement formatting refactor (new `settlement-text-renderer` + `settlement-text.utils`); `PlaceOrder` flow updates including default amount, sell-tab default, partially-filled state, best-price wiring, max label, and a sign-in-to-trade flow; refreshed typography variants; new `apps` and `circle-overlap` icons; custom `Select` migration for TBAs; connect-button view rewrite; event-list search/filter improvements.
    * @agg-build/auth: updates to the SIWE adapter and shared auth utils.
</Update>

<Update label="1.0.1" tags={["Patch", "sdk", "hooks", "ui"]}>
  * **sdk**: Add withdrawal lifecycle WebSocket support — new `WsWithdrawalLifecycleEvent` message type, `onWithdrawalLifecycle` SDK callback, and associated types (`WsWithdrawalLifecycleStatus`, `WsWithdrawalLegStatus`, `WsWithdrawalLifecycleLeg`).

    **hooks**: Add `useWithdrawFlow`, `useWithdrawalLifecycle`, and `useOnWithdrawalLifecycle` hooks with full withdrawal lifecycle tracking via WebSocket. Fix live outcome price fallback so REST midpoints surface when no WS midpoint exists. Improve `useMidpoints` to prefer the venue with the lower YES midpoint for better buyer pricing. Fix hooks package exports to use format-specific type declarations (`.d.mts` for ESM consumers).

    **ui**: Add wallet withdrawal flow — recipient address input, amount/token/network selection, confirmation step, and an order-style execution timeline showing per-leg bridge/transfer progress with live lifecycle status. Add `CopyButton` primitive. Show wallet address on card-payment pending step in the deposit flow. Surface best-price venue indicators in the event list, market details, and orderbook. Fix cluster-aware market deduplication to collapse cross-page duplicates.
</Update>

<Update label="1.0.0" tags={["Major", "sdk", "hooks", "ui", "auth"]}>
  * Initial v1.0.0 release of the AGG client libraries on npm under the `@agg-build` scope.
</Update>