Vote integration

Metin2-Help records and validates the vote. Your server website identifies the player, grants the reward in its own system and confirms processing. We do not receive game credentials and we do not change coins or items.

Guide for Apache, Nginx, Laravel, WordPress and Cloudflare

Submission, approved publication, voting, the standard widget and the basic API are free. There is no subscription.

Register the server — A signed-in account completes the form and submits it for review or keeps it as a draft.
Verify the domain — Publish the token at /.well-known/metin2-help-verify.txt or in a DNS TXT record. A moderator can confirm it manually.
Get approval — Only an approved server with verified ownership can generate an API key.
Generate the key — The key is shown once. Store it on the server, not in the players’ browser.
Install the script — The PHP example creates an intent and, separately, reads unclaimed votes.
Create the intent — Your website sends the player identifier and receives a URL with an opaque token. The token expires in 30 minutes.
Send the player — The player signs in on Metin2-Help and votes. Opening the URL is not a vote.
Check the votes — You query unclaimed votes with the server key.
Grant the reward — You grant it in your own database or system. Metin2-Help does not grant it.
Confirm — You send the processed vote IDs. Repeating the same confirmation does not create a second receipt.
Retry after an error — If the confirmation does not arrive, the vote stays unclaimed and you can retry. Delivery to the game is not exactly-once.
Rotate the key — Rotation revokes the old key immediately. Update the script before the next call.

API

POST /api/v1/servers/{public_id}/vote-intents
GET /api/v1/vote-intents/{intent_id}
GET /api/v1/servers/{public_id}/votes/unclaimed
POST /api/v1/servers/{public_id}/votes/claim
GET /api/v1/servers/{public_id}/stats
GET /api/v1/servers/{public_id}/integration

What do I install on my website?

The server public ID, shown on the edit page.
The API key, only when it is generated, stored in your backend.
The plain vote link, which can live in an HTML button and does not identify a player.
The reward-vote flow, which needs your backend.
The PHP example, which you adapt for the local reward.
The API endpoints below.
The unclaimed-vote query and the claim, after the local reward has been recorded.

Plain vote link

It can be placed in an HTML button. It does not contain a player id and it does not grant a reward by itself.

Reward vote

Your website identifies the signed-in player.
It creates an intent through the API and receives vote_url.
It redirects the player to vote_url. Opening it is not a vote.
After the vote, you query the unclaimed votes.
You grant the reward in your own system and record it locally by Vote ID.
You confirm processing. Repeating the same confirmation does not create a second record.

already_claimed only means Metin2-Help recorded the confirmation. It does not prove the local reward was granted. Your unique Vote ID journal is the proof. If the reward and the journal share a database, keep them in one transaction. If that is not possible, resume from the journal; this is not an exactly-once delivery into the game.

Vote4Coins-style systems

The Vote4Coins link on the server integration page has the form https://metin2-help.com/api/vote/{public_id}/{token}/ID. The token is not the API key. Replacing ID opens the page for that account, but it does not create a vote intent and does not confirm a reward. If ID stays unchanged, the vote is not attached to a player. A confirmed reward needs the advanced connection.

Some websites accept only a callback shaped like https://your-website/api/vote4coins/callback/INDEX?username=PLAYER&key=SECRET. That shape is an example. It is not a Metin2-Help endpoint and it is not a real key.

Metin2-Help does not automatically call an arbitrary owner callback. The current API uses a vote intent, a validated vote, polling and a claim confirmation.

A system that accepts only a callback URL needs an adapter on the owner backend or explicit protocol support. Metin2-Help does not change your website and does not access the game database.

Custom PHP: the example script can run on demand or from cron. Laravel: the same HTTP client in a scheduled command. Cron: poll and confirm after the local journal has recorded the reward.

Without changing the game core you can keep the journal and the reward in a database you control. Delivery into the game account remains your code.

Different terms

Vote URL. The page a player opens in order to vote. A simple vote uses the public page. A reward vote uses the vote_url returned to your backend, with an opaque token.

API verification URL. An endpoint your website asks whether a vote exists. On Metin2-Help this is the API with the key in a header, not a URL that contains the key.

Callback. An address on your domain that some external system would call after a vote. Metin2-Help does not automatically call a callback chosen in other software.

Postback. The same kind of reverse call, often a GET or POST to your website. A Vote4Coins table may show its own postback, not the vote link you entered.

Player ID. The account identifier from the server website. In the Vote4Coins link it replaces the ID segment only when that website performs the replacement. In the advanced integration the backend sends it as player_ref. Metin2-Help does not check that it exists in the game.

Username. It can be the same value as player_ref if that is the identifier you use. Metin2-Help does not check that it exists in the game.

API key. The secret your backend uses to authenticate to Metin2-Help. It is shown once and does not go into HTML.

Callback secret. A secret belonging to the system on your website. It is not the Metin2-Help API key and it should not be sent to us.

Vote Intent. The temporary record that ties a player to a vote that has not happened yet.

Claim. Your confirmation that you processed the Vote ID. By itself it does not prove the reward reached the game.

What can be established about Vote4Coins

The name Vote4Coins covers several implementations with different protocols. There is no single public contract that Metin2-Help can declare compatible.

Some toplists POST JSON to a callback configured by the owner, with a userid, a timestamp and a hash. Others expect the owner website to query an API and receive 0 or 1. Others generate, on the owner domain, one callback endpoint for each registration.

A table showing addresses shaped like https://your-website/api/vote4coins/callback/0?username={username}&key=SECRET is, by that shape, showing endpoints of your website. They are not the vote links that were entered and they are not Metin2-Help endpoints. Different keys for different rows are consistent with locally generated secrets, one per row.

This observation was not checked in a private website panel, and no request was sent to such addresses. Do not treat it as a description of every installation.

Metin2-Help does not call these callbacks. Its own webhook is separate, optional, off by default, HTTPS only, and only to the address saved in the server editor, with an HMAC signature. It does not replace a Vote4Coins postback.

If your installation can call an HTTPS API with an X-API-Key header, adapt the backend to the contract above. If it only accepts a postback received at its own callback, you need an adapter on your website: the adapter checks the vote with Metin2-Help and only then can notify the local system. Metin2-Help does not make that call.

To know what your installation can do, check its documentation: whether it accepts an HTTP client with a custom header, only a vote URL, or only an inbound postback. Without that detail, the integration cannot be called working.

What do I copy, and where?

A. I only want ranking votes. Copy the public simple link or a widget. Do not copy the API key.

B. I have a PHP website and can change the backend. Put the key and Public ID in the server configuration, then use the PHP example: intent, vote_url, unclaimed votes, local reward, claim.

C. I have Vote4Coins and can call a custom API. Your backend has to be adapted to the Metin2-Help contract. Do not paste the key into a callback field.

D. I have Vote4Coins that only accepts a postback. Metin2-Help does not call that postback. Without an adapter on your website, automatic rewards are not available.

E. I cannot change the website code. You can paste the Vote4Coins link into the existing field. If the website does not replace ID, the vote is not tied to a player. A confirmed reward stays with the advanced integration.

The Vote4Coins link and the identifier

The link ends with ID. A website that replaces ID opens the page for that account, but it does not create a vote intent. A website that leaves ID unchanged does not attach a player. The token in the link is not the API key. A confirmed reward stays with the advanced connection: an intent created by the website, a confirmed vote, and claim.

Simple vote: the player opens the page and votes, with no player ID attached.

Reward vote: your website creates the intent, and the reward is granted only on your side after confirmation.

POST /vote-intents

{
  "player_ref": "Hero.1",
  "idempotency_key": "player-hero-1-try"
}

{
  "intent_id": "0123456789abcdef01234567",
  "vote_url": "https://metin2-help.com/servere/{slug}/vot/{token}",
  "expires_at": "2026-11-14 02:00:00",
  "status": "pending"
}

POST /votes/claim

{ "vote_ids": [120] }

{ "data": [{ "vote_id": 120, "result": "claimed" }] }

401 means the key is missing or wrong. 403 means another server, an unapproved server or unverified ownership. 404 is a missing intent. 422 is an invalid identifier. 429 is the rate limit.

The webhook is optional and stays off until you enable it. The signature is HMAC-SHA256 over the timestamp, nonce and body. Polling remains the recovery method. We do not send to internal addresses.

Paid promotion is not active and does not change the order of votes.

Download the PHP example

<?php

/**
 * Exemplu de adaptat pe website-ul serverului privat.
 * Metin2-Help confirmă votul. Recompensa se acordă doar în sistemul tău.
 * Nu pune cheia în JavaScript sau în pagini publice.
 * Acest client nu apelează un callback Vote4Coins. Recompensa rămâne în sistemul tău.
 *
 * Variabile de mediu:
 * M2H_API_KEY, M2H_SERVER_ID, M2H_REWARD_DSN, M2H_REWARD_USER, M2H_REWARD_PASSWORD
 */

declare(strict_types=1);

const M2H_API = 'https://metin2-help.com';

function m2h_request(string $method, string $path, ?array $body = null): array
{
    $key = getenv('M2H_API_KEY');
    $server = getenv('M2H_SERVER_ID');
    if (!is_string($key) || $key === '' || !is_string($server) || $server === '') {
        throw new RuntimeException('Configurația API lipsește.');
    }
    $url = M2H_API . str_replace('{server}', rawurlencode($server), $path);
    $ch = curl_init($url);
    if ($ch === false) {
        throw new RuntimeException('Clientul HTTP nu a pornit.');
    }
    $headers = ['Accept: application/json', 'X-API-Key: ' . $key];
    $options = [
        CURLOPT_CUSTOMREQUEST => $method,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_TIMEOUT => 15,
        CURLOPT_PROTOCOLS => CURLPROTO_HTTPS,
    ];
    if ($body !== null) {
        $headers[] = 'Content-Type: application/json';
        $options[CURLOPT_POSTFIELDS] = json_encode($body, JSON_UNESCAPED_SLASHES);
    }
    $options[CURLOPT_HTTPHEADER] = $headers;
    curl_setopt_array($ch, $options);
    $raw = curl_exec($ch);
    $code = (int) curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
    curl_close($ch);
    $decoded = is_string($raw) ? json_decode($raw, true) : null;
    if (!is_array($decoded)) {
        throw new RuntimeException('Răspuns API invalid, HTTP ' . $code);
    }
    $decoded['_http'] = $code;

    return $decoded;
}

function m2h_start(string $playerRef): array
{
    if (!preg_match('/^[A-Za-z0-9_.:@-]{1,64}$/', $playerRef)) {
        throw new InvalidArgumentException('Identificatorul jucătorului nu este acceptat.');
    }

    return m2h_request('POST', '/api/v1/servers/{server}/vote-intents', [
        'player_ref' => $playerRef,
        'idempotency_key' => bin2hex(random_bytes(16)),
    ]);
}

function m2h_reward_pdo(): PDO
{
    return new PDO(
        (string) getenv('M2H_REWARD_DSN'),
        (string) getenv('M2H_REWARD_USER'),
        (string) getenv('M2H_REWARD_PASSWORD'),
        [PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION]
    );
}

/**
 * Înlocuiește corpul acestei funcții cu recompensa serverului tău.
 * Dacă recompensa și jurnalul sunt în aceeași bază, ține-le în aceeași tranzacție.
 * Dacă sunt sisteme diferite, păstrează jurnalul local înainte de confirmare
 * și reia din jurnal la următoarea rulare. Metin2-Help nu promite livrare unică
 * către joc; confirmarea repetată a aceluiași Vote ID nu mai creează o confirmare nouă.
 */
function m2h_grant_local(PDO $pdo, int $voteId, string $playerRef): void
{
    $pdo->beginTransaction();
    try {
        $seen = $pdo->prepare('INSERT INTO owner_vote_rewards (vote_id, player_ref, granted_at) VALUES (?, ?, ?)');
        $seen->execute([$voteId, $playerRef, gmdate('Y-m-d H:i:s')]);
        // Exemplu de înlocuit: $pdo->prepare('UPDATE account SET coins = coins + ? WHERE id = ?')->execute([10, $playerRef]);
        $pdo->commit();
    } catch (PDOException $exception) {
        if ($pdo->inTransaction()) {
            $pdo->rollBack();
        }
        if ((string) $exception->getCode() !== '23000') {
            throw $exception;
        }
    }
}

function m2h_poll(): void
{
    $pdo = m2h_reward_pdo();
    $pdo->exec('CREATE TABLE IF NOT EXISTS owner_vote_rewards (vote_id BIGINT NOT NULL PRIMARY KEY, player_ref VARCHAR(64) NOT NULL, granted_at DATETIME NOT NULL)');
    $cursor = 0;
    do {
        $page = m2h_request('GET', '/api/v1/servers/{server}/votes/unclaimed?limit=50&cursor=' . $cursor);
        $rows = $page['data'] ?? [];
        $ids = [];
        foreach ($rows as $row) {
            if (!is_array($row) || empty($row['vote_id']) || empty($row['player_ref'])) {
                continue;
            }
            m2h_grant_local($pdo, (int) $row['vote_id'], (string) $row['player_ref']);
            $ids[] = (int) $row['vote_id'];
        }
        if ($ids !== []) {
            $claim = m2h_request('POST', '/api/v1/servers/{server}/votes/claim', ['vote_ids' => $ids]);
            foreach ($claim['data'] ?? [] as $result) {
                // already_claimed nu dovedește recompensa locală. Dovada este rândul din owner_vote_rewards.
                if (($result['result'] ?? '') === 'rejected') {
                    error_log('Metin2-Help a respins vote_id ' . (int) ($result['vote_id'] ?? 0));
                }
            }
        }
        $cursor = (int) ($page['next_cursor'] ?? 0);
    } while ($cursor > 0);
}

if (PHP_SAPI === 'cli' && isset($argv[1]) && $argv[1] === 'poll') {
    m2h_poll();
}

API