> For the complete documentation index, see [llms.txt](https://docs.trover.tech/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.trover.tech/engineering/stabledex.md). # StableDex StableDex is Trover's own on-chain market terminal for Stable Mainnet (EVM chain `988`). Its native gas asset is `USDT0`. It reads ERC-20 metadata, recognized Uniswap v2/v3 pools, pool state, swap logs, and transfer logs from the configured Stable RPCs. It does not depend on Dexscreener being available for Stable. ## Configuration ```env ENABLE_STABLEDEX=true STABLE_CHAIN_ID=988 STABLE_RPC_URLS=https://rpc.stable.xyz,https://stable.drpc.org,https://stable-mainnet.rpc.sentio.xyz STABLE_EXPLORER_URL=https://stablescan.xyz STABLEDEX_ACTIVITY_LOOKBACK_BLOCKS=50000 STABLEDEX_HOLDER_CACHE_TTL_SECONDS=60 STABLEDEX_INDEXER_ENABLED=true STABLEDEX_INDEXER_INTERVAL_SECONDS=5 STABLEDEX_INDEXER_BATCH_BLOCKS=5000 STABLEDEX_INDEXER_LIVE_BLOCKS=128 STABLEDEX_HOLDER_INDEXER_TOKENS_PER_TICK=3 STABLEDEX_PROFILE_POLL_SECONDS=5 STABLEDEX_INDEXER_START_BLOCK=0 # USDT0 bridge fallback. STABLE_USDT0_BRIDGE_URL=https://usdt0.to # LayerZero Stargate / Value Transfer API: keep this key server-side. LAYERZERO_VTA_ENABLED=true LAYERZERO_VTA_API_BASE_URL=https://transfer.layerzero-api.com/v1 LAYERZERO_VTA_API_KEY= LAYERZERO_VTA_FEE_TOLERANCE_PERCENT=2 # Direct, API-free LayerZero OFT route discovery/quotes. LAYERZERO_DIRECT_OFT_ENABLED=true ``` StableDex does not need a separate swap-provider key or a router address from you. It queries Stable Swap's recognized Uniswap v3 factory/Quoter V2, official Uniswap v2 deployment, and the native-USDT0 Stable Swap v2 router. It builds the appropriate approval plus v3 `exactInputSingle`, v2 `swapExactTokensForTokens`, or native-USDT0 wrap/swap transaction. The browser opens the connected Privy EVM wallet's normal chain-switch and signature flow; on first use it adds canonical chain `988` if necessary. StableDex does not need delegated signing or a user private key. ## Trover-owned market index The worker scans Stable's recognized Uniswap V3 factory plus the official and native-USDT0 Stable Swap V2 factories. Factory cursors are persisted, so an initial backfill starts at `STABLEDEX_INDEXER_START_BLOCK` and advances in bounded batches instead of relying on DYORSwap, Dexscreener, GeckoTerminal, or FeferCoin data. A persistent live cursor scans only fresh blocks plus a small reorg overlap at every index interval, so new pairs and swaps appear without replaying a large historical window for each refresh. `GET /v1/stabledex/markets?category=new|trending|active` returns the indexed market catalogue. `new` is pair-level and includes every factory-discovered Stable pair, including pools that have not obtained a USD quote yet; `trending` and `active` remain restricted to priceable USDT0/WUSDT0 markets. A bounty list remains explicitly empty until a verified Stable bounty/launch contract is configured; the API does not manufacture a "bounty" label from unrelated activity. The chain's `USDT0` token has six decimals. The active v2 liquidity route can use wrapped `WUSDT0` (18 decimals) as its pair asset. StableDex detects that asset, applies the native router's wrap conversion and quoted 40 bps pre-wrap fee, and values it as USD-backed. It will not pretend that a direct USDT0 route exists where the actual pool requires WUSDT0. ## Live market updates StableDex uses public HTTP JSON-RPC only. The worker advances factory and swap cursors on a short interval and an open token terminal polls a fresh, bounded on-chain profile. The result is an independently recoverable update path for TradingView Lightweight Charts candles, directional buy/sell markers, and the per-transaction trade table—without a persistent RPC WebSocket connection. Every indexed V2/V3 `Swap` log is retained in the StableDex swap tape with its pool, block, transaction hash, log index, and raw protocol amounts. `GET /v1/stabledex/tokens/:address/trades` serves that durable public-RPC tape for a token's known pools. The token terminal combines it with its short live log tail so a provider hiccup or a rapidly advancing chain head does not erase recent individual buys and sells from the visible feed. Holder discovery has two public-RPC layers. A new/open token immediately uses a bounded current Transfer-log observation. In parallel, the worker advances persisted per-token Transfer-history cursors and refreshes each observed holder's live `balanceOf`; the holder tab automatically upgrades to that durable history index as it becomes available. This avoids pretending that an RPC has a magic `listHolders` method while still converging on a full indexed holder set without an explorer API key. ## Bridging Relay can bridge Stable's native `USDT0`, but its published Stable route metadata does not advertise swaps or gas top-ups. StableDex therefore retains Relay/Stargate compatibility where configured and also exposes a direct OFT path when the on-chain peer is actually configured. ### Direct LayerZero OFT route — no API key `GET /v1/stabledex/layerzero/direct/routes` reads the Stable USDT0 OFT's `peers()` mapping from public RPC before advertising a route. `POST /v1/stabledex/layerzero/direct/quote` then invokes `quoteSend()` on that same OFT and returns normal EVM approval/send steps for the connected wallet. It does not call the LayerZero Value Transfer API and needs no LayerZero API key. The verified direct outbound routes are **Stable USDT0 → Ethereum, Polygon, Arbitrum, and Optimism USDT0**. Stable's OFT has the required peer configured for each destination and quotes successfully on-chain. The reverse source-side peers tested for Stable return an unset peer, so Trover deliberately does not advertise an unverified inbound direct route. That is a protocol deployment state, not a client-side API limitation. The optional Stargate fallback uses LayerZero's Value Transfer API: 1. Discover a supported EVM source chain and token. 2. Validate that it has a destination on Stable (`chainKey: stable`, chain `988`). 3. Return LayerZero's exact EVM user steps. The wallet signs required approval and bridge steps in order. 4. Poll LayerZero status using the opaque quote ID and final source tx hash. The LayerZero API key never reaches the browser. A `LAYERZERO_VTA_API_KEY` is required for quotes and status; chain/token discovery remains available without it. The implementation uses the quote's returned steps exactly—particularly it does not approve an LZMulticall wrapper as an ERC-20 spender. The bridge control is intentionally available only on `/stabledex`; token-terminal routes do not render it. ## Operations * `GET /v1/stabledex/network` reports all configured RPC endpoint health. * `GET /v1/stabledex/search?q=…` redirects a supplied Stable token contract address to its on-chain profile. * `GET /v1/stabledex/tokens/:address` returns on-chain ERC-20 metadata, v3 and v2 pools, USD price where a USDT0/WUSDT0 pair exists, FDV/market cap, recent swaps, chart points, and holders. StableDex uses public RPC transfer logs and current `balanceOf` reads for an immediate, clearly labelled holder observation, then upgrades it to the persisted Transfer-history holder index as the worker backfills it; it does not require an explorer/API key. Verified pool discovery is persisted to the shared market index. * `GET /v1/stabledex/tokens/:address/trades` returns the persisted public-RPC V2/V3 swap tape for that token's indexed pools; no third-party DEX API key or WebSocket subscription is involved. * `GET /v1/stabledex/pools` lists the recently indexed, active Stable pools. * `POST /v1/stabledex/quote` returns Stable Swap/Uniswap v3 approval and swap steps for the connected wallet to sign. * `GET /v1/stabledex/layerzero/direct/routes` returns only currently verified, API-free direct OFT routes. * `POST /v1/stabledex/layerzero/direct/quote` is Privy-authenticated and returns public-RPC-quoted OFT approval/send steps for the profile-owned wallet. * `GET /v1/stabledex/stargate/chains` lists LayerZero-supported EVM sources and resolves Stable dynamically. * `GET /v1/stabledex/stargate/routes` discovers destination assets on Stable for a source asset. * `POST /v1/stabledex/stargate/quote` is Privy-authenticated and returns validated Stargate user steps for the wallet that belongs to that profile. * `GET /v1/stabledex/stargate/status/:quoteId` is Privy-authenticated and returns the LayerZero lifecycle/explorer URL. Zerion is useful on chains it lists, but its live chain catalog does not currently include Stable. StableDex therefore uses Stable's native Uniswap v3 deployment for Stable swaps and LayerZero Stargate for bridge routes. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.trover.tech/engineering/stabledex.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.