W Chain Website

💯WPoints Public API

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

Parameter
Type
Required
Description

month

string

Yes

Month in YYYY-MM format

Example Request

GET https://oracle.w-chain.com/api/points/leaderboard?month=2024-01

Example Response

[
  {
    "user": "0x1234567890123456789012345678901234567890",
    "points": 15750
  },
  {
    "user": "0x0987654321098765432109876543210987654321",
    "points": 12300
  },
  {
    "user": "0xabcdefabcdefabcdefabcdefabcdefabcdefabcd",
    "points": 8900
  }
]

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

Parameter
Type
Required
Description

month

string

Yes

Month in YYYY-MM format

user

string

Yes

User's Ethereum address

Example Request

GET https://oracle.w-chain.com/api/points/user?month=2024-01&user=0x1234567890123456789012345678901234567890

Example Response

[
  {
    "category": "trading",
    "points": 500,
    "created_at": "2024-01-15T14:30:00.000Z",
    "hash": "0xabc123def456789..."
  },
  {
    "category": "staking",
    "points": 250,
    "created_at": "2024-01-14T09:15:00.000Z",
    "hash": "0xdef789abc123456..."
  },
  {
    "category": "liquidity_provision",
    "points": 1000,
    "created_at": "2024-01-13T16:45:00.000Z",
    "hash": "0x123456789abcdef..."
  }
]

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

  • hash: Transaction hash associated with the point-earning activity

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

Parameter
Type
Required
Description

month

string

Yes

Month in YYYY-MM format

user

string

Yes

User's Ethereum address

Example Request

GET https://oracle.w-chain.com/api/points/user-by-category?month=2024-01&user=0x1234567890123456789012345678901234567890

Example Response

[
  {
    "category": "trading",
    "points": 5500
  },
  {
    "category": "liquidity_provision",
    "points": 3200
  },
  {
    "category": "staking",
    "points": 1800
  },
  {
    "category": "referral",
    "points": 750
  }
]

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

Parameter
Type
Required
Description

user

string

Yes

User's Ethereum address

Example Request

GET https://oracle.w-chain.com/api/points/user-by-current-month?user=0x1234567890123456789012345678901234567890

Example Response

{
  "points": 8750
}

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

Parameter
Type
Required
Description

user

string

Yes

User's Ethereum address

Example Request

GET https://oracle.w-chain.com/api/points/vs-last-month?user=0x1234567890123456789012345678901234567890

Example Response

{
  "current": {
    "points": 8750,
    "period": {
      "start": "2024-01-01T00:00:00.000Z",
      "end": "2024-01-19T23:59:59.999Z"
    }
  },
  "lastMonth": {
    "points": 6200,
    "period": {
      "start": "2023-12-01T00:00:00.000Z",
      "end": "2023-12-19T23:59:59.999Z"
    }
  },
  "comparison": {
    "difference": 2550,
    "percentageChange": 41.13,
    "isFullMonthComparison": false
  }
}

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

    • Current: Month start to current date

    • Previous: Same date range in previous month

    • Example: If today is Jan 19, compares Jan 1-19 vs Dec 1-19

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.

{
  "statusCode": 400,
  "statusMessage": "Missing month parameter"
}

404 Not Found

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

{
  "statusCode": 404,
  "statusMessage": "Points not found"
}

Caching Strategy

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

Endpoint
Cache Duration
Reasoning

/leaderboard

5 minutes

Leaderboard changes relatively slowly

/user

5 minutes

Detailed history is relatively stable

/user-by-category

30 seconds

Category summaries may update more frequently

/user-by-current-month

1 minute

Current month data changes more frequently

/vs-last-month

1 minute

Comparison data needs to be relatively fresh

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

  • referral: Points from referring new users

  • governance: Points from participating in governance

  • bridge: Points from using cross-chain bridge functionality

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

PreviousWCO Supply Information APINextPublic Price API

Last updated