🔄WCO Supply Information API

Overview

The WCO Supply Information API provides real-time data about the WCO token supply distribution, including circulating supply, locked supply, and burned tokens. This endpoint is essential for understanding the tokenomics and current state of WCO tokens in circulation.

Endpoint Details

URL: https://oracle.w-chain.com/api/wco/supply-info Method: GET Cache: 2 minutes TTL Authentication: None required

Response Structure

The API returns a comprehensive JSON response with the following structure:

{
  "timestamp": "2024-01-15T10:30:00.000Z",
  "cache": {
    "ttl_seconds": 120,
    "note": "This endpoint is cached for 2 minutes"
  },
  "summary": {
    "initial_supply_wco": "1000000000",
    "locked_supply_wco": "250000000.123456789",
    "burned_supply_wco": "5000000.987654321",
    "circulating_supply_wco": "744999999.888888890"
  },
  "raw": {
    "units": {
      "native": "WCO",
      "base": "wei",
      "wei_per_wco": "1000000000000000000"
    },
    "initial_supply_wei": "1000000000000000000000000000",
    "locked_supply_wei": "250000000123456789000000000",
    "burned_supply_wei": "5000000987654321000000000",
    "circulating_supply_wei": "744999999888888890000000000",
    "locked_supply_breakdown": [
      {
        "address": "0x1234...",
        "label": "validators-staking",
        "balance_wei": "200000000000000000000000000",
        "balance_wco": "200000000.0"
      },
      {
        "address": "0x5678...",
        "label": "vesting:team",
        "balance_wei": "50000000123456789000000000",
        "balance_wco": "50000000.123456789"
      }
    ],
    "burned_supply_breakdown": {
      "address": "0x0000000000000000000000000000000000000000",
      "label": "evm-zero-address",
      "balance_wei": "5000000987654321000000000",
      "balance_wco": "5000000.987654321"
    }
  },
  "methodology": {
    "formula": "circulating = initial_genesis_supply - (sum of locked addresses balances) - burned_balance",
    "data_sources": {
      "rpc_provider": "WCHAIN_RPC_PROVIDER",
      "multicall3_contract": "aggregate3 + getEthBalance"
    },
    "address_labels": {
      "validators_staking": "0x1234...",
      "vesting_contracts": {
        "team": "0x5678...",
        "advisors": "0x9abc..."
      },
      "burn_address": "0x0000000000000000000000000000000000000000"
    },
    "verification": {
      "how_to_verify": "Query each address balance on-chain or via any RPC, and confirm calculations match the formula."
    }
  }
}

Understanding the Response

Summary Section

The summary section provides human-readable WCO token amounts:

• initial_supply_wco: The total initial supply of WCO tokens at genesis

• locked_supply_wco: Total tokens locked in various contracts (staking, vesting, etc.)

• burned_supply_wco: Total tokens sent to the burn address (0x0000...)

• circulating_supply_wco: Tokens available for trading and transactions

Raw Data Section

The raw section contains precise wei-denominated values and detailed breakdowns:

• units: Explains the denomination system (1 WCO = 10^18 wei)

• *_supply_wei: Exact token amounts in wei (smallest unit)

• locked_supply_breakdown: Individual balances of each locked address

• burned_supply_breakdown: Details of tokens sent to burn address

Methodology Section

Provides transparency about data collection and calculation methods:

• formula: Mathematical formula used for circulating supply calculation

• data_sources: Technical details about data retrieval methods

• address_labels: Human-readable labels for contract addresses

• verification: Instructions for independently verifying the data

Calculation Methodology

Circulating Supply Formula

Circulating Supply = Initial Supply - Locked Supply - Burned Supply

Locked Supply Categories

1. Validators Staking Contract: Tokens staked by validators for network security

2. Vesting Contracts: Tokens allocated to team, advisors, and other stakeholders with time-based release schedules

Data Collection Process

1. Multicall3 Integration: Uses efficient batch calls to query multiple address balances simultaneously

2. Real-time Queries: Balances are fetched directly from the W-Chain RPC provider

3. Precision Handling: All calculations use BigInt to maintain precision with large numbers

4. Error Handling: Implements safeguards against negative circulating supply due to chain anomalies

Use Cases

For Developers

• DeFi Integration: Use circulating supply data for market cap calculations

• Analytics Dashboards: Display real-time tokenomics information

• Trading Applications: Incorporate supply metrics into trading algorithms

For Researchers

• Tokenomics Analysis: Study token distribution and unlock schedules

• Market Research: Analyze supply dynamics and their market impact

• Verification: Independently verify supply calculations using provided methodology

For Exchanges

• Market Data: Provide accurate circulating supply for market cap calculations

• Compliance: Maintain transparency about token supply for regulatory purposes

Data Freshness and Caching

• Cache Duration: 2 minutes (120 seconds)

• Update Frequency: Data refreshes automatically every 2 minutes

• Real-time Accuracy: Balances reflect the most recent blockchain state within cache window

Verification Guide

To independently verify the supply data:

1. Query Individual Addresses: Use any W-Chain RPC endpoint to query balances of addresses listed in methodology.address_labels

2. Sum Locked Balances: Add up all balances from validators staking and vesting contracts

3. Query Burn Address: Check balance of 0x0000000000000000000000000000000000000000

4. Apply Formula: Subtract locked and burned amounts from initial supply

5. Compare Results: Your calculation should match the API response

Error Handling

The API implements robust error handling:

• Network Issues: Automatic retries for RPC calls

• Invalid Responses: Graceful handling of malformed blockchain responses

• Negative Supply Protection: Clamps circulating supply to zero if calculation results in negative value

Rate Limiting

No explicit rate limiting is applied, but the 2-minute cache reduces the load on underlying blockchain infrastructure. For high-frequency applications, respect the cache TTL to optimize performance.

Support

For technical support or questions about this API:

• Check the verification methodology to ensure correct interpretation

• Review the raw data section for precise calculations

• Consult the W-Chain documentation for blockchain-specific details