> For the complete documentation index, see [llms.txt](https://docs.w-chain.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.w-chain.com/advanced-features/wpoints-public-api.md).

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

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

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

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

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

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

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

#### 404 Not Found

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

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