API/Shop

Back to API

This API page describes the endpoints under api.retromc.org/api/v1/shop.

GET api.retromc.org/api/v1/shop/getShops

Description

Get all chest shops spanning across all worlds. Do the filtering on your side.

HTTP Method

GET

Request Parameters

None needed

Response Format

• (ENTIRE OUTPUT) Array of shops, each shop follows this format:
  • world (string): World the shop is contained in.
  • x (int): X position of the shop
  • y (int): Y position of the shop
  • z (int): Z position of the shop
  • owner (string): Who owns this shop (can be Admin Shop)
  • ownerUUID (string): UUID of the shop. (can be f6b48fd1-2f3a-31db-8237-36411a7bcb37 for admin shop, not a real player ID!)
  • balance (decimal): "Balance" of the player who owns it? It can be different from shop to shop. Might be based on shop sell/buy price?
  • itemName (string): ID of the item in the shop.
  • stockAmount (int): Amount of items in stock. (can be 2147483647 for admin shop)
  • stockCapacity (int): Amount of stock that can still be sold. (can be 2147483647 for admin shop)
  • tradeAmount (int): Amount of items per buy/sell.
  • buyPrice (decimal): Price of buying, can be -1.0 if you cant buy from it.
  • sellPrice (decimal): Price of selling, can be -1.0 if you cant sell from it.
  • isAdminShop (boolean): If the shop if from admin shop.
  • lastScan (int): UNIX timestamp of the last time it was scanned.

Example Response

[
    {
        "world": "retromc",
        "x": -272,
        "y": 70,
        "z": -2512,
        "owner": "aq2a",
        "ownerUUID": "985b9366-cdc1-45c2-aa7b-cd6a0837e47f",
        "balance": 57.6481765487697,
        "itemName": "SUGAR_CANE",
        "stockAmount": 0,
        "stockCapacity": 3456,
        "tradeAmount": 64,
        "buyPrice": 3.2,
        "sellPrice": 1.92,
        "isAdminShop": false,
        "lastScan": 1788385279
    }
]

POST api.retromc.org/api/v1/shop/onlineOrder

Description

Try to complete an online order; that is buying/selling from a shop online. Note that you NEED a auth code coming from the server's /jcode shop command to actually complete a operation, to prevent people from just faking buy/sell requests from someone. Addtionally, the person needs to be online.

HTTP Method

POST

Request Parameters

• username (required, string): Username of the person trying to buy
• code (required, string): 6-digit hex code obtained from /jcode shop command.
• trades (required, int): Amount of trades to perform (shop.tradeAmount * trades = totalItemAmount)
• mode: (required, string): Can be either BUY or SELL.
• shop: (required, object): Same format as each shop from getShops, but only fields world, x, y, z, owner, itemName, tradeAmount, buyPrice, sellPrice, and isAdminShop are needed.

Response Format

On Error

• error_message (string): Error message.
  • "Player must be online to place an order." - If the player is offline when requesting.
  • "Invalid or expired code. Please generate a new code in-game using /jcode shop." - If the code is either not in the right format (not 6 hex digits) or has expired.
  • "Transaction failed. Please review your in-game messages for details." - Other error. Only the client can see the real error message. E.g. if they dont have the items, the shop is empty, etcera.
• error (bool): true

On Success

• message (string): Persumably always, "Transaction successful."; might differ.
• success (bool): true

Example Request

{
  "username": "Skull6",
  "code": "SOMECODE",
  "trades": 1,
  "mode": "SELL",
  "shop": {
    "world": "retromc",
    "x": -61,
    "y": 65,
    "z": -62,
    "owner": "Grassboii",
    "itemName": "APPLE",
    "tradeAmount": 1,
    "buyPrice": -1,
    "sellPrice": 40,
    "isAdminShop": false
  }
}

Example Response

{
  "success": true,
  "message": "Transaction successful."
}