Economy API

Manage player balances, view transaction history, and get market pricing.

Get Player Balance

Retrieve the current balance for a player.

Endpoint: GET /api/economy/balance?username=Player123

Authentication: Required (JWT)

Query Parameters:

• username - Minecraft username (optional, defaults to authenticated user)

Success Response (200):

{
  "success": true,
  "username": "Player123",
  "balance": 5000.50,
  "symbol": "💰",
  "formatted": "💰5,000.50"
}

Example:

curl "http://localhost:8080/api/economy/balance?username=Player123" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Error Responses:

• 403 - Can only view own balance (unless admin)
• 404 - Player not found
• 503 - Economy system not available

---

Get Transaction History

View transaction history for a player.

Endpoint: GET /api/economy/history?username=Player123&limit=50

Authentication: Required (JWT)

Query Parameters:

• username - Minecraft username (optional, defaults to authenticated user)
• limit - Number of transactions (default: 50, max: 200)
• page - Page number for pagination (default: 1)

Success Response (200):

{
  "success": true,
  "username": "Player123",
  "transactions": [
    {
      "id": 12345,
      "type": "PURCHASE",
      "amount": -100.0,
      "balance": 4900.50,
      "description": "Purchased Diamond Sword",
      "timestamp": "2024-01-15T14:30:00Z"
    },
    {
      "id": 12344,
      "type": "SALE",
      "amount": 500.0,
      "balance": 5000.50,
      "description": "Sold 10x Diamond",
      "timestamp": "2024-01-15T14:25:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 150,
    "pages": 3
  }
}

Example:

curl "http://localhost:8080/api/economy/history?limit=20" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Transaction Types:

• PURCHASE - Shop purchase
• SALE - Item sale
• TRANSFER - Player-to-player transfer
• ADMIN - Admin adjustment
• REWARD - Quest or achievement reward

---

Get Market Prices

Retrieve current market prices for items.

Endpoint: GET /api/economy/market-prices

Authentication: Required (JWT)

Success Response (200):

{
  "success": true,
  "prices": {
    "DIAMOND": {
      "buyPrice": 100.0,
      "sellPrice": 80.0,
      "stock": 500,
      "trend": "RISING"
    },
    "IRON_INGOT": {
      "buyPrice": 5.0,
      "sellPrice": 4.0,
      "stock": 1000,
      "trend": "STABLE"
    }
  },
  "lastUpdated": "2024-01-15T15:00:00Z"
}

Example:

curl http://localhost:8080/api/economy/market-prices \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Price Trends:

• RISING - Price increasing
• FALLING - Price decreasing
• STABLE - Price stable
• VOLATILE - Rapidly changing

---

Get Currency Symbol

Get the server's configured currency symbol.

Endpoint: GET /api/economy/symbol

Authentication: None required

Success Response (200):

{
  "success": true,
  "symbol": "💰",
  "name": "Coins"
}

Example:

curl http://localhost:8080/api/economy/symbol

---

Code Examples

TypeScript

interface Transaction {
  id: number;
  type: string;
  amount: number;
  balance: number;
  description: string;
  timestamp: string;
}

class EconomyAPI {
  constructor(private baseUrl: string, private token: string) {}
  
  async getBalance(username?: string) {
    const url = username 
      ? `${this.baseUrl}/api/economy/balance?username=${username}`
      : `${this.baseUrl}/api/economy/balance`;
      
    const response = await fetch(url, {
      headers: { 'Authorization': `Bearer ${this.token}` }
    });
    return await response.json();
  }
  
  async getHistory(username?: string, limit = 50, page = 1) {
    const params = new URLSearchParams({
      limit: limit.toString(),
      page: page.toString()
    });
    if (username) params.append('username', username);
    
    const response = await fetch(
      `${this.baseUrl}/api/economy/history?${params}`,
      {
        headers: { 'Authorization': `Bearer ${this.token}` }
      }
    );
    return await response.json();
  }
  
  async getMarketPrices() {
    const response = await fetch(
      `${this.baseUrl}/api/economy/market-prices`,
      {
        headers: { 'Authorization': `Bearer ${this.token}` }
      }
    );
    return await response.json();
  }
  
  async getCurrencySymbol() {
    const response = await fetch(`${this.baseUrl}/api/economy/symbol`);
    return await response.json();
  }
}

Python

class EconomyAPI:
    def __init__(self, base_url, token):
        self.base_url = base_url
        self.headers = {'Authorization': f'Bearer {token}'}
    
    def get_balance(self, username=None):
        params = {'username': username} if username else {}
        response = requests.get(
            f'{self.base_url}/api/economy/balance',
            headers=self.headers,
            params=params
        )
        return response.json()
    
    def get_history(self, username=None, limit=50, page=1):
        params = {'limit': limit, 'page': page}
        if username:
            params['username'] = username
        
        response = requests.get(
            f'{self.base_url}/api/economy/history',
            headers=self.headers,
            params=params
        )
        return response.json()
    
    def get_market_prices(self):
        response = requests.get(
            f'{self.base_url}/api/economy/market-prices',
            headers=self.headers
        )
        return response.json()
    
    def get_currency_symbol(self):
        response = requests.get(f'{self.base_url}/api/economy/symbol')
        return response.json()

Notes

• Economy system requires Vault plugin
• Balances are synced with Vault economy provider
• Market prices update dynamically based on supply/demand
• Transaction history stored for 90 days by default
• Players can only view their own balance (unless admin)
• Currency symbol configurable in config.yml

Related

• Shop API - Purchase items
• Players API - Sell inventory items
• Admin API - Admin economy management