Server-specific bearer tokens

Generate a token at Owner dashboard → Integration. It is shown once and stored by RuneTopic only as a SHA-256 hash. Regenerating revokes the previous token immediately.

Authorization: Bearer rt_live_YOUR_SERVER_TOKEN
Accept: application/json

Keep the token in your server's environment or private configuration. Do not ship it in a public client, launcher or repository.

Check, then claim atomically

GET https://www.runetopic.com/api/v1/votes/check.php?player=Alex

{
  "success": true,
  "available": true,
  "vote": {"id": 125534, "player": "Alex", "site": "runetopic", "voted_at": "2026-08-11 20:45:00"}
}

POST https://www.runetopic.com/api/v1/votes/claim.php
Content-Type: application/json

{"player":"Alex","vote_id":125534}

GET or POST—the fields are identical

Choose the method in your owner dashboard. RuneTopic sends only the configured method; it does not switch from GET to POST after an error because that can create duplicate rewards.

https://your-server.com/vote/callback?
username=Alex&playerName=Alex&serverID=143&site=runetopic&voteID=125534

Content-Type: application/x-www-form-urlencoded

username=Alex&server_id=143&site_id=runetopic&vote_id=125534&test=0

Compatibility

If your saved GET URL contains postback=, RuneTopic fills that value with the player name and also adds the documented fields. Placeholders {username}, {server_id}, {vote_id} and {site_id} are supported.

Success rules and retries

A 2xx response is accepted unless the body explicitly returns 0, -1, false, failed, error, or JSON with "success": false. Network and 5xx failures are retried once using the same method. 4xx responses are not retried. Timeout is 8 seconds by default.

Callback URLs must use HTTPS on port 443. RuneTopic resolves the host before delivery and rejects private, loopback, link-local and reserved destinations.

Coming soon after payment testing

Live purchase claims remain disabled. The JAR reserves store-delivery classes for future compatibility, but server owners should not build a production store fulfilment flow yet.

Java 8+ setup

1. Download runetopic-integration.jar and place it in your server's library directory.
2. Generate a token in the integration dashboard.
3. Set the server ID and token in private server configuration.
4. Call the SDK's vote claim method from the private server process—not the game client.

RuneTopicClient client = RuneTopicClient.builder()
    .serverId(143)
    .apiToken(System.getenv("RUNETOPIC_API_TOKEN"))
    .build();

VoteClaimResult result = client.votes().claimSync("Alex");
for (Reward reward : result.rewards()) {
    reward.grantWith(gameServer::executeCommand);
}

The JAR leases the reward first, executes your configured commands, and acknowledges only after command execution succeeds. An unacknowledged lease becomes available for retry.

Predictable HTTP errors

Default limit is 60 API requests per minute per server/IP. Responses include a request_id for staff support. Do not log bearer tokens, put them in URLs, accept a player name without validating it, or grant before a successful atomic claim.