Documentation menu

API Reference

Economy

Currencies + statistics for any owner (player, farm, ...)

GET /api/plugin/economy/leaderboard

Top owners by a statistic

Ranks all owners of one ownerType by a statistic in one period (highest first).

Parameters

  • gameMode string query
  • limit integer query
  • name string query

    Statistic name to rank by.

  • ownerType string query

    Owner type to rank (e.g. "farm").

  • period string query

    DAILY/WEEKLY/MONTHLY/LIFETIME.

Responses

  • 200 The ranked leaderboard.
200 response 
{
  "ownerType": "string",
  "statisticName": "string",
  "gameMode": "string",
  "period": "string",
  "entries": [
    {
      "rank": 0,
      "ownerKey": "string",
      "value": 0
    }
  ]
}

Request

~
curl -X GET https://api.hivescale.dev/api/plugin/economy/leaderboard?gameMode=value&limit=0&name=value&ownerType=value&period=value \
  -H "X-Hive-Api-Key: $HIVE_API_KEY"
HttpClient client = HttpClient.newHttpClient();

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.hivescale.dev/api/plugin/economy/leaderboard?gameMode=value&limit=0&name=value&ownerType=value&period=value"))
    .header("X-Hive-Api-Key", apiKey)
    .method("GET", HttpRequest.BodyPublishers.noBody())
    .build();

HttpResponse<String> response =
    client.send(request, HttpResponse.BodyHandlers.ofString());
GET /api/plugin/economy/{ownerType}/{ownerKey}/currencies

List an owner's currency balances

Parameters

  • ownerKey string path required
  • ownerType string path required

Responses

  • 200 All currency balances held by the owner.
200 response 
[
  {
    "currencyName": "string",
    "balance": 0
  }
]

Request

~
curl -X GET https://api.hivescale.dev/api/plugin/economy/{ownerType}/{ownerKey}/currencies \
  -H "X-Hive-Api-Key: $HIVE_API_KEY"
HttpClient client = HttpClient.newHttpClient();

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.hivescale.dev/api/plugin/economy/{ownerType}/{ownerKey}/currencies"))
    .header("X-Hive-Api-Key", apiKey)
    .method("GET", HttpRequest.BodyPublishers.noBody())
    .build();

HttpResponse<String> response =
    client.send(request, HttpResponse.BodyHandlers.ofString());
POST /api/plugin/economy/{ownerType}/{ownerKey}/currencies/modify

Add to / subtract from a balance

Atomically adds the (possibly negative) amount to the owner's balance, clamped to the currency's min/max, audited in currency_transactions. Returns the new balance.

Parameters

  • ownerKey string path required
  • ownerType string path required

Request body

application/json 
{
  "currency": "string",
  "amount": 0,
  "reason": "string"
}

Responses

  • 200 The updated balance.
  • 400 Bad Request
200 response 
{
  "currencyName": "string",
  "balance": 0
}

Request

~
curl -X POST https://api.hivescale.dev/api/plugin/economy/{ownerType}/{ownerKey}/currencies/modify \
  -H "X-Hive-Api-Key: $HIVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"currency":"string","amount":0,"reason":"string"}'
HttpClient client = HttpClient.newHttpClient();

String body = "{\"currency\":\"string\",\"amount\":0,\"reason\":\"string\"}";

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.hivescale.dev/api/plugin/economy/{ownerType}/{ownerKey}/currencies/modify"))
    .header("X-Hive-Api-Key", apiKey)
    .header("Content-Type", "application/json")
    .method("POST", HttpRequest.BodyPublishers.ofString(body))
    .build();

HttpResponse<String> response =
    client.send(request, HttpResponse.BodyHandlers.ofString());
GET /api/plugin/economy/{ownerType}/{ownerKey}/statistics

Read an owner's statistics

Parameters

  • ownerKey string path required
  • ownerType string path required
  • gameMode string query

Responses

  • 200 The owner's statistics for the requested game mode.
200 response 
{
  "ownerType": "string",
  "ownerKey": "string",
  "gameMode": "string",
  "statistics": [
    {
      "statisticName": "string",
      "gameMode": "string",
      "periodType": "string",
      "periodStart": "string",
      "value": 0,
      "updatedAt": 0
    }
  ]
}

Request

~
curl -X GET https://api.hivescale.dev/api/plugin/economy/{ownerType}/{ownerKey}/statistics?gameMode=value \
  -H "X-Hive-Api-Key: $HIVE_API_KEY"
HttpClient client = HttpClient.newHttpClient();

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.hivescale.dev/api/plugin/economy/{ownerType}/{ownerKey}/statistics?gameMode=value"))
    .header("X-Hive-Api-Key", apiKey)
    .method("GET", HttpRequest.BodyPublishers.noBody())
    .build();

HttpResponse<String> response =
    client.send(request, HttpResponse.BodyHandlers.ofString());
POST /api/plugin/economy/{ownerType}/{ownerKey}/statistics/increment

Increment an owner's statistic

Adds to a named statistic and returns its new value in every period (DAILY/WEEKLY/MONTHLY/LIFETIME).

Parameters

  • ownerKey string path required
  • ownerType string path required

Request body

application/json 
{
  "name": "string",
  "gameMode": "string",
  "amount": 0
}

Responses

  • 200 The updated per-period values.
  • 400 Bad Request
200 response 
{
  "statisticName": "string",
  "gameMode": "string",
  "newValues": {}
}

Request

~
curl -X POST https://api.hivescale.dev/api/plugin/economy/{ownerType}/{ownerKey}/statistics/increment \
  -H "X-Hive-Api-Key: $HIVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"string","gameMode":"string","amount":0}'
HttpClient client = HttpClient.newHttpClient();

String body = "{\"name\":\"string\",\"gameMode\":\"string\",\"amount\":0}";

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.hivescale.dev/api/plugin/economy/{ownerType}/{ownerKey}/statistics/increment"))
    .header("X-Hive-Api-Key", apiKey)
    .header("Content-Type", "application/json")
    .method("POST", HttpRequest.BodyPublishers.ofString(body))
    .build();

HttpResponse<String> response =
    client.send(request, HttpResponse.BodyHandlers.ofString());