Vote Rewards API Integration Guide

X-API-Key: mg_live_5bef...1a70

GET /api/v1/vote/check?player_id=PlayerName HTTP/1.1
Host: metin2.gg
X-API-Key: mg_live_YOUR_KEY_HERE

GET /api/v1/vote/unclaimed?limit=50&player_id=PlayerName HTTP/1.1
Host: metin2.gg
X-API-Key: mg_live_YOUR_KEY_HERE

{
  "votes": [
    {
      "vote_id": "550e8400-e29b-41d4-a716-446655440000",
      "player_id": "PlayerName",
      "voted_at": "2026-03-02T14:30:00Z"
    },
    {
      "vote_id": "660e8400-e29b-41d4-a716-446655440001",
      "player_id": "PlayerName",
      "voted_at": "2026-03-02T14:32:00Z"
    }
  ],
  "count": 2
}

POST /api/v1/vote/claim HTTP/1.1
Host: metin2.gg
Content-Type: application/json
X-API-Key: mg_live_YOUR_KEY_HERE

{
  "vote_ids": [
    "550e8400-e29b-41d4-a716-446655440000",
    "660e8400-e29b-41d4-a716-446655440001"
  ]
}

{
  "claimed": 2,
  "requested": 2
}

POST https://your-server.com/api/vote-webhook HTTP/1.1
Content-Type: application/json
X-Metin2GG-Signature: a1b2c3d4e5f6...

{
  "event": "vote.created",
  "vote_id": "550e8400-e29b-41d4-a716-446655440000",
  "server_id": "your-server-uuid",
  "player_id": "PlayerName",
  "voted_at": "2026-03-02T14:30:00Z",
  "timestamp": "2026-03-02T14:30:01Z"
}

# Python 3 backend adapter example, not a drop-in reward implementation.
# REQUIRED storage adapter:
# require_authenticated_player(session): resolve a trusted, logged-in local
# account to its exact vote player_id; reject anonymous/client-supplied identity.
# award_once(server_id, vote_id, player_id): in ONE database transaction,
# INSERT a receipt with UNIQUE(server_id, vote_id), grant the configured reward,
# and COMMIT. Existing receipt must match the same player.
# Return "committed" or "already_committed" ONLY after durable commit.
# Never mark the receipt committed before the reward transaction succeeds.
import json
import os
import ssl
from urllib.parse import urlencode
from urllib.request import Request, build_opener, HTTPSHandler, HTTPRedirectHandler
from uuid import UUID

class NoRedirect(HTTPRedirectHandler):
    def redirect_request(self, req, fp, code, msg, headers, newurl):
        raise RuntimeError("API redirect refused")

def api_request(path, body=None, query=None):
    key = os.environ["METIN2GG_API_KEY"]
    if not key:
        raise RuntimeError("API key is not configured")
    url = "https://metin2.gg/api/v1/vote/" + path
    if query:
        url += "?" + urlencode(query)
    headers = {"X-API-Key": key, "Accept": "application/json"}
    data = None
    if body is not None:
        headers["Content-Type"] = "application/json"
        data = json.dumps(body).encode("utf-8")
    request = Request(url, data=data, headers=headers,
                      method="POST" if data is not None else "GET")
    opener = build_opener(HTTPSHandler(context=ssl.create_default_context()), NoRedirect())
    with opener.open(request, timeout=10) as response:
        if response.status != 200:
            raise RuntimeError("API request failed")
        return json.load(response)  # Errors propagate; no reward on failure.

def process_vote_rewards(session, storage):
    player_id = storage.require_authenticated_player(session)
    if not isinstance(player_id, str) or not player_id:
        raise ValueError("Authenticated local player required")
    server_id = os.environ["METIN2GG_SERVER_ID"]
    UUID(server_id)
    pending = api_request("unclaimed", query={"limit": 50, "player_id": player_id})
    if not isinstance(pending, dict) or not isinstance(pending.get("votes"), list):
        raise ValueError("Invalid API response")
    acknowledged = []
    for vote in pending["votes"]:
        if not isinstance(vote, dict):
            raise ValueError("Invalid vote")
        if vote.get("server_id", server_id) != server_id:
            raise ValueError("Wrong server")
        if vote.get("player_id") != player_id:
            continue
        vote_id = str(UUID(vote["vote_id"]))
        receipt = storage.award_once(server_id, vote_id, player_id)
        if receipt not in ("committed", "already_committed"):
            raise RuntimeError("No committed local receipt")

        # Claim ONLY after the receipt and reward are durably committed.
        # If this request fails, retry later: award_once must find the receipt
        # and skip a second award. Keep a reconciliation queue for failed ACKs.
        result = api_request("claim", body={"vote_ids": [vote_id]})
        if (not isinstance(result, dict) or result.get("requested") != 1 or
                result.get("claimed") not in (0, 1)):
            raise ValueError("Invalid acknowledgement")
        acknowledged.append(vote_id)
    return acknowledged

# Run inside an authenticated server command, or adapt a trusted scheduled
# worker with an explicit local-account mapping. Never pass a URL player name
# directly as an authenticated session. Do not call GET /check as a probe:
# it consumes the vote before your local reward transaction can commit.
# Test mocks first; do not manufacture production votes or rewards.

-- UI-only integration sketch, not an authorization or reward handler.
-- The game client may open a menu or request the existing /reward command.
-- No API key, HTTP request, item grant, or client "voted" flag belongs here.
--
-- Required backend /reward handler:
-- 1. Authenticate the connected session and resolve its local player account.
-- 2. Rate-limit the request and ignore any client-supplied player/server ID.
-- 3. Call the server-side polling + persistent receipt adapter below.
-- 4. Send the actual committed result back to the player.
--
-- An NPC quest can display instructions. It must not interpret cmdchat,
-- a URL parameter, or a client callback as proof that a player voted.
-- Wire the menu to your existing authenticated server-command mechanism;
-- its syntax depends on your server implementation.

<?php
// PHP 8 server-side adapter example — requires your own authenticated session
// resolver and transaction-backed awardOnce implementation. No public $_GET API.
function voteApi(string $path, ?array $body = null, array $query = []): array {
    $key = getenv('METIN2GG_API_KEY');
    if (!$key) {
        throw new RuntimeException('API key is not configured');
    }
    $url = 'https://metin2.gg/api/v1/vote/' . $path;
    if ($query) {
        $url .= '?' . http_build_query($query, '', '&', PHP_QUERY_RFC3986);
    }
    $headers = ['X-API-Key: ' . $key, 'Accept: application/json'];
    $ch = curl_init($url);
    curl_setopt_array($ch, [
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_CONNECTTIMEOUT => 5,
        CURLOPT_TIMEOUT => 10,
        CURLOPT_SSL_VERIFYPEER => true,
        CURLOPT_SSL_VERIFYHOST => 2,
        CURLOPT_FOLLOWLOCATION => false,
    ]);
    if ($body !== null) {
        $headers[] = 'Content-Type: application/json';
        curl_setopt($ch, CURLOPT_POST, true);
        curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($body, JSON_THROW_ON_ERROR));
    }
    curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
    $raw = curl_exec($ch);
    $status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);
    if ($raw === false || $status !== 200) {
        throw new RuntimeException('Vote API unavailable');
    }
    $result = json_decode($raw, true, 512, JSON_THROW_ON_ERROR);
    if (!is_array($result)) {
        throw new RuntimeException('Invalid API response');
    }
    return $result;
}

function processVoteRewards($session, $storage): array {
    // REQUIRED: authenticate a trusted session. Never trust request player input.
    $playerId = $storage->requireAuthenticatedPlayer($session);
    if (!is_string($playerId) || $playerId === '') {
        throw new RuntimeException('Authenticated local player required');
    }
    $serverId = getenv('METIN2GG_SERVER_ID');
    if (!$serverId) {
        throw new RuntimeException('Server ID is not configured');
    }
    $pending = voteApi('unclaimed', null, ['limit' => 50, 'player_id' => $playerId]);
    if (!isset($pending['votes']) || !is_array($pending['votes'])) {
        throw new RuntimeException('Invalid pending votes');
    }
    $acknowledged = [];
    foreach ($pending['votes'] as $vote) {
        if (!is_array($vote) || ($vote['server_id'] ?? $serverId) !== $serverId) {
            throw new RuntimeException('Wrong server or invalid vote');
        }
        if (($vote['player_id'] ?? null) !== $playerId) {
            continue;
        }
        $voteId = $vote['vote_id'] ?? '';
        if (!is_string($voteId) || !preg_match('/^[a-f0-9]{8}(?:-[a-f0-9]{4}){3}-[a-f0-9]{12}$/Di', $voteId)) {
            throw new RuntimeException('Invalid vote ID');
        }
        // REQUIRED: UNIQUE(server_id, vote_id), bound to the same player.
        // Receipt + actual reward must commit in ONE local DB transaction.
        $receipt = $storage->awardOnce($serverId, $voteId, $playerId);
        if (!in_array($receipt, ['committed', 'already_committed'], true)) {
            throw new RuntimeException('No committed local receipt');
        }
        // Failed ACKs need a retry/reconciliation queue; the durable receipt
        // prevents another award. No cross-network exactly-once guarantee.
        $result = voteApi('claim', ['vote_ids' => [$voteId]]);
        if (($result['requested'] ?? null) !== 1 ||
            !in_array($result['claimed'] ?? null, [0, 1], true)) {
            throw new RuntimeException('Invalid acknowledgement');
        }
        $acknowledged[] = $voteId;
    }
    return $acknowledged;
}
// Invoke from an authenticated backend handler with your real $storage adapter.
// Do not publish this as an anonymous player-name endpoint or report success
// before a real reward has committed. No production test votes are required.