Topaz

Developers

Developer overview

Everything you need to read vault data, integrate deposits and withdrawals, and pull historical analytics — whether you're building a frontend, a bot, or a dashboard.

Three ways to integrate#

Pick the surface that matches what you're building:

EasiestData APIRead-only REST at /api/v1 — fully assembled vault state, metrics, user positions, and a per-vault integration manifest. No RPC plumbing.Most directSmart contractsRead and write on-chain: deposits, withdrawals, and zaps straight against the vault, strategy, and zapper contracts.AnalyticsSubgraphGraphQL for historical and derived data: APY, share-price history, TVL over time, and full user P&L.

Start with the Data API

If you only need to display vault data or build a deposit flow, the Data API already computes everything (TVL, APR/APY, in-range, pending rewards, P&L) and ships an integration manifest with the exact addresses, methods, and rules. Drop to raw contracts when you need to send transactions, and use the subgraph for time-series.

Network#

All contracts are on BNB Smart Chain (chainId 56). There are currently 10 CL vaults and 2 V2 vaults configured.

Never hardcode addresses

Load addresses from /api/v1/meta (and the per-vault manifest) or from src/config/deployments/frontend.bsc.jsonin this repo. The tables below are rendered from that same config so they can't drift, but treating the API/config as the source of truth keeps you correct across deployments.

Shared contracts#

ContractAddress
CL Zapper0x396717cAe3BCA595437619DD3AAE19aE4a76a982
CL Strategy Factory0x90D87F6c12933889F9882dDAFbE6a89845743d6B
V2 Zapper0xC6141AEAb5EA77A339AdEa098c1045F4bEfFcfa7
Swap Router (v3)0x9B63CA87919617d042A89663492dB3c8686e0CaE
Quoter (v3)0x7CCB89bB9BdEF68688F39a2c22d249fD1D9759f1
Router0x1E98c8226e7d452e1888e3d3d2F929346321c6c3

Per-vault contracts (vault, strategy) and the protocol positionManager are listed in Smart contracts and exposed by /api/v1/meta. A CL vault's pool is readable on-chain via strategy.pool(); its gauge is resolved from the Stats/Data API by pool and is included in each vault's manifest.

Protocol tokens#

TokenAddress
TOPAZ (reward)0xdf002282C1474C9592780618Adda7EaA99998Abd
WBNB0xbb4CdB9CBd36B01bD1cBaEBF2De08d9173bc095c
USDT0x55d398326f99059fF775485246999027B3197955

Conventions that make transactions succeed#

Whatever surface you use, these rules matter — getting them wrong is the usual cause of reverts:

  • Keep amounts as bigint/strings end-to-end. Native BNB value and token amounts are 18-decimal integers; converting through a JS number rounds the wei and can revert.
  • Slippage is mandatory. Every deposit/withdraw/zap takes a minShares / minAmount* guard — never pass 0 in production. Derive it from a preview or a static simulation.
  • Gate deposits & zap-ins on isCalm(). They revert when the pool isn't calm. Withdrawals and zap-outs are not gated.
  • Budget gas on zaps: gasLimit ≈ estimateGas × 2 (or a ~3M floor), especially for zapOut*.
  • Share decimals differ: CL vaults are 18-dec, V2 (ERC-4626) vaults are 24-dec. Always read decimals(); don't assume 1e18.
  • Handle the empty vault (totalSupply() == 0): the first deposit locks a tiny amount of dead shares.

Next#

Smart contracts →Data API →Subgraph →