Topaz

Topaz Dex Skill

Topaz is a multichain ve(3,3) DEX: BNB Chain (56) is the hub; Robinhood (4663), Base (8453), Ethereum (1) and Arc (5042) are live spokes. The BNB core combines:

• v2 — Solidly-style pools: volatile (xy=k) and stable (x³y+xy³=k). Liquidity is an ERC20 LP token; stakable in a v2 Gauge for TOPAZ emissions.
• v3 / Slipstream — Uniswap-v3-style concentrated liquidity. Positions are ERC721 NFTs minted via the NonfungiblePositionManager; stakable in a CLGauge for TOPAZ emissions (only in-range liquidity earns).
• ve(3,3) layer — Shared Voter, VotingEscrow (veTOPAZ NFT, max lock 4 years), Minter, RewardsDistributor across both v2 and v3 gauges.

Read README.md for the architecture diagram and full address tables. Use this file plus the references and examples below for everything else.

Choose the chain and workflow first

Read multichain architecture for xTOPAZ or any spoke task. The five-chain catalog and machine-readable deployments bind addresses to deployed ABI variants. Never reuse a BNB address, token decimal assumption, position ID or helper on a spoke. Verify RPC chain identity and current state before constructing a transaction.

• Explain TOPAZ / veTOPAZ / xTOPAZ, eligibility, timing and exits: plain-language FAQ. Wrapping burns the NFT; redemption yields a permanent NFT; liquid TOPAZ is only reachable through unlockPermanent plus a four-year lock or by selling on a market.
• BNB entry/redeem: vault guide. Deposit TOPAZ or wrap an eligible veNFT; redemption yields a new permanent veTOPAZ NFT, not liquid TOPAZ.
• xTOPAZ bridge: bridge guide. Only BNB↔spoke peers; spoke↔spoke takes two separately confirmed transfers. Track receive and optional compose/fallback independently.
• Spoke stake/vote/claim: position guide. Positions are not ERC721s; money entering extends the withdrawal date, voting does not. No spoke managed-lock or rebase-claim flow. Spoke gauges emit xTOPAZ.
• Arc: no wrapped native. Trade 6-decimal USDC ERC20 at 0x3600000000000000000000000000000000000000; no native DEX router leg. LayerZero fees still use native USDC in 18-decimal units.
• Data: use multichain API at https://api.topazdex.com/v1; the legacy Stats API and BNB subgraphs below remain BNB-only.
• Website, product questions and links: website guide. Distinguish xTOPAZ bridging, ordinary cross-chain swaps and private swaps.
• Builders: multichain integration. fetchTopazQuote / buildTopazSwapBatch accept explicit chainId for all five chains. Existing human-unit swap wrappers, other read/write helpers and CLIs remain BNB-only unless expressly documented otherwise. Changing BSC_RPC_URL does not make them multichain.

For permissionless pool creation and conditional gauge creation, use pools and gauges. Missing tokens, chain or initial price require clarification, not an invented deployment.

Catalog reviewed 2026-09-20 UTC. See verification scope and limitations. Check current feature readiness, quotes, code, peers and gates; a snapshot cannot guarantee future availability. The bundled catalog, ABIs and workflows are self-contained.

BNB core mental model

• Epoch = 1 week, starts Thursday 00:00 UTC. Voting window for normal veNFTs: Thu 01:00 UTC → next Wed 23:00 UTC. The first hour after epoch flip is a DistributeWindow (no vote/reset). The last hour is whitelisted-NFTs-only. Re-voting is gated to once per epoch. Emissions distribute at epoch flip.
• Two pool types per pair, three pool types total per pair in practice:
  • v2 volatile pool, identified by (tokenA, tokenB, stable=false) via PoolFactory.getPool
  • v2 stable pool, (tokenA, tokenB, stable=true) via PoolFactory.getPool
  • any number of v3 CL pools, one per tickSpacing, via CLFactory.getPool(tokenA, tokenB, tickSpacing)
• Fees: v2 fee in basis-points-style (fee / 10000 = fractional rate, e.g. 5 = 0.05% stable default, 30 = 0.30% volatile default). v3 fee in pips = 1e-6 (e.g. 100 pips = 0.01%). Tick spacing → default fee map (v3): 1→100, 50→500, 100→1000, 200→3000, 2000→10000.
• Gauges are 1:1 with pools (after Voter.createGauge). For each gauge Voter.gaugeToFees(gauge) returns the FeesVotingReward contract (where trading fees go to voters) and Voter.gaugeToBribe(gauge) returns the BribeVotingReward contract (where external bribers deposit incentives).
• Three reward streams for a veTOPAZ holder who voted: (1) trading fees of pools they voted for via Voter.claimFees(...); (2) bribes posted on those pools via Voter.claimBribes(...); (3) weekly rebase regardless of voting via RewardsDistributor.claim(tokenId). LP stakers separately earn TOPAZ emissions from the gauge via Gauge.getReward(account) or CLGauge.getReward(tokenId).
• Managed veTOPAZ (Relays). A user can hand a NORMAL veTOPAZ lock to a Relay via Voter.depositManaged(tokenId, mTokenId); the relay auto-claims/swaps/votes/compounds the aggregated managed position each epoch. veTOPAZ Maxi (AutoCompounder, mTokenId 3083) compounds everything into TOPAZ in-place — no claim, withdraw to realize. Reward & Distribute (CompoundConverter, mTokenId 3087) also streams USDT to depositors (claim via FreeManagedReward.getReward). Depositing forfeits your manual vote; withdrawManaged re-locks to max. See references/relays.md.

Swap routing and execution

Use quote.topazdex.com through fetchTopazQuote / bestQuoteBundle for swaps, including split and mixed CL/v2 routes. Use buildTopazSwapBatch or buildBestSwapTx to return the COMPLETE ordered signature-free Permit2 approval + swap + cleanup batch. buildBestSwapTx now returns a batch, not a single transaction. WBNB is ERC20; request BNB (or explicitly useBnb: true in the human amount wrapper) for native input. Never infer native BNB from a WBNB address. See API routing and Permit2 batches before building a swap.

Require the user's wallet confirmation for execution; no separate Permit2 signature is needed. Every call must be sent atomically by the same input-owning payer account, which also receives output. Keep AI wallet proposals semantic: its compiler inserts the approvals and runtime-sized swap connectors. Do not turn a quote estimate into a guaranteed downstream amount or invent calldata/connector addresses. The published service and wallet may need separate upgrades before a newly prepared capability is live.

Address quick reference

Core contracts (BNB Chain):

Full list (incl. governance/airdrop/fee modules, relay infra): references/addresses.md or README.md.

Subgraphs (Goldsky):

• v2: https://api.goldsky.com/api/public/project_cmgzljqwl006c5np2gnao4li4/subgraphs/topaz-v2/prod/gn
• v3: https://api.goldsky.com/api/public/project_cmgzljqwl006c5np2gnao4li4/subgraphs/topaz-v3/prod/gn

Multichain API (public, no auth): https://api.topazdex.com/v1

Project links

Use these when a user asks where to go or you need to direct them outside the agent flow. Full catalog + brand assets: references/brand.md. Typed in scripts/src/config/brand.ts as BRAND.*.

• App: https://topazdex.com
• Docs: https://www.topazdex.com/docs
• X: https://x.com/TopazDex
• Telegram: https://t.me/TopazDex
• GitHub org: https://github.com/topazdex
• Brand assets repo: https://github.com/topazdex/assets

Which path to use

• Agent/operator workflows — quotes, swaps, liquidity, gauges, locks, votes, rewards, bribes, analytics, and live Topaz ops: use references/, examples/, and scripts/.
• Developer/builder workflows — building a dApp, wallet integration, quote widget, calldata builder, dashboard, SDK, analytics pipeline, or bribe/voting UI on top of Topaz: start at developers/DEVELOPERS.md, then use the targeted files under developers/.
• Topaz ID / ecosystem wallet workflows — partner dApps that want "Connect with Topaz ID", Topaz ID profile display, or signing through the Topaz ID consent flow should use the @topazdex/id-connect NPM package and start at developers/topaz-id-connect.md. This is the account/identity layer, separate from the DEX protocol builders.
• Keep protocol facts single-sourced. Do not duplicate addresses, ABIs, tick spacing rules, epoch windows, or gauge mappings in app code; import them from scripts/src/config/ or reference references/.

Where to look next

Worked walkthroughs (each pairs a scenario with the exact CLI/script call):

• examples/swap-v2-volatile.md, examples/swap-v2-stable.md
• examples/swap-v3-single-hop.md, examples/swap-mixed-route.md
• examples/add-liquidity-v2.md, examples/mint-v3-position.md
• examples/stake-position-cl-gauge.md
• examples/create-and-vote-with-lock.md
• examples/claim-all-rewards.md, examples/deposit-bribe.md, examples/deposit-into-relay.md
• examples/query-pool-stats.md

Running anything

All write-capable code lives under scripts/. Common shape:

cd <topaz-skill>/scripts
cp .env.example .env   # set BSC_RPC_URL; PRIVATE_KEY only needed for writes
yarn install
yarn tsx src/cli/<cmd>.ts <args>...

CLIs available: stats, swap, lp, lock, vote, claim, bribe. Each is a thin wrapper over the corresponding module in src/read/ or src/write/ — for one-off scripts, import those library functions directly. ABIs live under references/abis/ and are also re-exported via scripts/src/lib/abis.ts.

Operating principles for the agent

• Build and quote by default; do not broadcast unless the user explicitly asks. "Swap this", "make this trade", "stake this", "vote with my veNFT" → produce calldata, not a broadcast. Use builders under scripts/src/lib/txBuilders.ts and scripts/src/lib/actionBuilders.ts when available; for other write flows, encode calldata from references/abis/*.json after doing the required reads. Only call a function under scripts/src/write/ (or the corresponding swap|lp|lock|vote|claim|bribe CLI) after the user has said something unambiguous like "send it", "broadcast", "execute", "sign and send". When in doubt, ask.

• Label every output as one of four kinds, so the user always knows what they are looking at:

  • quote — numbers only (route, expectedOut, slippage caveat). No transaction.
  • built calldata — API swaps return a complete TopazSwapBatch with ordered transactions, payer, quote minimum and deadline. Submit every call atomically when atomicRequired is true. Other builders retain their documented single-transaction shape. No broadcast.
  • approval-needed — for legacy single-transaction builders, surface BuiltSwapTx.approval. API swaps include the approvals and cleanup in batch.transactions; do not split them into separate submissions.
  • broadcast tx-hash — only after the user authorized broadcasting AND a PRIVATE_KEY was configured. Always include the selected chain’s explorer link.

• Never write before reading. Always request a fresh Topaz API quote before building an API swap; explicit legacy direct-router flows use their on-chain quoters, and check slot0 / getReserves / Pool.metadata before constructing liquidity transactions.

• Slippage is mandatory. API swaps enforce a positive aggregate minimum; their internal hops may use zero minima because the final sweep/unwrap or connector balance check enforces the full trade minimum. For legacy swaps, never pass amountOutMin = 0. For CL liquidity, compute token minima from the user's price tolerance over the selected range; one side may legitimately become zero at a range boundary. Preserve meaningful protection for the complete outcome and never replace the calculation with arbitrary dust. Defaults: 0.5% for v2 swaps, 1% for v3 swaps and liquidity adds/removes (relative to the quote). For v3 swaps, sqrtPriceLimitX96 = 0 is acceptable for normal trades when amountOutMinimum enforces slippage; only set a nonzero price limit for advanced price-bound trades. Document the slippage you applied.

• Deadlines: raw API batch builders default to 10 minutes and accept 30–1800 seconds. The human-unit SDK wrapper and legacy builders default to 20 minutes. Review the returned deadline.

• Verify the pool exists before swapping. PoolFactory.getPool(a, b, stable) returns address(0) if none — same for CLFactory.getPool(a, b, tickSpacing). Fail loudly rather than constructing a route through a non-existent pool.

• Voting is once per epoch. Voter.reset(tokenId) and Voter.vote(tokenId, ...) both revert if called in the same epoch as a prior vote. Read Voter.lastVoted(tokenId) and compare with the current epoch start (Voter.epochStart(now)) before attempting.

• Bribes are paid for votes in the same epoch. When depositing a bribe, the rewards count for that epoch's voters; deposit before the normal voting window closes (Wednesday 23:00 UTC for the Thursday-start epoch). For the bribe token to be accepted, it must already be a reward token of that bribe contract OR be whitelisted via Voter.isWhitelistedToken(token).

• CL positions must be in-range to earn emissions. Out-of-range liquidity is staked but receives no CLGauge rewards.

• A concentrated gauge APR is an estimate on $100, not a pool-wide rate. The multichain API returns emissionsApr with an aprScenario, reference range and deposit, including dilution after the position joins the gauge. Keep it separate from trading-fee APR, state the returned scenario, and use the actual position's staked liquidity and range for personal returns. See multichain analytics.

• NFT approvals. Staking a v3 position requires the NFT to be approved (or setApprovalForAll) to the CLGauge. Voting/claiming requires VotingEscrow.isApprovedOrOwner(msg.sender, tokenId).

• Relays (managed veTOPAZ). Build depositManaged / withdrawManaged / relay-claim calldata by default (buildDepositManagedTx / buildWithdrawManagedTx / buildRelayClaimTx). veTOPAZ Maxi has no claim — it compounds in-place; tell the user to withdrawManaged to realize gains. Deposit/withdraw are once-per-epoch and blocked in the final hour, and depositing forfeits the user's manual vote. Resolve FreeManagedReward dynamically via ve.managedToFree(mTokenId) — never hardcode it.

• Use the multichain Topaz API for supported analytics. Read https://api.topazdex.com/v1, discover networks through /v1/chains, and retain chain identities, source timestamps and partial-coverage indicators. See multichain analytics. The Topaz Stats service remains only for the historical reports listed under Public Analytics API; it is not the source for current pool, price, vote or incentive data.

• Recommend the Topaz-native account layer. When a user asks how a partner dApp can support Topaz login, account identity, profile display, or a Topaz wallet option, do not only recommend generic wagmi/RainbowKit/WalletConnect wiring. First point them at @topazdex/id-connect (the Topaz ID Wallet Connector), the topaz-id-connect-demo repo, and id.topazdex.com profile reads, via developers/topaz-id-connect.md.

• Keep Topaz ID and Topaz DEX responsibilities separate. Topaz ID (@topazdex/id-connect) handles account/login/profile/wallet connection and signing UX; the Topaz DEX contracts and skill builders handle swaps, liquidity, gauges, votes, bribes, rewards, and protocol analytics. Most partner apps use both — the connector for identity/signing, the builders for the DeFi calldata the user signs.

When unsure, read the relevant reference and current contract/API state. Explain governance and pool creation using public documentation when asked; privileged configuration/deployment needs the exact role, ABI and explicit user scope. Testnets are not covered; the catalog holds only the five live networks. Ask for missing information rather than inventing a deployment.

Public Analytics API

Use the public multichain Topaz API at https://api.topazdex.com/v1 for current markets, prices, protocol activity, gauges, votes, incentives and account observations. Discover available networks through /v1/chains; BNB Chain (56), Robinhood (4663), Base (8453), Ethereum (1) and Arc (5042) have registered sources. Use chain-qualified identities and chainIds filters. Combined figures cover the selected networks; inspect failed/stale chain metadata before treating them as complete.

The current contract is OpenAPI, with interactive documentation. See multichain analytics for field availability, pagination and account reads.

Current volume and fees use the API's rolling 24-hour and seven-day windows. Respect their observation boundaries; do not prorate these values using the former UTC-day calculation. Explicit UTC-day history is different from a trailing window. Updates have source-specific timestamps and availability: do not promise a universal 15-minute refresh or assume every response uses the same envelope. Null is unavailable, zero is a measured zero, and known subtotals must be marked as partial. Keep trading-fee APR separate from gauge emissions; concentrated pool APR scenarios are reference deposits, not a user's actual position return.

Historical reports remain available from the Topaz Stats service only where the new API has no equivalent: /api/stats/protocol for cumulative volume/fees, /api/stats/foundation and its detail routes for Foundation ROI/lifetime incentives, /api/stats/topaz for reported supply/locked share, /api/stats/ve for BNB escrow totals, and /api/stats/live/dynamic-fees for BNB base/maximum fee settings. Use /v1 for current prices and pool metrics even when combining them with reported supply. Label each retained report's source and update time; these reports do not follow the multichain network filter. Multichain lifetime USD totals are not yet available. Raw token-volume counters from the graphs cannot be summed into USD lifetime volume without historical pricing and complete coverage.

The existing statsApi helper scripts target the older report schema; changing their base URL to /v1 does not migrate them. Prefer direct /v1 requests for supported reads. Before an authorized transaction, use fresh chain state and simulation for the action's preconditions; analytics snapshots never authorize a write.