feat: unified market discovery with browse, search, and pagination

Refactor market reference discovery to support both search and browse
modes with server-side pagination across all market adapters.

Markets:
- Polymarket: add browse support with sort options (volume, liquidity,
  newest, ending soon), paginated search, and structured reference
  results with price/volume/liquidity/endDate metadata
- Hyperliquid: add browse support sorted by volume, paginated results,
  and unified reference result format
- Extend MarketAdapter interface with browseReferences(), browseOptions,
  and pagination (limit/offset) for both search and browse

API:
- Add GET /markets/:id/browse endpoint with sort/limit/offset params
- Update search endpoint to support limit/offset pagination
- Rename 'symbol' to 'reference' throughout order placement pipeline

Core:
- Update schemas to use 'reference' instead of 'symbol' in order inputs
- Add BrowseOption and pagination types to market adapter interface

Web UI:
- Redesign MarketSearchPanel with tabbed browse/search, sort controls,
  stat grid cards with price/volume/liquidity/endDate, hover glow
  effects, and load-more pagination
- Add market card animations (card-glow-pulse, radial hover gradient)
- Update TradeTicketCard and PortfolioPanels styling
- Add items-start to grid layout to prevent column stretching

Docs:
- Update README, admin guide, API reference, architecture, testing,
  trading agent, and trading model docs to reflect new discovery model

Author: siriusctrl

README.md

@@ -6,7 +6,7 @@ A self-hosted paper trading engine with a clean REST API. Simulated trading acro
 
 - **Market agnostic** — unified API across all markets, discover capabilities at runtime
 - **Polymarket** — prediction market trading with live odds from the CLOB API
-- **Hyperliquid** — perpetual futures with symbol-level fractional size precision and max leverage limits
+- **Hyperliquid** — perpetual futures with reference-level fractional size precision and max leverage limits
 - **Extensible** — add new markets by implementing a simple adapter interface
 - **Agent-friendly** — skill-based integration with version-aware SSE events, self-describing market capabilities
 - **Decision transparency** — every action requires reasoning; journal + timeline for full audit trail
@@ -56,19 +56,19 @@ You can start from [.env.example](.env.example).
 
 ### Trading Constraints
 
-Order payload `quantity` is decimal-capable at schema layer, then validated per market/symbol.
+Order payload `quantity` is decimal-capable at schema layer, then validated per market/reference.
 
 Discover constraints before placing orders:
 
 ```bash
-GET /api/markets/:market/trading-constraints?symbol=<symbol>
+GET /api/markets/:market/trading-constraints?reference=<reference>
 ```
 
 Example response:
 
 ```json
 {
-  "symbol": "BTC",
+  "reference": "BTC",
   "constraints": {
     "minQuantity": 0.00001,
     "quantityStep": 0.00001,
@@ -80,7 +80,28 @@ Example response:
 
 Notes:
 - Some markets require integer quantities (`supportsFractional: false`, usually `quantityStep: 1`).
-- Hyperliquid derives `quantityStep` and fractional support from `szDecimals`, and enforces symbol `maxLeverage`.
+- Search and browse surfaces now return lightweight market references. Execution endpoints (`quote`, `orderbook`, `resolve`, order placement) accept those references directly.
+- Discovery is intentionally separate from execution: `browse` and `search` help humans and agents find candidates quickly, then adapters lazily normalize the chosen `reference` only when a quote or order is requested.
+- For Polymarket, discovery references are typically market slugs. The adapter resolves those slugs into outcome token ids behind the scenes when you ask for quotes or place orders.
+- Hyperliquid derives `quantityStep` and fractional support from `szDecimals`, and enforces per-reference `maxLeverage`.
+- Browse sort options are market-specific and discoverable from `GET /api/markets`. Polymarket exposes `volume`, `liquidity`, `endingSoon`, and `newest`; Hyperliquid exposes `price`.
+
+### Market Discovery
+
+Typical discovery flow:
+
+```bash
+GET /api/markets
+GET /api/markets/:market/browse?sort=<market-specific-sort>
+GET /api/markets/:market/search?q=iran
+GET /api/markets/:market/quote?reference=<reference>
+POST /api/orders
+```
+
+The platform now treats `reference` as the single external identifier across markets:
+- Polymarket: usually a slug during discovery, resolved lazily to a token id for execution
+- Hyperliquid: usually a ticker such as `BTC`
+- Future markets: whatever adapter-specific identifier makes the most sense externally
 
 ### Running the Server
 

docs/admin-guide.md

@@ -49,7 +49,7 @@ A user detail view shows:
 The trade page allows an admin to:
 - create a new trader account
 - choose a market dynamically from runtime discovery
-- search assets
+- search and browse market references
 - inspect quotes and trading constraints
 - select a target user
 - place market or limit orders on that user's behalf
@@ -110,7 +110,7 @@ Important rules:
 - optional `accountId` must match the user's default account if supplied
 - `Idempotency-Key` is supported and should be used by the dashboard or scripts for retry-safe writes
 - `leverage` and `reduceOnly` are only valid for perp markets
-- symbol normalization and trading-constraint validation still apply
+- reference normalization and trading-constraint validation still apply
 - market orders fill immediately using directional executable prices
 - limit orders remain pending until the background reconciler fills or cancels them
 

docs/api-reference.md

@@ -50,7 +50,7 @@ Notes:
 
 Required fields:
 - `market`
-- `symbol`
+- `reference`
 - `side`
 - `type`
 - `quantity`
@@ -64,7 +64,7 @@ Optional fields:
 Rules:
 - `reasoning` is required for state-changing writes
 - `leverage` and `reduceOnly` are valid only for perp markets
-- quantity is validated against per-symbol trading constraints
+- quantity is validated against per-reference trading constraints
 - normal market-order execution uses directional executable prices: `buy -> ask`, `sell -> bid`
 - limit orders remain `pending` until the background reconciler fills or cancels them
 
@@ -86,8 +86,9 @@ Rules:
 | Method | Endpoint | Auth | Description |
 |--------|----------|------|-------------|
 | `GET` | `/api/markets` | key or admin | Discover registered markets and capabilities |
-| `GET` | `/api/markets/:market/search` | key or admin | Search or browse assets |
-| `GET` | `/api/markets/:market/trading-constraints` | key or admin | Get symbol-level quantity and leverage constraints |
+| `GET` | `/api/markets/:market/search` | key or admin | Search market references |
+| `GET` | `/api/markets/:market/browse` | key or admin | Browse active market references |
+| `GET` | `/api/markets/:market/trading-constraints` | key or admin | Get reference-level quantity and leverage constraints |
 | `GET` | `/api/markets/:market/quote` | key or admin | Get one quote |
 | `GET` | `/api/markets/:market/quotes` | key or admin | Get quotes in batch |
 | `GET` | `/api/markets/:market/orderbook` | key or admin | Get one orderbook |
@@ -96,13 +97,38 @@ Rules:
 | `GET` | `/api/markets/:market/fundings` | key or admin | Get funding rates in batch |
 | `GET` | `/api/markets/:market/resolve` | key or admin | Get settlement or resolution status |
 
+### Search and browse contract
+
+- `search` requires a non-empty `q`
+- `browse` is explicit and accepts a market-specific `sort` string
+- browse options are discoverable from `GET /api/markets`
+- current defaults:
+  - Polymarket: `volume`, `liquidity`, `endingSoon`, `newest`
+  - Hyperliquid: `price`
+- both endpoints return lightweight discovery records shaped like:
+
+```json
+{
+  "reference": "btc",
+  "name": "BTC-PERP",
+  "price": 94321.1,
+  "volume": 12003455.2,
+  "liquidity": 882100.4,
+  "endDate": null,
+  "metadata": {}
+}
+```
+
+- discovery results are not required to be execution-ready exchange ids
+- adapters normalize the supplied `reference` lazily when `quote`, `orderbook`, `resolve`, or order placement is called
+
 ### Trading constraints response
 
 Example:
 
 ```json
 {
-  "symbol": "BTC",
+  "reference": "BTC",
   "constraints": {
     "minQuantity": 0.00001,
     "quantityStep": 0.00001,
@@ -156,6 +182,9 @@ The structured liquidation event includes:
 - `cancelledReduceOnlyOrderIds`
 - `liquidatedAt`
 
+Note:
+- timeline and settlement/liquidation audit surfaces still expose internal normalized `symbol` fields because accounting is stored against resolved execution identifiers
+
 ## Admin API
 
 The full operator workflow is documented in [Admin Guide](admin-guide.md). The main admin-only endpoints are:

docs/architecture.md

@@ -109,13 +109,14 @@ It should not know anything about:
 The `markets` package owns market-specific reads.
 
 Adapters expose a common interface so the rest of the system can ask for:
-- searchable assets
+- searchable market references
+- browseable market references
 - quotes
 - orderbooks
 - funding rates
 - resolution information
 - trading constraints
-- symbol normalization when needed
+- reference normalization when needed
 
 Adapters do not execute trades. They are data providers for the simulation engine.
 
@@ -161,18 +162,19 @@ Examples:
 - markets with `funding` are treated as perp markets
 - markets with `resolve` support settlement checks
 - markets with `orderbook` can expose live depth
-- markets with `search` can drive browse/search UX
+- markets with `search` and `browse` can drive discovery UX for humans and agents
 
 This avoids hardcoding business logic around a market name such as `if market === "hyperliquid"`.
 
 The adapter contract currently centers around methods like:
 - `search(query)`
-- `getQuote(symbol)`
-- `getOrderbook(symbol)`
-- `getFundingRate(symbol)`
-- `resolve(symbol)`
-- `getTradingConstraints(symbol)`
-- `normalizeSymbol(symbol)`
+- `browse(options)`
+- `getQuote(reference)`
+- `getOrderbook(reference)`
+- `getFundingRate(reference)`
+- `resolve(reference)`
+- `getTradingConstraints(reference)`
+- `normalizeReference(reference)`
 
 ## Request Flow
 
@@ -182,7 +184,7 @@ A typical order request follows this path.
 2. Route resolves the acting identity and target account.
 3. Route delegates to the shared order-placement service.
 4. The service loads the adapter from the registry.
-5. The service normalizes the symbol and validates trading constraints.
+5. The service normalizes the external reference and validates trading constraints.
 6. The service fetches a quote.
 7. The service chooses spot or perp engine based on capabilities.
 8. The service performs transactional writes to accounts, orders, trades, and positions.

docs/testing.md

@@ -118,40 +118,45 @@ TRADE_SYMBOL=""
 while read -r MARKET_ID; do
   [[ -n "$MARKET_ID" ]] || continue
 
-  SEARCH_PAYLOAD="$(auth_get "/api/markets/$MARKET_ID/search?limit=1")"
-  SYMBOL="$(jq -r '.results[0].symbol // empty' <<<"$SEARCH_PAYLOAD")"
-  [[ -n "$SYMBOL" ]] || continue
+  SORT="$(jq -r --arg m "$MARKET_ID" '.markets[] | select(.id == $m) | .browseOptions[0].value // empty' <<<"$MARKETS_PAYLOAD")"
+  BROWSE_URL="/api/markets/$MARKET_ID/browse?limit=1"
+  if [[ -n "$SORT" ]]; then
+    BROWSE_URL="$BROWSE_URL&sort=$SORT"
+  fi
+  BROWSE_PAYLOAD="$(auth_get "$BROWSE_URL")"
+  REFERENCE="$(jq -r '.results[0].reference // empty' <<<"$BROWSE_PAYLOAD")"
+  [[ -n "$REFERENCE" ]] || continue
 
   CAPS="$(jq -r --arg m "$MARKET_ID" '.markets[] | select(.id == $m) | .capabilities[]?' <<<"$MARKETS_PAYLOAD")"
   if grep -qx "quote" <<<"$CAPS"; then
-    auth_get "/api/markets/$MARKET_ID/quote?symbol=$SYMBOL" >/dev/null
+    auth_get "/api/markets/$MARKET_ID/quote?reference=$REFERENCE" >/dev/null
   fi
   if grep -qx "orderbook" <<<"$CAPS"; then
-    auth_get "/api/markets/$MARKET_ID/orderbook?symbol=$SYMBOL" >/dev/null
+    auth_get "/api/markets/$MARKET_ID/orderbook?reference=$REFERENCE" >/dev/null
   fi
   if grep -qx "funding" <<<"$CAPS"; then
-    auth_get "/api/markets/$MARKET_ID/funding?symbol=$SYMBOL" >/dev/null
+    auth_get "/api/markets/$MARKET_ID/funding?reference=$REFERENCE" >/dev/null
   fi
   if grep -qx "resolve" <<<"$CAPS"; then
-    auth_get "/api/markets/$MARKET_ID/resolve?symbol=$SYMBOL" >/dev/null
+    auth_get "/api/markets/$MARKET_ID/resolve?reference=$REFERENCE" >/dev/null
   fi
 
   if [[ -z "$TRADE_MARKET" ]]; then
     TRADE_MARKET="$MARKET_ID"
-    TRADE_SYMBOL="$SYMBOL"
+    TRADE_SYMBOL="$REFERENCE"
   fi
 done < <(jq -r '.markets[].id' <<<"$MARKETS_PAYLOAD")
 
 [[ -n "$TRADE_MARKET" && -n "$TRADE_SYMBOL" ]] || {
-  echo "no tradeable symbol found"
+  echo "no tradeable reference found"
   exit 1
 }
 
 echo "[3/8] Place market order"
 MARKET_ORDER_PAYLOAD="$(auth_post "/api/orders" "$(jq -nc \
   --arg m "$TRADE_MARKET" \
   --arg s "$TRADE_SYMBOL" \
-  '{market:$m,symbol:$s,side:"buy",type:"market",quantity:1,reasoning:"e2e smoke: open starter position"}'
+  '{market:$m,reference:$s,side:"buy",type:"market",quantity:1,reasoning:"e2e smoke: open starter position"}'
 )")"
 MARKET_ORDER_ID="$(jq -r '.id // empty' <<<"$MARKET_ORDER_PAYLOAD")"
 [[ -n "$MARKET_ORDER_ID" ]] || { echo "market order failed: $MARKET_ORDER_PAYLOAD"; exit 1; }
@@ -160,7 +165,7 @@ echo "[4/8] Place and cancel pending limit order"
 LIMIT_ORDER_PAYLOAD="$(auth_post "/api/orders" "$(jq -nc \
   --arg m "$TRADE_MARKET" \
   --arg s "$TRADE_SYMBOL" \
-  '{market:$m,symbol:$s,side:"sell",type:"limit",quantity:1,limitPrice:0.99,reasoning:"e2e smoke: pending order for cancel flow"}'
+  '{market:$m,reference:$s,side:"sell",type:"limit",quantity:1,limitPrice:0.99,reasoning:"e2e smoke: pending order for cancel flow"}'
 )")"
 LIMIT_ORDER_ID="$(jq -r '.id // empty' <<<"$LIMIT_ORDER_PAYLOAD")"
 [[ -n "$LIMIT_ORDER_ID" ]] || { echo "limit order failed: $LIMIT_ORDER_PAYLOAD"; exit 1; }
@@ -195,7 +200,7 @@ MISSING_REASONING_CODE="$(curl -sS -o /tmp/unimarket-missing-reasoning.out -w "%
   -X POST "$BASE_URL/api/orders" \
   -H "Authorization: Bearer $API_KEY" \
   -H "Content-Type: application/json" \
-  -d "{\"market\":\"$TRADE_MARKET\",\"symbol\":\"$TRADE_SYMBOL\",\"side\":\"buy\",\"type\":\"market\",\"quantity\":1}")"
+  -d "{\"market\":\"$TRADE_MARKET\",\"reference\":\"$TRADE_SYMBOL\",\"side\":\"buy\",\"type\":\"market\",\"quantity\":1}")"
 [[ "$MISSING_REASONING_CODE" == "400" ]] || { echo "expected 400 for missing reasoning"; exit 1; }
 
 echo "[8/8] Optional admin checks"

docs/trading-agent.md

@@ -152,18 +152,23 @@ Pragmatic starting defaults:
 
 Use a repeatable sequence:
 1. `GET /api/markets`
-2. `GET /api/markets/:market/search`
-3. `GET /api/markets/:market/quotes`
-4. `GET /api/markets/:market/orderbooks`
-5. optional `funding` and `resolve` reads when the market supports them
-6. account, portfolio, positions, and order reads
-7. decision and journal write
+2. `GET /api/markets/:market/browse`
+3. optional `GET /api/markets/:market/search` when the agent has a concrete query
+4. keep the returned `reference` for the candidate you want to investigate
+5. `GET /api/markets/:market/quotes`
+6. `GET /api/markets/:market/orderbooks`
+7. optional `funding` and `resolve` reads when the market supports them
+8. account, portfolio, positions, and order reads
+9. decision and journal write
 
 ## What the Agent Should Know About the Platform
 
 A few design facts help agents make better decisions.
 
 - unimarket is simulation-first; it does not place real exchange trades in core flows
+- discovery surfaces return market `reference` values; execution endpoints accept the same reference and let adapters normalize it internally
+- the agent should treat `reference` as the only external market identifier it needs to persist between discovery and execution
+- on Polymarket, a discovery `reference` is usually a slug preview, not an already-resolved token id
 - markets without `funding` behave like spot inventory
 - prediction-market bearish views are expressed by buying the opposite outcome token, not by opening a naked short
 - markets with `funding` behave like perp markets with leverage, funding, and liquidation

docs/trading-model.md

@@ -42,10 +42,12 @@ For prediction markets, directional expression is outcome-based:
 
 For Polymarket specifically:
 - asset discovery comes from Gamma
-- query search uses Gamma `search-v2`, then hydrates selected market slugs through `/markets`
+- query search uses Gamma `search-v2`
+- browse uses Gamma `/events`
+- external discovery results use lightweight market `reference` values, typically Polymarket slugs
 - quotes and orderbooks come from the CLOB API
-- symbol normalization can map a `conditionId` to a concrete outcome `tokenId`
-- if you want a specific outcome such as `NO`, pass the corresponding token id explicitly
+- reference normalization can map a slug or `conditionId` to a concrete outcome `tokenId`
+- if you want a specific outcome such as `NO`, pass the corresponding token id explicitly as the reference
 
 ### Perp-like markets
 
@@ -69,8 +71,8 @@ All state-changing order flows follow the same broad structure.
 
 1. Validate request payload.
 2. Resolve the market adapter.
-3. Normalize the symbol if the adapter supports normalization.
-4. Load symbol-level trading constraints.
+3. Normalize the external reference if the adapter supports normalization.
+4. Load reference-level trading constraints.
 5. Validate quantity step, minimum quantity, fractional support, and optional max leverage.
 6. Fetch a fresh quote.
 7. Either fill immediately or store a pending limit order.
@@ -117,7 +119,7 @@ Future evolution:
 
 ## Trading Constraints
 
-Every market may expose symbol-level constraints through `getTradingConstraints(symbol)`.
+Every market may expose reference-level constraints through `getTradingConstraints(reference)`.
 
 The engine uses these fields:
 - `minQuantity`
@@ -131,7 +133,7 @@ If a market does not provide custom constraints, unimarket falls back to:
 - `supportsFractional = false`
 - `maxLeverage = null`
 
-This keeps order validation market-agnostic while still allowing symbol-specific precision and leverage rules.
+This keeps order validation market-agnostic while still allowing reference-specific precision and leverage rules.
 
 ## Spot Position Accounting