💯WPoints Public API

OverviewCopy Anchor Link

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 URLCopy Anchor Link

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

AuthenticationCopy Anchor Link

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

Common ParametersCopy Anchor Link

Month FormatCopy Anchor Link

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

• Example: 2024-01 for January 2024
• Example: 2024-12 for December 2024

User ParameterCopy Anchor Link

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

EndpointsCopy Anchor Link

1. Monthly LeaderboardCopy Anchor Link

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

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 DetailsCopy Anchor Link

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

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 CategoryCopy Anchor Link

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

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 PointsCopy Anchor Link

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

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 MonthCopy Anchor Link

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

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 HandlingCopy Anchor Link

All endpoints return appropriate HTTP status codes and error messages:

400 Bad RequestCopy Anchor Link

Returned when required parameters are missing or invalid.

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

404 Not FoundCopy Anchor Link

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

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

Caching StrategyCopy Anchor Link

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

Rate LimitingCopy Anchor Link

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

Data CategoriesCopy Anchor Link

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 PracticesCopy Anchor Link

For DevelopersCopy Anchor Link

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 AnalyticsCopy Anchor Link

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 InterfacesCopy Anchor Link

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

SupportCopy Anchor Link

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