HTTP API Reference

Base URL: https://gameplaygen.com/api/economy

All endpoints (except game creation) require a Bearer token: Authorization: Bearer <api_key>

Endpoints Overview

Core

POST/games— Create a game (no auth)

POST/currencies— Define a currency

POST/items— Define an item

POST/players— Get or create a player

POST/players/batch— Create up to 100 players at once

POST/grant— Grant currency to player

POST/spend— Spend currency from player

POST/purchase— Buy an item (atomic)

POST/transfer— Transfer currency between players

GET/stats— Economy statistics

GET/config— Game economy config

GET/transactions— Paginated transaction log

GET/players/:id/balance— Player balances

GET/players/:id/inventory— Player inventory

Advanced

POST/craft— Craft a recipe

POST/loot/roll— Roll a loot table

POST/marketplace/list— List item for sale

POST/marketplace/buy— Buy a marketplace listing

GET/audit-flags— Anti-cheat audit flags

Response Format

All responses follow a consistent envelope:

json

// Success
{
  "success": true,
  "data": { ... },
  "requestId": "req_a1b2c3d4e5f6"
}

// Error
{
  "success": false,
  "error": "Missing required field: currencyId",
  "requestId": "req_a1b2c3d4e5f6"
}

POST /games

Create a new game. No authentication required. Returns an API key — store it securely.

Field	Type	Required	Description
`name`	`string`	`Yes`	`Unique game name`
`ownerId`	`string`	`No`	`Owner identifier (default: anonymous)`

bash

curl -X POST https://gameplaygen.com/api/economy/games \
  -H "Content-Type: application/json" \
  -d '{ "name": "my-game" }'

json

{
  "success": true,
  "data": {
    "gameId": "j97abc...",
    "apiKey": "gg_live_sk_abc123..."
  }
}

POST /currencies

Define a currency. Idempotent — updates if it already exists.

Field	Type	Required	Description
`currencyId`	`string`	`Yes`	`Unique currency identifier (e.g. gold, gems)`
`name`	`string`	`Yes`	`Display name`
`icon`	`string`	`Yes`	`Emoji or icon URL`
`maxBalance`	`number`	`No`	`Maximum balance cap per player`

bash

curl -X POST https://gameplaygen.com/api/economy/currencies \
  -H "Authorization: Bearer gg_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{ "currencyId": "gold", "name": "Gold", "icon": "💰" }'

POST /items

Define a purchasable item with pricing.

Field	Type	Required	Description
`itemId`	`string`	`Yes`	`Unique item identifier`
`name`	`string`	`Yes`	`Display name`
`rarity`	`string`	`No`	`Rarity tier`
`prices`	`{ currencyId, amount }[]`	`Yes`	`Price list`
`maxOwned`	`number`	`No`	`Max quantity per player`
`metadata`	`object`	`No`	`Custom metadata`

bash

curl -X POST https://gameplaygen.com/api/economy/items \
  -H "Authorization: Bearer gg_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "itemId": "iron-sword",
    "name": "Iron Sword",
    "rarity": "common",
    "prices": [{ "currencyId": "gold", "amount": 50 }]
  }'

POST /players

Get or create a player by external ID. Idempotent.

Field	Type	Required	Description
`externalId`	`string`	`Yes`	`Your user/player ID`
`metadata`	`object`	`No`	`Custom player metadata`

bash

curl -X POST https://gameplaygen.com/api/economy/players \
  -H "Authorization: Bearer gg_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{ "externalId": "player_42" }'

POST /players/batch

Create up to 100 players in a single request. Each player can have initial wallet balances. Ideal for game setup, migrations, or simulations.

Field	Type	Required	Description
`players`	`array`	`Yes`	`Array of player objects (max 100)`
`players[].externalId`	`string`	`Yes`	`Your user/player ID`
`players[].displayName`	`string`	`No`	`Display name (defaults to externalId)`
`players[].wallets`	`array`	`No`	`Initial wallet balances: [{ currencyId, balance }]`

bash

curl -X POST https://gameplaygen.com/api/economy/players/batch \
  -H "Authorization: Bearer gg_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "players": [
      { "externalId": "player_1", "displayName": "Alice", "wallets": [{ "currencyId": "gold", "balance": 100 }] },
      { "externalId": "player_2", "displayName": "Bob", "wallets": [{ "currencyId": "gold", "balance": 50 }] }
    ]
  }'

Returns { success: true, players: [{ externalId, playerId }, ...] }

POST /grant

Grant (mint) currency to a player. This is a faucet — it creates new currency.

Field	Type	Required	Description
`externalId`	`string`	`Yes*`	`Player external ID (preferred)`
`playerId`	`string`	`Yes*`	`Internal player ID (legacy)`
`currencyId`	`string`	`Yes`	`Currency to grant`
`amount`	`number`	`Yes`	`Amount to grant (positive)`
`metadata`	`object`	`No`	`e.g. { reason: 'quest_complete' }`
`idempotencyKey`	`string`	`No`	`Unique key to prevent duplicate grants`

* Provide either externalId or playerId.

bash

curl -X POST https://gameplaygen.com/api/economy/grant \
  -H "Authorization: Bearer gg_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "externalId": "player_42",
    "currencyId": "gold",
    "amount": 100,
    "metadata": { "reason": "quest_complete" }
  }'

POST /spend

Deduct currency from a player. Fails if insufficient balance.

Field	Type	Required	Description
`externalId`	`string`	`Yes*`	`Player external ID`
`currencyId`	`string`	`Yes`	`Currency to spend`
`amount`	`number`	`Yes`	`Amount to deduct`
`metadata`	`object`	`No`	`e.g. { reason: 'repair_cost' }`
`idempotencyKey`	`string`	`No`	`Unique key to prevent duplicates`

bash

curl -X POST https://gameplaygen.com/api/economy/spend \
  -H "Authorization: Bearer gg_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "externalId": "player_42",
    "currencyId": "gold",
    "amount": 30
  }'

POST /purchase

Atomic item purchase — deducts the item's price and adds it to the player's inventory. Rolls back if anything fails.

Field	Type	Required	Description
`externalId`	`string`	`Yes*`	`Player external ID`
`itemId`	`string`	`Yes`	`Item to purchase`
`metadata`	`object`	`No`	`Custom metadata`

bash

curl -X POST https://gameplaygen.com/api/economy/purchase \
  -H "Authorization: Bearer gg_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{ "externalId": "player_42", "itemId": "iron-sword" }'

POST /transfer

Transfer currency between two players. Subject to anti-cheat laundering detection.

Field	Type	Required	Description
`fromExternalId`	`string`	`Yes`	`Sender player external ID`
`toExternalId`	`string`	`Yes`	`Recipient player external ID`
`currencyId`	`string`	`Yes`	`Currency to transfer`
`amount`	`number`	`Yes`	`Amount to transfer`
`metadata`	`object`	`No`	`Custom metadata`

bash

curl -X POST https://gameplaygen.com/api/economy/transfer \
  -H "Authorization: Bearer gg_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "fromExternalId": "player_42",
    "toExternalId": "player_99",
    "currencyId": "gold",
    "amount": 50
  }'

GET /stats

Economy-wide statistics including player count, transaction totals, and currency flows.

bash

curl https://gameplaygen.com/api/economy/stats \
  -H "Authorization: Bearer gg_live_sk_..."

json

{
  "success": true,
  "data": {
    "totalPlayers": 1247,
    "totalTransactions": 89432,
    "currencyStats": [{
      "currencyId": "gold",
      "totalInCirculation": 5430000,
      "totalGranted": 8200000,
      "totalSpent": 2770000
    }]
  }
}

GET /config

Returns the game's economy configuration — all defined currencies and items.

bash

curl https://gameplaygen.com/api/economy/config \
  -H "Authorization: Bearer gg_live_sk_..."

GET /transactions

Paginated transaction log.

Param	Type	Description
`limit`	`number`	`Results per page (default 50)`
`cursor`	`string`	`Pagination cursor from previous response`

bash

curl "https://gameplaygen.com/api/economy/transactions?limit=20" \
  -H "Authorization: Bearer gg_live_sk_..."

GET /players/:id/balance

Get all currency balances for a player.

bash

curl https://gameplaygen.com/api/economy/players/j97abc.../balance \
  -H "Authorization: Bearer gg_live_sk_..."

json

{
  "success": true,
  "data": { "gold": 750, "gems": 12 }
}

GET /players/:id/inventory

Get all items in a player's inventory.

bash

curl https://gameplaygen.com/api/economy/players/j97abc.../inventory \
  -H "Authorization: Bearer gg_live_sk_..."

json

{
  "success": true,
  "data": [
    { "itemId": "iron-sword", "quantity": 1 },
    { "itemId": "health-potion", "quantity": 5 }
  ]
}

Advanced Endpoints

POST /craft

Execute a crafting recipe — consumes ingredients and grants outputs. See Crafting docs for recipe setup.

Field	Type	Required	Description
`gameId`	`string`	`Yes`	`Game ID`
`playerId`	`string`	`Yes`	`Internal player ID`
`recipeId`	`string`	`Yes`	`Recipe identifier`

bash

curl -X POST https://gameplaygen.com/api/economy/craft \
  -H "Authorization: Bearer gg_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "gameId": "j97abc...",
    "playerId": "j97def...",
    "recipeId": "iron_sword_recipe"
  }'

json

{
  "success": true,
  "data": {
    "granted": [
      { "type": "item", "id": "iron-sword", "amount": 1 }
    ]
  }
}

POST /loot/roll

Roll a loot table and grant results to a player. See Loot Tables docs.

Field	Type	Required	Description
`gameId`	`string`	`Yes`	`Game ID`
`playerId`	`string`	`Yes`	`Internal player ID`
`tableId`	`string`	`Yes`	`Loot table identifier`

bash

curl -X POST https://gameplaygen.com/api/economy/loot/roll \
  -H "Authorization: Bearer gg_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "gameId": "j97abc...",
    "playerId": "j97def...",
    "tableId": "boss_dragon_table"
  }'

json

{
  "success": true,
  "data": {
    "results": [
      { "type": "item", "id": "dragon_scale", "amount": 1 },
      { "type": "currency", "id": "gold", "amount": 250 }
    ]
  }
}

POST /marketplace/list

List an item for sale on the player marketplace. The item is escrowed (removed from seller's inventory). See Marketplace docs.

Field	Type	Required	Description
`gameId`	`string`	`Yes`	`Game ID`
`playerId`	`string`	`Yes`	`Seller player ID`
`itemId`	`string`	`Yes`	`Item to list`
`currencyId`	`string`	`Yes`	`Currency for the price`
`price`	`number`	`Yes`	`Listing price`
`quantity`	`number`	`No`	`Quantity (default 1)`
`expiresAt`	`number`	`No`	`Expiration timestamp (ms)`

bash

curl -X POST https://gameplaygen.com/api/economy/marketplace/list \
  -H "Authorization: Bearer gg_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "gameId": "j97abc...",
    "playerId": "j97def...",
    "itemId": "iron-sword",
    "currencyId": "gold",
    "price": 500
  }'

POST /marketplace/buy

Buy a marketplace listing. Deducts currency from buyer, pays seller (minus tax), transfers item.

Field	Type	Required	Description
`gameId`	`string`	`Yes`	`Game ID`
`playerId`	`string`	`Yes`	`Buyer player ID`
`listingId`	`string`	`Yes`	`Listing to purchase`

bash

curl -X POST https://gameplaygen.com/api/economy/marketplace/buy \
  -H "Authorization: Bearer gg_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "gameId": "j97abc...",
    "playerId": "j97ghi...",
    "listingId": "j97listing..."
  }'

json

{
  "success": true,
  "data": {
    "taxAmount": 25,
    "sellerReceives": 475
  }
}

GET /audit-flags

Get anti-cheat audit flags for your game. See Anti-Cheat docs.

Param	Type	Description
`severity`	`string`	`Filter by 'warning' or 'critical'`
`limit`	`number`	`Results per page (default 50)`

bash

curl "https://gameplaygen.com/api/economy/audit-flags?severity=warning" \
  -H "Authorization: Bearer gg_live_sk_..."

json

{
  "success": true,
  "data": [
    {
      "severity": "warning",
      "reason": "Possible laundering: 6 transfers with same player in 1 minute",
      "playerId": "j97def...",
      "resolved": false,
      "createdAt": 1708700000000
    }
  ]
}

Error Codes

Status	Meaning
`400`	`Missing or invalid request fields`
`401`	`Missing or invalid API key`
`404`	`Player, currency, or item not found`
`422`	`Validation failed (e.g. insufficient balance, recipe on cooldown)`
`429`	`Rate limited (anti-cheat)`
`500`	`Internal error`