🔄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 genesislocked_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 addressburned_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 calculationdata_sources: Technical details about data retrieval methodsaddress_labels: Human-readable labels for contract addressesverification: Instructions for independently verifying the data
Calculation Methodology
Circulating Supply Formula
Circulating Supply = Initial Supply - Locked Supply - Burned SupplyLocked Supply Categories
Validators Staking Contract: Tokens staked by validators for network security
Vesting Contracts: Tokens allocated to team, advisors, and other stakeholders with time-based release schedules
Data Collection Process
Multicall3 Integration: Uses efficient batch calls to query multiple address balances simultaneously
Real-time Queries: Balances are fetched directly from the W-Chain RPC provider
Precision Handling: All calculations use BigInt to maintain precision with large numbers
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:
Query Individual Addresses: Use any W-Chain RPC endpoint to query balances of addresses listed in
methodology.address_labelsSum Locked Balances: Add up all balances from validators staking and vesting contracts
Query Burn Address: Check balance of
0x0000000000000000000000000000000000000000Apply Formula: Subtract locked and burned amounts from initial supply
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
Last updated