PLANNED SPECIFICATION · V1

Reward real votes, securely

This specification defines how the Toplands Vote API will let a game server create a player vote session, confirm completion, and grant the reward exactly once.

Not live yetThese endpoints are the planned integration contract. They will not accept production requests until the protected backend is deployed.

View quick start Explore endpoints

How vote validation works

A secure flow from the game server to the player and back.

Create a vote session

Your game server sends a private player reference. Toplands returns a short-lived session ID and vote URL.

Open the vote page

Your client, launcher, website, or in-game command opens the returned URL in the player’s browser.

Player completes the vote

Toplands applies the anti-bot challenge and IP cooldown, then records the verified vote.

Validate and reward

Your game server checks the session and claims it. A completed vote can be rewarded only once.

Quick start

The recommended implementation for a launcher, website, or in-game vote command.

STEP 1

Create a vote session from your game server

Send an internal player identifier from your backend. Do not send passwords, e-mail addresses, or character information that Toplands does not need.

POST/v1/vote-sessions

curl -X POST https://api.toplands.com/v1/vote-sessions \
  -H "Authorization: Bearer YOUR_SECRET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "server_id": "srv_aden_01",
    "player_reference": "account_18427",
    "return_url": "https://yourserver.com/vote-complete"
  }'

Example response

{
  "session_id": "vs_8f2c91",
  "vote_url": "https://toplands.com/vote/vs_8f2c91",
  "status": "pending",
  "expires_at": "2026-10-20T21:30:00Z"
}

STEP 2

Open the returned URL for the player

The URL can be opened by a launcher button, your account panel, or an in-game command. The client never receives your secret API key.

// Launcher or website example
window.open(voteSession.vote_url, "_blank", "noopener,noreferrer");

Lineage II example

An in-game .vote command can ask the game server to create the session, then send the returned URL to the player through an HTML dialog.

STEP 3

Check whether the vote was verified

Poll only while the session is pending, or use a webhook when available. Stop checking after completion, expiration, or failure.

GET/v1/vote-sessions/{session_id}

{
  "session_id": "vs_8f2c91",
  "status": "verified",
  "vote_id": "vote_51ad7b",
  "voted_at": "2026-10-20T20:42:18Z",
  "next_vote_at": "2026-10-21T20:42:18Z",
  "claimed": false
}

STEP 4

Claim once, then grant the reward

Claiming is atomic and idempotent. If two game-server threads try to claim the same vote, only one receives permission to grant the reward.

POST/v1/votes/{vote_id}/claim

{
  "claimed": true,
  "vote_id": "vote_51ad7b",
  "player_reference": "account_18427"
}

Safe reward order

First claim the vote at Toplands, then persist a local reward log, and only then add the reward to the player.

Endpoint reference

The initial API surface stays intentionally small.

POST/v1/vote-sessions

Create a short-lived vote session for a player.

GET/v1/vote-sessions/{id}

Read the current session and cooldown status.

POST/v1/votes/{id}/claim

Consume a verified vote exactly once.

Implementation rules

These rules protect both the player and your reward economy.

Keep keys on the server

Never embed a secret API key in JavaScript, a launcher executable, HTML, or the game client.

Use opaque player references

Send an internal ID or a server-generated alias instead of personally identifiable information.

Reward only after claim

A visible success page is not proof. Trust only an authenticated API response with claimed: true.

Respect cooldowns

Use next_vote_at to show when the player may vote again and avoid unnecessary requests.

Ready for owner-dashboard integration

API keys, webhook settings, logs, and test mode will be managed from the server owner area.

Open owner dashboard