# 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:

```json
{
  "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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.w-chain.com/advanced-features/wco-supply-information-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.