L2Ranks Developer & API Documentation

Complete integration reference for Lineage 2 server developers. Learn how to verify player votes, distribute automated rewards, receive HMAC-signed callbacks, and embed the responsive voting widget.

API v1.0 • REST & Webhooks

Pull Model (Server Poll)

Your L2 server or Web Account Panel periodically queries our REST API.

• GET /api/v1/server/votes/check

• POST /api/v1/server/votes/claim

• Perfect for automated game server daemon tasks.

Push Model (Webhooks)

L2Ranks immediately delivers an HTTP POST event to your webhook URL on confirmed vote.

• Signed with HMAC-SHA256 (X-L2P-Signature)

• Real-time delivery with retry queue

• Eliminates polling overhead

Embedded Widget

Embed our responsive voting widget directly into your server website or player panel.

• Auto-fills player account name

• Instant voting flow

• CSP frame-ancestors domain security

1. Authentication & API Credentials

All REST API calls to L2Ranks require Bearer authentication using your server's signing secret.

Include your API secret in the standard Authorization HTTP header on all requests:

Authorization: Bearer sec_live_your_hmac_secret_key

Security Best Practice

Never share your Signing HMAC Secret in client-side code or public Git repositories. Keep it inside your server environment variables or server.properties file.

2. Reward Verification Flow (Check & Claim)

GET /check & POST /claim

The two-step verification protocol guarantees that in-game rewards are granted exactly once per 12-hour vote window.

Step 2.1: Check If Player or IP Has Voted

Account Name or IP Address

GEThttps://l2ranks.com/api/v1/server/votes/check?account_name=PLAYER_NAME

GEThttps://l2ranks.com/api/v1/server/votes/check?ip=203.0.113.195

Query Parameters:

account_name (string, optional): Player character login name or account identifier.
character_name (string, optional): In-game character name.
ip (string, optional): Player's IP address (e.g. 203.0.113.195). Allows your server to verify votes by client IP even if the player didn't type their character name. Also accepts voter_ip.
hours (integer, optional, default: 12): Rolling voting cycle window in hours (between 1 and 720).
Note: At least one identifier (account_name, character_name, or ip) is required.

Terminal cURL Example (Check by Account Name)

curl -s -X GET "https://l2ranks.com/api/v1/server/votes/check?account_name=player1" \
  -H "Authorization: Bearer sec_live_your_hmac_secret_key" \
  -H "Accept: application/json"

Terminal cURL Example (Check by IP Address)

curl -s -X GET "https://l2ranks.com/api/v1/server/votes/check?ip=203.0.113.195" \
  -H "Authorization: Bearer sec_live_your_hmac_secret_key" \
  -H "Accept: application/json"

Example JSON Response (Unclaimed Vote Found):

{
  "hasVoted": true,
  "vote": {
    "voteId": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
    "accountName": "dark_login_01",
    "characterName": "BloodKnight",
    "voterIp": "203.0.113.195",
    "is_logged_in": true,
    "isLoggedIn": true,
    "authMode": "LOGGED_IN",
    "votedAt": "2026-11-08T18:15:30.000Z",
    "votedAtUnix": 1794161730,
    "nextVoteAt": "2026-11-09T06:15:30.000Z",
    "ownerSignatureVerified": false,
    "rewardClaimed": false,
    "rewardClaimedAt": null
  },
  "serverTimeUnix": 1794161800
}

is_logged_in (boolean): Informs your server whether the voter was logged into an active L2Ranks registered user account (true) or cast their vote as an unauthenticated guest (false). You can give extra in-game perks or reward multipliers to registered voters!

Example JSON Response (No Active Votes):

{
  "hasVoted": false,
  "vote": null,
  "serverTimeUnix": 1794161800
}

Step 2.2: Acknowledge & Claim In-Game Reward

Optional

POSThttps://l2ranks.com/api/v1/server/votes/claim

Optional: Calling this endpoint is optional if you manage reward deduplication internally. If you want L2Ranks to track player reward statuses for you, call this endpoint once you have granted the in-game reward (e.g. Festival Adena or Coin of Luck) in your game database. This marks the vote record as rewardClaimed: true and enables delivery tracking in your server dashboard.

Terminal cURL Example (Claim Reward)

curl -s -X POST "https://l2ranks.com/api/v1/server/votes/claim" \
  -H "Authorization: Bearer sec_live_your_hmac_secret_key" \
  -H "Content-Type: application/json" \
  -d '{"account_name": "dark_login_01", "ip": "203.0.113.195"}'

Example Success Response:

{
  "success": true,
  "claimedAt": "2026-11-08T18:16:02.000Z",
  "voteId": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
  "accountName": "dark_login_01",
  "is_logged_in": true
}

3. Outbound Webhook & Callback Specifications

Push Notification

When configured, L2Ranks automatically transmits an HTTP POST event to your webhook URL whenever a player confirms a vote.

Webhook Event Schema (JSON)

{
  "event": "vote.confirmed",
  "voteId": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
  "serverId": "YOUR_SERVER_UUID",
  "accountName": "player_character_01",
  "characterName": "GladiatorX",
  "voterIp": "84.232.11.90",
  "votedAt": "2026-11-02T00:30:00.000Z",
  "nextVoteAt": "2026-11-02T12:30:00.000Z"
}

How to Verify the HMAC-SHA256 Signature Header

Every webhook request includes an X-L2P-Signature HTTP header containing a hexadecimal HMAC-SHA256 hash calculated over the raw request body using your secret key. This guarantees the webhook originated from L2Ranks and has not been forged or tampered with.

<?php
// Retrieve the raw request body and signature header
$rawPayload = file_get_contents('php://input');
$receivedSignature = $_SERVER['HTTP_X_L2P_SIGNATURE'] ?? '';
$secret = 'sec_live_your_hmac_secret_key';

// Compute the expected HMAC-SHA256 hash
$computedSignature = hash_hmac('sha256', $rawPayload, $secret);

// Timing-attack safe comparison
if (!hash_equals($computedSignature, $receivedSignature)) {
    http_response_code(401);
    exit(json_encode(['error' => 'Invalid webhook signature']));
}

// Signature is authentic! Process vote reward:
$event = json_decode($rawPayload, true);
$account = $event['accountName'];

// 1. Deliver reward in Lineage 2 database
// giveRewardToAccount($account, 4037, 5);

// 2. Acknowledge delivery
http_response_code(200);
echo json_encode(['received' => true]);

Recommended Callback Response:

Your endpoint should return an HTTP 200 OK with body {"received": true} within 5 seconds. If your endpoint times out or returns a 5xx error, delivery will be marked as failed.

4. Responsive Voting Widget Embed

widget.l2ranks.com

Embed a fast, lightweight voting form on your community website.

Copy and paste this HTML iframe code onto your website's vote page:

<iframe
  src="https://l2ranks.com/widget/YOUR_SERVER_UUID?account_name=PLAYER_ACCOUNT"
  width="100%"
  height="450"
  frameborder="0"
  allowtransparency="true"
  title="Vote on L2Ranks">
</iframe>

Cross-Origin Framing Protection (CSP)

For security, our widget sends a Content-Security-Policy: frame-ancestors header. Ensure you enter your website URL in the Allowed Embed Domains field in your server dashboard.