Mainnet and Testnet:

• The W Chain Mainnet is our fully operational network, where real-world applications are deployed securely and efficiently.

• The W Chain Testnet is a safe testing environment for developers to experiment, deploy, and fine-tune applications before launching on the Mainnet.

Hybrid Blockchain: W Chain’s hybrid model offers the best of both worlds—public blockchain for transparency and community-driven applications, and private blockchain for businesses that need tighter control over their data and operations.

High Performance: W Chain is built to handle thousands of transactions per second (TPS), ensuring that no matter the scale, your business can run smoothly without interruptions or delays.

Scalability: Our architecture is designed to grow with you. Whether you're a startup or a global enterprise, W Chain can scale to meet your needs with ease.

DeFi-Ready: Developers can quickly deploy decentralized finance applications, from staking mechanisms to complex lending and borrowing protocols.

Add the following Network Information to your Wallet App. Depends on your app choice, it may fall under "Add Custom Network" section.

Overview

In a Proof-of-Stake (PoS) Ethereum Virtual Machine (EVM) compatible blockchain, nodes form the foundational infrastructure that ensures the network’s functionality, security, and decentralization. Nodes are broadly classified into two categories—Validator Nodes and Non-Validator Nodes—each fulfilling specific roles within the ecosystem. This section provides a high-level introduction to these node types and their contributions to a PoS EVM network, setting the stage for detailed exploration in subsequent sections.

Node Types and Roles

Validator Node

Validator Nodes are active participants in the PoS consensus mechanism. By staking a required amount of cryptocurrency, these nodes are responsible for validating transactions, proposing new blocks, and finalizing them through a process known as "sealing." They play a critical role in maintaining the network’s security and integrity, earning staking rewards and transaction fees in return for their efforts.

Non-Validator Node

Non-Validator Nodes, identified by a seal: false configuration, do not engage in the consensus process or block production. Operating as full nodes or light nodes, they focus on synchronizing with the blockchain, verifying transactions and blocks for local use, and relaying data across the network. These nodes enhance accessibility, support decentralized data propagation, and provide infrastructure for applications and users without the resource-intensive demands of validation.

Network Contribution

Validator Nodes drive the core operations of block creation and consensus, ensuring the blockchain progresses securely and consistently. Non-Validator Nodes complement this by bolstering network resilience, enabling data availability, and facilitating broader participation. Together, they create a balanced and robust PoS EVM environment.

Welcome to W Chain

W Chain is a next-generation blockchain platform designed to bring trust, transparency, and efficiency to global payments and decentralized finance (DeFi). By combining the strengths of public and private blockchain technologies, W Chain provides businesses, developers, and users with a flexible and secure foundation to build innovative applications that scale with their needs.

What is W Chain?

W Chain is a hybrid blockchain platform that blends the openness and transparency of public blockchains with the control and security of private networks. This unique architecture ensures that businesses can operate with confidence, knowing they have the flexibility to maintain privacy where needed, while also benefiting from the decentralization of a public chain.

Our vision is simple: to create a world where financial transactions are fast, secure, and accessible to everyone, everywhere. Whether you’re sending cross-border payments, developing cutting-edge DeFi applications, or securing enterprise data, W Chain empowers you to do it all efficiently and cost-effectively.

This guide explains how to use the Trade page of W Swap. The interface is a familiar Uniswap V2-style experience adapted for W Chain (native token WCO) with the same core flow: connect a wallet, select tokens, approve if required, set slippage, and confirm the trade.

Overview

• Network: W Chain (EVM-compatible; native gas token WCO)

W Chain utilizes the Ethereum Virtual Machine (EVM) in the backend. Smart contracts are written in Solidity and they can function on W Chain as they do on Ethereum. To deploy a smart contract, you send a transaction containing your bytecode without specifying any recipients. After the contract is deployed, it will be available to all users of the W Chain network.

You don't have to write and deploy your smart contract manually like that, there many tools or frameworks that will help you write, test and deploy your smart contracts in better ways.

Foundry

Foundry is an open-source, modern development framework designed for writing, testing, and deploying Solidity smart contracts for Ethereum and other EVM-compatible blockchains. Written in Rust, it offers a fast, efficient, and developer-friendly environment with tools like Forge for compiling, testing, and deploying contracts, Cast for interacting with the blockchain via the command line, and Anvil for running a local Ethereum node for testing.

Foundry emphasizes simplicity, speed, and modularity, allowing developers to write robust tests in Solidity, debug contracts easily, and integrate with existing Ethereum tools. Its focus on a test-driven development approach and seamless integration with Git makes it a popular choice for building secure and scalable decentralized applications.

We recommend Foundry, as it natively use Solidity in its scripting, testing and deploying functionalities. You will never need to switch between different programming languages, use Solidity everywhere!

Here is the recommended settings for your foundry.toml:

Using this settings, you will be able to use the RPC in your CLI commands. Here are some examples:

Hardhat

Hardhat is an open-source, flexible, and extensible development environment for writing, compiling, testing, and deploying Solidity smart contracts for Ethereum and EVM-compatible blockchains. Built with JavaScript and Node.js, it provides a robust framework for developers to create, debug, and deploy smart contracts efficiently.

Key features include the Hardhat Network for local blockchain testing, a powerful task runner for automating workflows, and support for plugins to extend functionality. Hardhat’s intuitive API, detailed error reporting, and integration with tools like TypeScript and Ethers.js make it ideal for both beginners and experienced developers building secure, scalable decentralized applications.

Compared to Foundry, Hardhat will require you to switch contexts between Solidity and Javascript/TypeScript. This benefits developers with good Javascript background as it will use familiar testing modules, and share same contexts with Ethers JS, building early connection to UI/Frontend side of the dApp.

Here is a settings you can start from:

Verifying Smart Contract

We recommend you to use Foundry or Hardhat to build, deploy and to verify the source code on W Chain Block Explorer. If there's any situation you want to manually verify a smart contract, you can send the POST request to W Chain Block Explorer's API. Here's an example:

Endpoint

• Method: GET

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:

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...)

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

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

Calculation Methodology

Circulating Supply Formula

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

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

Proof of Stake (PoS) is a consensus mechanism used by blockchain networks like W Chain to secure the network and validate transactions. Unlike Proof of Work (PoW), which relies on miners solving complex cryptographic puzzles, PoS allows network participants (known as validators) to produce and validate new blocks based on the amount of cryptocurrency they hold and are willing to “stake” (lock up) as collateral.

The PoS mechanism reduces energy consumption compared to PoW, while also incentivizing participants to act honestly since they have a financial stake in the network.

How PoS Works in W Chain

In W Chain’s PoS implementation, validators are selected based on their staked tokens, and they are responsible for producing and validating blocks. Validators earn rewards for their work but can also face penalties if they act dishonestly or fail to perform their duties.

Here’s how the PoS mechanism functions in W Chain:

1. Validators Stake Tokens: To become a validator, participants must lock up (or stake) a minimum amount of W Chain tokens in a staking contract.

2. Block Validation: Validators are chosen to produce blocks based on the amount of tokens they have staked and their past performance. Once selected, the validator proposes a new block to be added to the blockchain.

3. Rewards and Penalties: Validators earn rewards for producing valid blocks. However, if they attempt to manipulate the network or act maliciously, they risk losing part or all of their staked tokens.

Staking in W Chain

Staking is the process by which participants lock up their W Chain tokens to become validators. Validators are essential for maintaining the network's security and producing new blocks. The more tokens a validator stakes, the higher their chances of being selected to validate blocks and earn rewards.

Benefits of Staking:

• Earning Rewards: Validators earn rewards for producing blocks and validating transactions.

• Network Security: Staking ensures that validators are financially motivated to act honestly, securing the network.

• Participation in Consensus: Validators play a key role in maintaining consensus and ensuring the blockchain operates smoothly.

Unstaking in W Chain

Unstaking is the process of withdrawing staked tokens from the validator set. Validators can only unstake all of their tokens at once. After unstaking, they are no longer eligible to validate blocks or earn rewards.

Important Considerations:

• Validators must unstake all tokens at once; partial unstaking is not allowed.

• After unstaking, validators no longer participate in block production or receive rewards.

Epochs and Validator Responsibilities

Epochs are a critical concept in W Chain’s PoS implementation. They define specific time frames (measured in blocks) during which a particular set of validators is responsible for block production.

How Epochs Work:

1. Epoch Duration: Each epoch lasts for a set number of blocks. The duration can be configured by node operators during the genesis block creation.

2. Validator Set Update: At the end of each epoch, the validator set is updated. Validators query the ValidatorSet Smart Contract to retrieve the new set of validators for the next epoch.

3. New Epoch Start: After the epoch block is produced, a new epoch begins with the updated validator set.

Why Epochs Are Important:

• Validator Rotation: Epochs ensure that the validator set is regularly updated, providing fairness and decentralization. New validators can join, and inactive or dishonest validators are removed.

• Staking and Unstaking: Validators can only join or leave the set at the end of an epoch, ensuring the stability of the network during each epoch.

Validator Responsibilities

Validators are responsible for:

1. Block Production: Validators propose new blocks to be added to the blockchain. This requires maintaining a consistent connection to the network and following the consensus rules.

2. Validating Transactions: Validators must ensure that all transactions in the proposed block are valid according to the network rules.

3. Staking and Security: Validators need to maintain their stake and ensure their node is operating correctly. Misbehavior or downtime can result in penalties or removal from the validator set.

Penalties and Slashing:

• Validators who act maliciously or fail to perform their duties may lose a portion of their staked tokens through a process called slashing. This incentivizes validators to act honestly and secure the network.

Proof of Stake Workflow in W Chain

1. Become a Validator:

• Stake the required minimum number of W Chain tokens.

• The validator becomes part of the validator set and is eligible to propose blocks.

1. Participate in Consensus:

• Validators are randomly selected to propose blocks based on the amount of staked tokens and their past performance.

• Validators validate transactions and propose a block to the network.

Earn Rewards:

• Validators earn W Chain token rewards for each valid block they produce.

1. Unstaking:

• Validators can choose to unstake their tokens, at which point they are removed from the validator set and cease participating in block production.

This section will guide you through setting up a Non-Validator Node on W Chain.

Step 1: Prepare the System

Before starting, ensure your system meets the minimum requirements for running a node:

• vCPUs: 2 or more

Bridge supported assets between W Chain and other networks using W Swap’s Bridge page. This guide covers supported chains and tokens, approvals, transaction statuses, and best practices.

Overview

• Networks Supported: Ethereum, BNB Chain, and W Chain

Provide and manage liquidity in constant-product AMM pools on W Chain. This guide covers creating positions, understanding LP tokens and fees, and safely removing liquidity.

Overview

• Network: W Chain (EVM-compatible; native gas token WCO)

• Model: a constant-product AMM (x·y = k)

• LP Tokens: Minted to represent your position; burned when removing liquidity

• Fees: 0.25% per trade paid to LPs (accrues within pool reserves)

Prerequisites

• A supported wallet (e.g., Rabby or Metamask) connected to W Chain.

• Sufficient WCO for gas.

• The two assets you want to deposit. If assets are on Ethereum or BNB Chain, bridge them first.

Add Liquidity

1. Open Liquidity or Add Liquidity page.

2. Select the token pair (Token A and Token B). You may paste contract addresses for custom tokens.

3. Enter an amount for one token; the UI computes the corresponding amount for the other token based on current pool price.

Notes:

• If a pool does not exist yet, your deposit sets the initial price. Carefully choose amounts to avoid unintended pricing.

• For new pools, higher slippage tolerance may be needed; the UI will guide you.

Remove Liquidity

1. Navigate to your position (e.g., Pool page or Your Liquidity).

2. Choose the position and select Remove.

3. If prompted, approve the router to spend your LP tokens (Approve LP).

Fees and Rewards

• Each trade pays a 0.25% liquidity fee to LPs, accruing inside the pool as additional reserves.

• Your portion of fees is implicit in the increased value of your LP tokens.

• Realization occurs when you withdraw liquidity (your redeemed amounts include fee accrual).

Risks and Best Practices

• Impermanent Loss: Price divergence between tokens can reduce your position value vs. holding.

• Slippage: Large deposits/withdrawals can move price; consider splitting actions.

• Smart Contract Risk: Use official UI and verified token addresses.

• Gas Costs: Keep WCO for approvals, adds, and removals.

Troubleshooting

• Approve Required: Approve both tokens before adding liquidity; approve LPs before removing.

• Insufficient Balance: Confirm balances on W Chain and consider bridging if needed.

• Transaction Reverted: Increase slippage tolerance or reduce deposit size.

FAQs

• How do I earn fees? Fees accumulate in the pool; your LP token share entitles you to a proportional claim when you withdraw.

• Can I add single-sided liquidity? a constant-product AMM requires balanced deposits; use a swap first if needed.

• Where can I see my positions? Use the Pool or Your Liquidity view in the DApp.

Coin & Token Transfer Watcher

This document explains how to use the Watched Addresses system to receive real-time webhook notifications for W Chain coin (WCO) transfers and ERC-20 token transfers involving your registered addresses.

The system provides:

• A CRUD API to manage watched addresses and webhook URLs

This section will guide you through setting up a Validator Node on W Chain.

Step 1: Prepare the System

Before starting, ensure your system meets the minimum requirements for running a node:

• vCPUs: 4 or more

• Memory: At least 16GB

• Disk Space: At least 1TB (SSD or NVMe recommended for optimal performance)

• Operating System: Ubuntu 20.04, 22.04, or 24.04

• Node JS v.22 and NPM v10 or newer

• Internet Connection: A broadband connection with at least 5Mbps upload/download speed.

It's possible to run a node from a local dedicated server, but it's recommended to run it on a professional cloud providers such as AWS, Digital Ocean, Azure or GCP.

Step 2: Install Dependencies

Make sure you have up-to-date version of Ubuntu, Git and NPM installed.

Step 3: Prepare Directory

Step 4: Download files from latest Release

To initiate a Node, you need the latest binary and genesis.json. It always available at .

You need to select the suitable binary based on your Operating System and architecture. You can contact your Cloud Computing Provider if you are not sure about yours.

In this guide, we will use the most common one: Linux (amd64), as it's widely used in AWS EC2 instances.

Download BInary File

In this example we are using v.1.0.6

After the download complete, print your directory contents to get the downloaded file name:

The file name will be in this format: "w-chain-node_" + version tag + system + "_" + architecture + ".tar.gz". Extract the file:

Rename the file (Optional, but important for better UX):

Download genesis.json

You don't need to change anything from this genesis.json, just make sure it exists in the same directory with your binary file.

Step 5: Verify Files

Make sure both binary file and genesis.json is correctly downloaded and in stored in same directory.

Turn the binary file into executable:

Verify the version:

[VERSION INFO] Release version = 1.0.6

Step 6: Initialize Keys and Blockchain Data Directories

This command will initialize data directory and validator keys:

You will see the newly created public keys printed like this:

You can copy-paste it to some quick note to be used in next steps. We will also need the Private Key of this newly created Public Key.

You will see a single line of string. This is the Private Key.

Same as above, copy the Private Key and store it somewhere safe, we will use it in next step.

When you are done, exit the text editor, no need to save anything. And go back to root directory of your Node:

Step 7: Create Server Config

The node is basically a server that will run 24/7, responding to queries and persisting blocks to database. Instead of passing the configs as flags to server command, it's strongly recommended to store the server configs in a json/yaml file.

Run this command (in /w-chain directory) to generate server config template:

You will see a file, default-config.json created.

Now, we will edit this config file to adjust with your actual server configuration.

genesis.json location

Path to Data Directory

Ports

Network section

Minimum Gas Price accepted and Seal flag

Step 9: Staking Contract

To join W Chain Network as a Validator Node, each node must stake at least 10,000,000 (10 Million) WCO. This is to ensure the Node operators to act honestly and follow the consensus, as any malicious act will result to stake slashing (rogue node will lose a part of its staked WCO).

Clone Staking Contract Script from W Chain Repository

It should create new directory: staking-contract. Enter the directory and install the node dependencies

The process will only take few seconds, run this command next:

This will copy the template .env and open it in a text editor, you will see this:

Replace your_private_key_here with the actual Private Key you copied . Do not change anything else, save and exit the text editor.

Step 10: Load up the Stake

The next important step is to fund the Validator address (Public Key) with WCO. Please remember, you need some WCO for gas fee, too! Ideally, you should have at least 10,000,001 WCO inside this address.

After you fund the address, go to /staking-contract directory and run the stake script:

Wait for the script to process, if everything is correct, you will get the transaction hash returned.

Next, we will register BLS Public Key (obtained ). Run this command:

Wait for the script to process the on-chain call, if everything is correct, you will get the transaction hash returned.

Step 11: Create a System Service

To keep your Node instance running as a background service, you need to define the service. Run this on your terminal (inside your server/instance).

The text editor will open a blank page. Copy-paste the texts below into it:

Then save and exit the text editor.

Step 12: Enable and Run the Node Service

After installing new service, you have to reload the service daemon and enable the service.

Then start the service:

Congratulations! Your node is now running and will start to catch up with the network, this may take few days, depends on the block-height and the I/O performance of your node.

Important Commands to Maintain and Monitor Your Node

Service

Logging

Overview

The Points API provides comprehensive access to user points data within the W-Chain ecosystem. These endpoints allow you to retrieve points information for individual users, leaderboards, and comparative analytics across different time periods and categories.

Base URL

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

Authentication

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

Common Parameters

Month Format

When specifying months in API calls, use the format: YYYY-MM

• Example: 2024-01 for January 2024

• Example: 2024-12 for December 2024

User Parameter

User addresses should be provided as Ethereum-compatible addresses (0x prefixed hex strings).

Endpoints

1. Monthly Leaderboard

Endpoint: GET /leaderboard Cache: 5 minutes Description: Retrieves the points leaderboard for a specific month, showing all users ranked by their total points.

Parameters

Example Request

Example Response

Response Fields

• user: Ethereum address of the user

• points: Total points earned by the user in the specified month

Notes

• Results are automatically sorted by points in descending order (highest first)

• Only includes users who earned points during the specified month

2. User Points Details

Endpoint: GET /user Cache: 5 minutes Description: Retrieves detailed points information for a specific user in a given month, including individual point entries with categories and transaction hashes.

Parameters

Example Request

Example Response

Response Fields

• category: The category/type of activity that earned the points

• points: Number of points earned for this specific activity

• created_at: ISO timestamp when the points were awarded

Notes

• Results are ordered by creation date (most recent first)

• Provides granular view of all point-earning activities

3. User Points by Category

Endpoint: GET /user-by-category Cache: 30 seconds Description: Retrieves aggregated points for a specific user grouped by category for a given month.

Parameters

Example Request

Example Response

Response Fields

• category: The category/type of activity

• points: Total points earned in this category for the specified month

Notes

• Results are sorted by points in descending order (highest category first)

• Provides a summary view of user's point distribution across activities

4. Current Month User Points

Endpoint: GET /user-by-current-month Cache: 1 minute Description: Retrieves the total points for a specific user in the current month.

Parameters

Example Request

Example Response

Response Fields

• points: Total points earned by the user in the current month

Notes

• Automatically uses the current month (no month parameter needed)

• Useful for real-time dashboards and current progress tracking

5. Points Comparison vs Last Month

Endpoint: GET /vs-last-month Cache: 1 minute Description: Compares a user's points between the current period and the corresponding period in the previous month, with intelligent date range handling.

Parameters

Example Request

Example Response

Response Fields

Current Period:

• current.points: Points earned in the current period

• current.period.start: Start date of current comparison period

• current.period.end: End date of current comparison period

Last Month Period:

• lastMonth.points: Points earned in the corresponding previous period

• lastMonth.period.start: Start date of previous comparison period

• lastMonth.period.end: End date of previous comparison period

Comparison Analytics:

• comparison.difference: Absolute difference in points (current - last month)

• comparison.percentageChange: Percentage change from last month (rounded to 2 decimal places)

• comparison.isFullMonthComparison: Boolean indicating if comparing full months or partial periods

Intelligent Date Range Logic

The endpoint uses smart date range comparison:

1. Late in Month (Day >= 28): Compares full months

   • Current: Full current month

   • Previous: Full previous month

2. Early/Mid Month (Day < 28): Compares equivalent date ranges

Use Cases

• Progress Tracking: Monitor user engagement trends

• Gamification: Show improvement or decline in user activity

• Analytics: Understand user behavior patterns over time

Error Handling

All endpoints return appropriate HTTP status codes and error messages:

400 Bad Request

Returned when required parameters are missing or invalid.

404 Not Found

Returned when no points data is found for the specified criteria.

Caching Strategy

Each endpoint implements intelligent caching to balance data freshness with performance:

Rate Limiting

No explicit rate limiting is enforced, but clients should respect the cache durations to optimize performance and reduce server load.

Data Categories

Common point categories include:

• trading: Points earned from trading activities

• staking: Points from staking WCO tokens

• liquidity_provision: Points from providing liquidity to pools

Best Practices

For Developers

1. Cache Awareness: Respect cache durations in your application logic

2. Error Handling: Implement proper error handling for 400/404 responses

3. Date Formatting: Always use YYYY-MM format for month parameters

4. Address Validation: Validate Ethereum addresses before making API calls

For Analytics

1. Trend Analysis: Use /vs-last-month for growth tracking

2. Category Insights: Use /user-by-category to understand user behavior

3. Leaderboard Tracking: Monitor /leaderboard for competitive analysis

For User Interfaces

1. Real-time Updates: Use /user-by-current-month for live progress displays

2. Historical Data: Use /user for detailed activity timelines

3. Comparative Views: Use /vs-last-month for progress indicators

Support

For technical support or questions about the Points API:

• Verify parameter formats match the documentation

• Check error messages for specific guidance

• Ensure user addresses are valid Ethereum addresses

• Consult the caching information for data freshness expectations

Overview

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 URL

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

Authentication

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

Common Response Format

All price endpoints return a consistent JSON structure:

Response Fields

• price: Current price of the asset in USD (number)

• asset: Token symbol/identifier (string)

• base_currency: Always "USD" for price denomination (string)

Supported Tokens

1. WCO Token Price

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

Example Request

Example Response

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

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 Price

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

Example Response

Price Calculation

WAVE USD price is calculated using the formula:

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

Future Token Support

Additional tokens will be added following the same patterns:

Endpoint Structure

Response Format

All future tokens will maintain the same response structure:

Implementation Patterns

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

Error Handling

Database Errors

When price data cannot be retrieved:

Missing Dependencies

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

• Returns appropriate error response

• Logs error details for debugging

• Maintains API consistency

Caching Strategy

WCO Token

• Cache Key: api_price_wco

• TTL: 60 seconds

• Strategy: Database query caching

• Invalidation: Time-based expiration

WAVE Token

• Cache Dependency: Inherits from WCO caching

• Additional Caching: Trading pair data may have separate caching

• Effective TTL: Minimum of dependent cache TTLs

Benefits

• Reduces database load

• Improves response times

• Maintains data freshness

• Handles high-frequency requests efficiently

Rate Limiting

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 Cases

For DeFi Applications

• 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 Platforms

• 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 Exchanges

• 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 Freshness

WCO Price Updates

• 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 Updates

• 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 Practices

For Developers

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

For High-Frequency Applications

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 Applications

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 Examples

JavaScript/TypeScript

Python

Monitoring and Observability

Health Checks

• Monitor API response times

• Track cache hit/miss ratios

• Alert on price data staleness

• Monitor database connectivity

Key Metrics

• Response Time: API endpoint latency

• Cache Efficiency: Cache hit percentage

• Data Freshness: Time since last price update

• Error Rate: Failed requests percentage

Support and Troubleshooting

Common Issues

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 Help

• 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.