Topaz data API

Multichain coverage

Topaz analytics cover BNB Chain (56), Robinhood Chain (4663), Base (8453), Ethereum (1) and Arc (5042). Protocol totals combine the selected networks; a network filter applies to the metrics, chart and pool list. Pool and token identities always include both chain ID and contract address.

Begin with GET /v1/chains. Use chainIds for collections and explicit chainId/address paths for individual entities. Capabilities and coverage are per network; deployment alone does not establish indexed data availability.

Base URL and format

Base origin: https://api.topazdex.com. Read-only public endpoints return JSON over HTTPS with CORS. The website’s /api routes are compatibility forwards for older clients; integrations should call the API service directly.

Example: https://api.topazdex.com/v1/protocol?chainIds=56,4663,5042. Omit chainIds to request the API’s all-network scope; inspect the returned chain IDs.

Discovery and reference

OpenAPI · Interactive docs · API catalog.

Generate clients from https://api.topazdex.com/openapi.json. Do not reuse a compatibility endpoint’s schema for /v1.

Responses, identity and pagination

Success responses use ok, data and endpoint-specific meta, with pageInfo on paginated collections. Schemas differ by endpoint family. Validate consumed fields, chain IDs, contract addresses, requested epochs and source identity.

Follow pageInfo.nextCursor until hasNextPage is false. Keep filters and the pinned publication consistent. An expired or replaced publication requires a fresh traversal, not concatenation across snapshots. A page-size limit is not a complete inventory.

Observations and caching

Headline 24-hour and seven-day figures use the API’s rolling windows. Each network has its own indexed observation boundary; combined totals sum those independently observed windows. They are not a synchronized cross-chain block. No browser-side proration of yesterday’s totals is applied.

A missing value is not zero. A known subtotal is displayed with + when complete valuation or network coverage is unavailable. Charts mark partial periods and preserve gaps. Response generation and cache times are not the time the underlying chain state was observed.

Use indexedAt, snapshotAt, availableAt and the endpoint’s observation metadata as documented. generatedAt and cacheTtlSeconds describe serving; neither establishes a new chain observation. Stale/failed chain IDs and complete/known-value fields carry meaningful coverage information.

Failures

Check HTTP status and structured error codes. An unavailable chain, unsupported feature, missing entity, invalid query and incomplete history are different states. A failed refresh must not relabel a cached total as a new complete observation.

Protocol

GET /v1/protocol returns per-chain observations and totals for eligible user-pool liquidity, counts and rolling day/week flows. Policy metadata excludes backing, bridge balances, holders, prices and APRs from additive protocol metrics.

GET /v1/protocol/history and /v1/protocol/daily return period flows and TVL observations. The default alignment is rolling; use alignment=utc for calendar-day charts. /stats explicitly requests UTC charts. GET /v1/protocol/trailing returns requested windows with coverage.

Pools

GET /v1/pools lists chain-qualified markets. GET /v1/pools/{chainId}/{poolAddress} returns one pool; /history, /daily, /trailing and /ticks provide metric-specific observations. Use scope=all when the intended universe extends beyond curated pools.

Pool fields retain rolling volume and fees, separate feeApr/emissionsApr, fee-mode flags and pricing/range evidence. Excluded pools or unknown valuations cannot be silently inserted as zeros.

Tokens and prices

GET /v1/tokens and /v1/tokens/{chainId}/{tokenAddress} expose metadata and market observations. /prices, /price-history, /price-changes and /trailing use their documented observation boundaries. GET /v1/prices supports batch valuation.

GET /v1/token-lists, /v1/token-lists/{chainId}, /v1/categories and /v1/curation expose catalog and category metadata. Supply, market cap and holder counts are not implied by a token’s price response.

Gauges

GET /v1/gauges and /v1/gauges/{chainId}/{gaugeAddress} describe indexed gauges. /history, /rewards and /bribes provide scoped observations. Keep user-pool gauges, system gauges, killed gauges and mapping support distinct.

Votes, epochs and funding

GET /v1/votes supports the documented event/current views. GET /v1/epochs and /v1/epochs/{chainId}/{epochStart} describe epoch observations. GET /v1/markets/bribes supplies per-epoch notified funding; /v1/bribes and chain-qualified pool/gauge /bribes routes expose funding records.

Notified funding, claimed rewards, rolling trading fees and gauge emission rates are different quantities. A public voting display is not authority to sign a transaction.

Accounts and governance

GET /v1/accounts/{address}/portfolio, /liquidity-positions, /voting-positions, /votes, /rewards, /activity and /xtopaz are chain-scoped account reads. Indexed inventory may lag a confirmed receipt. Read the deployment, ownership, custody and claim evidence required by the action before signing.

The interface retains direct contract and subgraph reads where needed for transaction preconditions, receipt recovery or account acceptance. The broad hub account API gate remains separate from enabled spoke position discovery.

xTOPAZ and bridging

GET /v1/xtopaz, /v1/xtopaz/rate-history and /v1/xtopaz/epochs report share accounting. GET /v1/bridge and /v1/bridge/{guid} report indexed messages. Canonical supply and backing are counted once; independent chain observations can leave reconciliation incomplete.

Topaz Auto vaults

GET /v1/auto-manage/vaults lists Topaz Auto vaults on BNB Chain, Robinhood Chain and Arc, with each vault’s pool, tokens, range, principal, reward fee and estimated APR. GET /v1/auto-manage/vaults/{chainId}/{vault} returns one vault; /history, /rebalances and /activity return its principal history, range resets and deposit, redemption and claim events.

The API reads each vault’s contract when asked and indexes its events; a vault whose live read failed returns its last indexed state, marked as such. Transactions should read the vault and lens contracts directly.

Observed pool fees

Read feePips and the customFee/dynamicFee flags from /v1/pools and pool details. Indexed observations are not live execution quotes. The current public market response does not supply dynamic base/maximum settings.

Compatibility exceptions

The interface temporarily retains compatibility reports for Foundation ownership/allocation/incentive history and ROI, TOPAZ supply/locked shares, public veTOPAZ escrow/power totals and BNB dynamic-fee settings; cumulative volume uses /v1/protocol/volume. These reports have independent timestamps and definitions; they are not combined multichain snapshots.

Do not build new market or protocol integrations on /api/stats. See methodology for the interface’s current exceptions.

Deployment and health

GET /v1/deployments, /v1/health and /v1/health/chains expose deployment and service observations. Use /v1/chains feature status before requesting a capability.

Schema evolution

Allow additive fields while validating the values and identities you consume. Re-import generated clients when required fields or semantics change. Methodology versions identify calculations; they do not make incompatible response shapes interchangeable.

Continue reading

API reference · OpenAPI · Stats · Methodology · Multichain integration