HytaleTop100 Voting API: Complete Integration Guide for Server Owners

Introduction to the HytaleTop100 Voting API

We're excited to announce the launch of the HytaleTop100 Voting API, a powerful system that allows server owners to integrate vote-based rewards directly into their Hytale servers. This API enables you to check player vote balances and redeem votes for in-game rewards, creating a seamless connection between your website listing and your player economy.

How the Voting System Works

HytaleTop100 operates as a vote banking system. When players vote for your server on our website, their votes are credited to their account as redeemable points. You, as the server owner, decide what these votes are worth in your economy.

The Player Experience

Players sign in to HytaleTop100 with Google OAuth and set their Hytale account ID. When they vote for your server, votes are added to their balance. They can then spend these votes on your server for ranks, items, perks, or whatever rewards you offer.

Two Types of Vote Counters

Total Votes: The lifetime total number of times a player has voted for your server. This number never decreases and is used for leaderboards and server rankings.

Available Votes: The current spendable balance. This decreases when you redeem votes through the API for player rewards.

Getting Your API Key

To use the API, you'll need your server's unique API key. You can find this in your server's edit page after logging into HytaleTop100:

1. Sign in to your HytaleTop100 account
2. Navigate to "My Servers"
3. Click "Edit" on your server
4. Scroll to the API section to find your API key

Important: Keep your API key secret! Anyone with your API key can redeem votes from your server's players. Never share it publicly or commit it to public repositories.

API Endpoints

The API is simple and RESTful, with three main endpoints:

1. Check Vote Balance

Get a player's current vote balance and history.

GET /api/v1/servers/{server_id}/votes/{account_id}

Headers:

Authorization: Bearer YOUR_API_KEY
  Content-Type: application/json

Response:

{
    "account_id": "cool_gamer_123",
    "username": "CoolGamer",
    "total_votes": 47,
    "available_votes": 20,
    "last_voted_at": "2025-12-15T10:30:00Z"
  }

2. Redeem Votes

Deduct votes from a player's balance when they purchase rewards.

POST /api/v1/servers/{server_id}/votes/{account_id}/redeem

Headers:

Authorization: Bearer YOUR_API_KEY
  Content-Type: application/json

Request Body:

{
    "amount": 10,
    "description": "Diamond Sword"
  }

Response:

{
    "success": true,
    "account_id": "cool_gamer_123",
    "redeemed": 10,
    "remaining_votes": 10,
    "transaction_id": "txn_abc123"
  }

3. View Transaction History

Retrieve a player's complete vote history including redemptions.

GET /api/v1/servers/{server_id}/votes/{account_id}/history

Headers:

Authorization: Bearer YOUR_API_KEY
  Content-Type: application/json

Response:

{
    "account_id": "cool_gamer_123",
    "transactions": [
      {
        "type": "earned",
        "amount": 1,
        "timestamp": "2025-12-15T10:30:00Z"
      },
      {
        "type": "redeemed",
        "amount": -10,
        "description": "Diamond Sword",
        "timestamp": "2025-12-14T15:45:00Z"
      }
    ]
  }

Integration Examples

Node.js Example

const axios = require('axios');

  async function getVoteBalance(serverId, accountId, apiKey) {
      const url = `https://hytaletop100.com/api/v1/servers/${serverId}/votes/${accountId}`;

      const response = await axios.get(url, {
          headers: {
              'Authorization': `Bearer ${apiKey}`,
              'Content-Type': 'application/json'
          }
      });

      return response.data;
  }

  async function redeemVotes(serverId, accountId, amount, description, apiKey) {
      const url = `https://hytaletop100.com/api/v1/servers/${serverId}/votes/${accountId}/redeem`;

      const response = await axios.post(url, {
          amount: amount,
          description: description
      }, {
          headers: {
              'Authorization': `Bearer ${apiKey}`,
              'Content-Type': 'application/json'
          }
      });

      return response.data;
  }

Java Example

import java.net.http.HttpClient;
  import java.net.http.HttpRequest;
  import java.net.http.HttpResponse;
  import java.net.URI;
  import com.google.gson.Gson;
  import com.google.gson.JsonObject;

  public class VotingAPI {
      private static final HttpClient client = HttpClient.newHttpClient();
      private static final Gson gson = new Gson();

      public static JsonObject getVoteBalance(String serverId, String accountId, String apiKey) throws Exception {
          String url = String.format("https://hytaletop100.com/api/v1/servers/%s/votes/%s", serverId, accountId);

          HttpRequest request = HttpRequest.newBuilder()
              .uri(URI.create(url))
              .header("Authorization", "Bearer " + apiKey)
              .header("Content-Type", "application/json")
              .GET()
              .build();

          HttpResponse response = client.send(request, HttpResponse.BodyHandlers.ofString());
          return gson.fromJson(response.body(), JsonObject.class);
      }

      public static JsonObject redeemVotes(String serverId, String accountId, int amount, String description, String apiKey) throws Exception {
          String url = String.format("https://hytaletop100.com/api/v1/servers/%s/votes/%s/redeem", serverId, accountId);

          JsonObject body = new JsonObject();
          body.addProperty("amount", amount);
          body.addProperty("description", description);

          HttpRequest request = HttpRequest.newBuilder()
              .uri(URI.create(url))
              .header("Authorization", "Bearer " + apiKey)
              .header("Content-Type", "application/json")
              .POST(HttpRequest.BodyPublishers.ofString(gson.toJson(body)))
              .build();

          HttpResponse response = client.send(request, HttpResponse.BodyHandlers.ofString());
          return gson.fromJson(response.body(), JsonObject.class);
      }
  }

Use Cases and Examples

In-Game Vote Shop

Create commands like /voteshop that check a player's balance and allow them to purchase rewards:

• VIP Rank: 50 votes
• Diamond Armor: 25 votes
• Spawn Egg: 10 votes
• Bonus Crate Key: 5 votes

Website Reward Store

Build a web store where players can log in and spend their votes on server perks, bypassing in-game purchases entirely.

Automated Milestone Rewards

Set up automated systems that grant rewards at vote milestones:

• Every 10th vote: Bonus crate key
• 100 total votes: Special title
• Monthly top voter: Exclusive cosmetic

Vote Parties

Track when your server reaches a certain number of votes in a day and trigger server-wide rewards for everyone online.

Best Practices

Security

• Never expose your API key - Store it securely in environment variables or configuration files that are not publicly accessible
• Validate player authentication - Only allow authenticated in-game players to trigger vote redemptions
• Log all transactions - Keep records of redemptions for customer support and fraud detection

User Experience

• Clear pricing - Make sure players understand what votes are worth in your economy
• Confirmation prompts - Ask players to confirm before redeeming votes for expensive items
• Balance display - Show players their current vote balance in-game or on your website
• Transaction receipts - Provide confirmation messages when votes are redeemed

Economy Design

• You control the value - Set prices based on what works for your server's economy
• Balance rewards - Don't make votes too powerful or too weak compared to other progression systems
• Offer variety - Provide rewards at different price points to appeal to all players

Error Handling

The API returns standard HTTP status codes:

• 200 OK - Request successful
• 400 Bad Request - Invalid parameters (e.g., insufficient votes)
• 401 Unauthorized - Invalid or missing API key
• 404 Not Found - Account ID not found
• 500 Internal Server Error - Server error (contact support)

Always handle errors gracefully in your integration:

try {
      const balance = await getVoteBalance(serverId, accountId, apiKey);
      console.log(`Player has ${balance.available_votes} votes`);
  } catch (error) {
      if (error.response.status === 404) {
          console.log("Player has not voted yet");
      } else {
          console.log("Error checking balance:", error.message);
      }
  }

Rate Limits

The API is designed for normal server operation. Standard rate limits apply to prevent abuse while allowing legitimate usage patterns.

Support and Resources

Need help integrating the API? We're here to help:

• Full API Documentation - Visit /docs/api for complete endpoint reference
• Example Code - Find ready-to-use integration examples in popular languages
• Community Discord - Ask questions and share integration tips with other server owners

Get Started Today

The HytaleTop100 Voting API is live and ready for integration. Log in to your server dashboard, grab your API key, and start building your vote-based reward system today.

Your players are voting. Now you can reward them seamlessly.

Happy coding!