💹Public Price API

OverviewCopy Anchor Link

The W-Chain Price API provides real-time price data for tokens within the W-Chain ecosystem. Currently supporting WCO and WAVE tokens, this API delivers USD-denominated prices with caching for optimal performance. Future token additions will follow the same endpoint structure and response format.

Base URLCopy Anchor Link

https://oracle.w-chain.com/api/price

AuthenticationCopy Anchor Link

All Price API endpoints are publicly accessible and do not require authentication.

Common Response FormatCopy Anchor Link

All price endpoints return a consistent JSON structure:

{
  "price": 1.2345,
  "asset": "TOKEN_SYMBOL",
  "base_currency": "USD"
}

Response FieldsCopy Anchor Link

• price: Current price of the asset in USD (number)
• asset: Token symbol/identifier (string)
• base_currency: Always "USD" for price denomination (string)

Supported TokensCopy Anchor Link

1. WCO Token PriceCopy Anchor Link

Endpoint: GET /wco
Cache: 1 minute
Description: Retrieves the current USD price of WCO token from the latest price feed data.

Example Request

GET https://oracle.w-chain.com/api/price/wco

Example Response

{
  "price": 0.0234,
  "asset": "WCO",
  "base_currency": "USD"
}

Data Source

• Source: Internal price feed database (price_feed_wco table)
• Update Frequency: Real-time price feed updates
• Precision: Full decimal precision as stored in database
• Fallback: Returns null if no price data available

Technical Implementation

• Queries the most recent price entry from price_feed_wco table
• Implements 60-second caching to reduce database load
• Orders by timestamp descending to get latest price
• Handles database errors gracefully

2. WAVE Token PriceCopy Anchor Link

Endpoint: GET /wave
Cache: Inherits from WCO cache (1 minute)
Description: Retrieves the current USD price of WAVE token, calculated using WCO price and WAVE/WCO trading pair data.

Example Request

GET https://oracle.w-chain.com/api/price/wave

Example Response

{
  "price": 1.4567,
  "asset": "WAVE",
  "base_currency": "USD"
}

Price Calculation

WAVE USD price is calculated using the formula:

WAVE_USD_Price = WAVE_WCO_Rate × WCO_USD_Price

Where:

• WAVE_WCO_Rate: Latest trading pair price from pair ID 1
• WCO_USD_Price: Current WCO price from /api/price/wco

Data Sources

• Primary: Trading pair data (pair ID: 1) for WAVE/WCO rate
• Secondary: WCO USD price from internal price feed
• Dependencies: Requires both WCO price and trading pair data

Technical Implementation

• Makes internal API call to /api/price/wco for WCO price
• Fetches latest WAVE/WCO pair price using getLatestPairPricesById(1)
• Multiplies pair rate by WCO USD price for final WAVE USD price
• Inherits caching behavior from WCO endpoint

Future Token SupportCopy Anchor Link

Additional tokens will be added following the same patterns:

Endpoint StructureCopy Anchor Link

GET /api/price/{token_symbol}

Response FormatCopy Anchor Link

All future tokens will maintain the same response structure:

{
  "price": number,
  "asset": "TOKEN_SYMBOL",
  "base_currency": "USD"
}

Implementation PatternsCopy Anchor Link

New tokens will follow one of these implementation patterns:

1. Direct Price Feed (like WCO):
   • Dedicated price feed table
   • Direct USD pricing
   • Simple database query
2. Calculated Price (like WAVE):
   • Based on trading pair data
   • Calculated against base token (typically WCO)
   • Derived USD pricing

Error HandlingCopy Anchor Link

Database ErrorsCopy Anchor Link

When price data cannot be retrieved:

{
  "price": null,
  "asset": "TOKEN_SYMBOL",
  "base_currency": "USD"
}

Missing DependenciesCopy Anchor Link

For calculated prices (like WAVE), if dependencies are unavailable:

• Returns appropriate error response
• Logs error details for debugging
• Maintains API consistency

Caching StrategyCopy Anchor Link

WCO TokenCopy Anchor Link

• Cache Key: api_price_wco
• TTL: 60 seconds
• Strategy: Database query caching
• Invalidation: Time-based expiration

WAVE TokenCopy Anchor Link

• Cache Dependency: Inherits from WCO caching
• Additional Caching: Trading pair data may have separate caching
• Effective TTL: Minimum of dependent cache TTLs

BenefitsCopy Anchor Link

• Reduces database load
• Improves response times
• Maintains data freshness
• Handles high-frequency requests efficiently

Rate LimitingCopy Anchor Link

No explicit rate limiting is enforced, but the caching mechanism naturally throttles database queries. Clients should:

• Respect cache durations
• Avoid excessive polling
• Implement client-side caching for frequently accessed data

Use CasesCopy Anchor Link

For DeFi ApplicationsCopy Anchor Link

• Portfolio Valuation: Calculate total portfolio value in USD
• Trading Interfaces: Display current market prices
• Yield Farming: Calculate APY and rewards in USD terms
• Liquidity Pools: Price LP tokens and calculate impermanent loss

For Analytics PlatformsCopy Anchor Link

• Market Data: Real-time price tracking and charts
• Market Cap Calculations: Combine with supply data for market cap
• Price Alerts: Trigger notifications on price movements
• Historical Analysis: Track price trends over time

For Wallets and ExchangesCopy Anchor Link

• Balance Display: Show USD values of token holdings
• Trading Pairs: Price discovery for trading interfaces
• Order Books: Reference pricing for limit orders
• Fee Calculations: Calculate transaction fees in USD

Data FreshnessCopy Anchor Link

WCO Price UpdatesCopy Anchor Link

• Source: Real-time price feed system
• Frequency: Continuous updates based on market activity
• Latency: Sub-minute from price feed to API (with caching)

WAVE Price UpdatesCopy Anchor Link

• Source: Trading pair activity on W-Chain DEX
• Frequency: Updates with each trade in WAVE/WCO pair
• Latency: Depends on WCO price freshness + pair data updates

Best PracticesCopy Anchor Link

For DevelopersCopy Anchor Link

1. Handle Null Prices: Always check for null price values
2. Implement Fallbacks: Have backup pricing sources when possible
3. Cache Appropriately: Respect API cache durations in your application
4. Error Handling: Implement robust error handling for network issues

For High-Frequency ApplicationsCopy Anchor Link

1. Batch Requests: Group multiple price requests when possible
2. WebSocket Alternative: Consider WebSocket connections for real-time updates
3. Local Caching: Implement application-level caching
4. Rate Management: Avoid overwhelming the API with requests

For Financial ApplicationsCopy Anchor Link

1. Precision Handling: Use appropriate decimal precision for financial calculations
2. Timestamp Tracking: Track when prices were last updated
3. Audit Trails: Log price data usage for compliance
4. Backup Systems: Implement redundant price sources

Integration ExamplesCopy Anchor Link

JavaScript/TypeScriptCopy Anchor Link

// Fetch single token price
async function getTokenPrice(symbol) {
  try {
    const response = await fetch(`https://oracle.w-chain.com/api/price/${symbol.toLowerCase()}`);
    const data = await response.json();
    return data.price;
  } catch (error) {
    console.error(`Error fetching ${symbol} price:`, error);
    return null;
  }
}

// Fetch multiple token prices
async function getPortfolioValue(holdings) {
  const prices = await Promise.all([
    fetch('https://oracle.w-chain.com/api/price/wco').then(r => r.json()),
    fetch('https://oracle.w-chain.com/api/price/wave').then(r => r.json())
  ]);
  
  let totalValue = 0;
  holdings.forEach(holding => {
    const price = prices.find(p => p.asset === holding.symbol)?.price || 0;
    totalValue += holding.amount * price;
  });
  
  return totalValue;
}

PythonCopy Anchor Link

import requests
import asyncio
import aiohttp

def get_token_price(symbol):
    """Fetch token price synchronously"""
    try:
        response = requests.get(f'https://oracle.w-chain.com/api/price/{symbol.lower()}')
        response.raise_for_status()
        return response.json()['price']
    except requests.RequestException as e:
        print(f"Error fetching {symbol} price: {e}")
        return None

async def get_multiple_prices(symbols):
    """Fetch multiple token prices asynchronously"""
    async with aiohttp.ClientSession() as session:
        tasks = []
        for symbol in symbols:
            url = f'https://oracle.w-chain.com/api/price/{symbol.lower()}'
            tasks.append(session.get(url))
        
        responses = await asyncio.gather(*tasks)
        prices = {}
        
        for response, symbol in zip(responses, symbols):
            if response.status == 200:
                data = await response.json()
                prices[symbol] = data['price']
            else:
                prices[symbol] = None
        
        return prices

Monitoring and ObservabilityCopy Anchor Link

Health ChecksCopy Anchor Link

• Monitor API response times
• Track cache hit/miss ratios
• Alert on price data staleness
• Monitor database connectivity

Key MetricsCopy Anchor Link

• Response Time: API endpoint latency
• Cache Efficiency: Cache hit percentage
• Data Freshness: Time since last price update
• Error Rate: Failed requests percentage
• Dependency Health: WCO price availability for WAVE calculations

Support and TroubleshootingCopy Anchor Link

Common IssuesCopy Anchor Link

1. Null Prices: Check if price feed is active and database is accessible
2. Stale Data: Verify cache TTL settings and price feed updates
3. WAVE Price Errors: Ensure both WCO price and trading pair data are available
4. High Latency: Check database performance and network connectivity

Getting HelpCopy Anchor Link

• Verify endpoint URLs and request format
• Check for network connectivity issues
• Review error messages in API responses
• Monitor W-Chain network status for underlying issues

This API documentation covers the current implementation of WCO and WAVE price endpoints. As new tokens are added to the W-Chain ecosystem, they will follow similar patterns and be documented with the same level of detail.