🔍 Verus Ticker API

🦎 CoinGecko Format (Individual Pool Entries)

Data Structure: Array format with individual pool entries for each converter

Pool Separation: Each converter creates separate pool entries (no aggregation)

Pool ID Format: Uses converter names as unique pool identifiers

Liquidity Calculation: Pool liquidity × currency weight (typically 25% for 4-currency pools)

Symbol Source: Uses Ethereum-standardized symbols from currency_contract_mapping.eth_symbol

Price Source: Direct from converter state data with volume-weighted calculations

💹 CoinMarketCap Format (Aggregated Pairs)

Data Structure: Object with sequential numeric keys ("0", "1", "2", etc.) for CMC DEX API compliance

Pair Aggregation: Same trading pairs from multiple converters are combined into single entries

Volume Aggregation: Sums volumes from all converters for the same currency pair

Price Aggregation: Volume-weighted average pricing across all instances

Symbol Source: Uses Ethereum-standardized symbols from currency_contract_mapping.eth_symbol

Contract Integration: Uses ERC20 contract addresses for base_id/quote_id fields

🌐 Coinpaprika Format (Aggregated Pairs)

Format Compatibility: VerusStatisticsAPI wrapper structure with {"code":"200000","data":{"time":timestamp,"ticker":[...]}}

Pair Aggregation: Same as CoinMarketCap - combines same trading pairs from multiple converters

Symbol Standard: Uses Ethereum-standardized symbols from currency_contract_mapping.eth_symbol

Data Structure: Array of ticker objects with symbol, volume, last, high, low, open fields

Exclusion Logic: Filters converter currencies and excluded chains

Price Fallback: When last_price = 0, uses (high + low) / 2 calculation

🧪 CMC I-Address Format (Aggregated Pairs - Testing)

Purpose: Testing endpoint using Verus i-addresses instead of ERC20 contract addresses

Pair Aggregation: Same aggregation logic as CoinMarketCap with unique pairs

Key Differences: Uses currency IDs (i-addresses) as base_id/quote_id instead of contract addresses

Data Structure: Identical to CoinMarketCap format but with i-address identifiers

Symbol Source: Uses Verus native currency names from currency_contract_mapping.vrsc_symbol

Format Structure: CoinMarketCap DEX API compatible with sequential keys ("0", "1", "2", etc.)

Use Case: Testing and validation of Verus native identifier integrations

Step 1: Converter Discovery and Filtering

Method: Call getcurrencyconverters("VRSC") RPC method to get all converters in the VRSC system

Filtering: Exclude converters listed in excluded_chains array: ["Bridge.CHIPS", "Bridge.vDEX", "Bridge.vARRR", "whales"]

Validation: Check each converter has fullyqualifiedname field and is not in exclusion list

Result: List of active converters that contain VRSC as a reserve currency

Current Count: 9 active converters (Bridge.vETH, Switch, Kaiju, vYIELD, SUPER🛒, NATI🦉, Pure, SUPERVRSC, NATI)

Step 2: Currency Weight Extraction

Method: For each converter, extract currencies array from converter discovery data

Weight Calculation: Each currency has a weight field (e.g., 25000000 = 0.25 or 25%)

Total Weight: Sum all currency weights in the converter (typically = 100000000 = 1.0 or 100%)

Currency Info: Extract currencyid, weight, and symbol for each currency in the converter

Validation: Ensure all currencies have valid weights and currency IDs

Step 3: Total Converter Liquidity Calculation (USD)

Step 3a: Get converter supply from discovery data (supply field)

Step 3b: Get converter-to-VRSC ratio using estimateconversion(converter_id, "VRSC", 1)

Step 3c: Get VRSC-to-USD price using estimateconversion("VRSC", "DAI.vETH", 1, via="Bridge.vETH") (DAI ≈ $1 USD)

Formula: Total Liquidity = Supply × Converter_to_VRSC_ratio × VRSC_USD_price

Example: Bridge.vETH supply × Bridge.vETH_to_VRSC_ratio × VRSC_USD_price = Total USD liquidity

Step 4: Pair Liquidity Calculation

Method: For each trading pair (base_currency, target_currency) in a converter

Weight Sum: Add the weight of base_currency + weight of target_currency

Formula: Pair Liquidity = Total_Converter_Liquidity × (Weight_Base + Weight_Target) / Total_Weight

Example: If VRSC (25%) + DAI.vETH (25%) in Bridge.vETH = 50% of total converter liquidity

Result: Pair liquidity represents the portion of total converter liquidity allocated to that specific trading pair

Step 5: Real Volume Calculation Method

Method: Call getcurrencystate(converter_name, "start_block,end_block,interval", volume_currency) for each currency in the converter

Block Range: Use current_block - 1440 to current_block (24-hour period with 1440 blocks ≈ 24 hours)

Multiple Calls: Make separate calls for each currency as the volume_currency parameter

Base Volume: Extract volume from getcurrencystate call using base_currency as volume_currency parameter

Target Volume: Extract volume from getcurrencystate call using target_currency as volume_currency parameter

Data Source: Real blockchain volume data from conversiondata.volumepairs in the response

Precision: All volumes returned as-is from blockchain (typically 8 decimal places)

Step 6: OHLC Price Data Extraction and Price Inversion

Method: Extract OHLC (Open, High, Low, Close) data from the same getcurrencystate calls used for volume

Source: Price data comes from conversiondata.volumepairs entries for the specific trading pair

Price Inversion: When necessary, invert prices using 1 / original_price to maintain proper base/target relationships

Direction Logic: Ensure price represents target_currency per unit of base_currency (e.g., DAI per VRSC)

Consistency: Use target_currency call data for OHLC to maintain consistency with volume methodology

Fallback: If no OHLC data available, set values to 0 or use fallback calculations

Step 7: Data Aggregation and Formatting

Pair Creation: Generate all possible trading pairs (base→target) for currencies within each converter

Volume Filtering: Only include pairs with volume > 0 (either base_volume > 0 or target_volume > 0)

Currency Mapping: Apply ERC20 symbol mapping from currency_contract_mapping for Ethereum compatibility

Exclusion: Filter out pairs involving converter currencies or currencies in excluded chains

Precision: Format all numeric values to 8 decimal places as strings to prevent scientific notation

Step 8: Endpoint-Specific Output Formatting

CoinGecko Format: Array of ticker objects with ticker_id, volumes, prices, pool_id, liquidity_in_usd

CoinMarketCap Format: Object with contract address composite keys, aggregated same-pair data

Coinpaprika Format: VerusStatisticsAPI wrapper with {"code":"200000","data":{"time":timestamp,"ticker":[...]}}

Caching: All endpoints have cached versions using 60-second TTL for performance optimization

📄 Example .env Configuration File

Setup Instructions: Create a .env file in the project root with your RPC credentials

Security Note: Never commit the actual .env file with real credentials to version control

📋 Complete Contract Address Mapping

Data Source: currency_contract_mapping contains ERC20 contract addresses for Verus currencies exported to Ethereum

Coverage: 14 currencies mapped to ERC20 contracts representing 99.8% of total trading volume

Structure: Each currency maps to {"address": "0x...", "eth_symbol": "SYMBOL", "vrsc_symbol": "VRSC_NAME"}

🏷️ Symbol Standardization

Verus Native (CoinGecko/CoinMarketCap): Uses original Verus currency names (DAI.vETH, MKR.vETH, tBTC.vETH)

ERC20 Standard (Coinpaprika): Uses Ethereum-standardized symbols (DAI, MKR, TBTC) from eth_symbol field

Contract Keys (CoinMarketCap): Uses contract address composite keys for unique pair identification

Fallback Logic: Currencies without ERC20 mapping retain their Verus native symbols

🔄 Cross-Chain Compatibility

Ethereum Integration: Contract addresses enable direct integration with Ethereum DeFi protocols

Token Names: Official Etherscan token names ("USD Coin", "Dai Stablecoin", "Wrapped Ether") for ecosystem familiarity

Address Validation: All contract addresses verified against live Ethereum blockchain data

Multi-Chain Support: Architecture supports future expansion to other blockchain networks

🆚 CoinMarketCap vs I-Address Endpoint Comparison

Purpose: The I-Address endpoint provides identical functionality to CoinMarketCap but uses Verus native identifiers for testing and validation

Usage:

🔗 Current Data Processing (All Endpoints)

Pair Generation: Each endpoint generates 57 unique trading pairs from active converters

Data Consistency: All endpoints use identical blockchain data with same block height

Volume Extraction: Direct volume data from individual converter pairs via getcurrencystate RPC calls

Price Calculation: OHLC data extracted from blockchain volume pairs

Result: 57 consistent pairs across all endpoints with different formatting and symbol standards

📈 Volume-Weighted Price Calculation

Methodology: Each price component weighted by its corresponding volume for accurate market representation

Formula: weighted_avg = Σ(price_i × volume_i) / Σ(volume_i)

OHLC Aggregation: High = max(all_highs), Low = min(all_lows), Open/Close = volume-weighted averages

Fallback Logic: When last_price = 0, use (high + low) / 2 for price calculations

🚫 Exclusion and Filtering Logic

Converter Currency Exclusion: is_converter_currency() removes basket currencies from trading pairs

Chain Exclusion: excluded_chains filters out problematic converters (Bridge.CHIPS, Bridge.vDEX, etc.)

Volume Filtering: Only pairs with base_volume > 0 OR target_volume > 0 are included

Contract Validation: Pairs without valid contract addresses use fallback symbol mapping

🔗 Contract Address Integration

Data Source: currency_contract_mapping in dict.py contains authoritative ERC20 contract addresses

Coverage: 15 currencies with ERC20 contracts, 99.8% volume coverage

Key Mappings:

• DAI.vETH → 0x6B175474E89094C44Da98b954EedeAC495271d0F (DAI)
• vETH → 0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2 (WETH)
• NATI.vETH → 0x0F5D2fB29fb7d3CFeE444a200298f468908cC942 (NATION)
• VRSC → 0x83D2944d5fC10A064451Dc5852f4F47759F249B6

Fallback Logic: Currencies without contracts use Verus native symbols

🚫 Converter Currency Exclusion

Exclusion Logic: is_converter_currency(currency_id) filters out multi-currency basket pairs

Excluded Converters: Bridge.vETH, SUPERVRSC, SUPER🛒, Switch, Kaiju, NATI🦉, Pure, vYIELD, whales, NATI

Reason: Converter currencies represent baskets, not tradeable pairs

Implementation: Applied across all endpoints (CoinGecko, CoinMarketCap, Coinpaprika)

📊 Price Aggregation Method

Quote Volume Weighting: When the same trading pair exists across multiple converters, the final last_price is calculated using volume-weighted averaging with quote volume as the weight. This ensures that higher dollar-value trades have more influence on the final price.

Formula: weighted_price = (price1 × quote_vol1 + price2 × quote_vol2) / (quote_vol1 + quote_vol2)

Applied to: /coinmarketcap, /coinmarketcap_cache, /coinmarketcap_iaddress, /coinmarketcap_iaddress_cache, /coinpaprika, /coinpaprika_cache