AstralExchange

A new dimension of server economy

AstralExchange turns your server economy into an interactive market of fictional cryptocurrencies. Players deposit funds, trade tokens, follow prices and manage their portfolios through a clear inventory GUI. Created by Szkogis.

• Prices shaped by players - buying raises the price, selling lowers it, and larger orders have a greater price impact.
• 10 original currencies included - each with its own liquidity pool, symbol, color and item icon.
• Every player action in a GUI - markets, buying and selling, portfolio, bank, history and language selection. No resource pack required.
• Data refreshed during play - every 20 ticks by default, approximately once per second at 20 TPS. Includes approximately 24h statistics, the seven latest 5-minute candles and the last 20 trades per account.
• Scheduled trading hours - daily, weekly, monthly and one-time closures with a 24-hour clock and configurable time zone.
• Make it fit your server - Vault, optional PlaceholderAPI, included English and Polish translations, and custom languages and HEX or & colors.

A market your players can move

Each currency has cash and token reserves. A constant-product AMM calculates prices from those reserves. Buying removes tokens from the pool and raises the price. Selling returns tokens and lowers it. Initial liquidity keeps trading possible even with a small player population.

• Liquidity and slippage: larger orders receive a less favorable average execution price. The confirmation GUI shows the cost or proceeds, fee and price impact before execution.
• Default fee: 0.30%: fees are removed from circulation. They are not paid to an administrator account.
• Quotes last up to 10 seconds: a trade by another player on the same currency invalidates the quote. The player must request and confirm a new quote; stale orders are rejected without charging funds.
• Circuit breaker: by default, a 20% price change in the active observation window of up to 60 seconds triggers a 60-second pause for that currency. The triggering trade still executes.

This is a self-contained game economy: no real-world price feeds, player order book, limit/stop orders, leverage or short selling. Prices stay unchanged without trades. Portfolio values are spot estimates; sale proceeds include slippage and fees.

10 currencies. Each with its own identity.

• Velunor
Symbol: VLU
Placeholder ID: velunor

• Draveli
Symbol: DRV
Placeholder ID: draveli

• Korynth
Symbol: KYN
Placeholder ID: korynth

• Mivora
Symbol: MVR
Placeholder ID: mivora

• Thalvex
Symbol: TVX
Placeholder ID: thalvex

• Oryndel
Symbol: OYD
Placeholder ID: oryndel

• Zelvori
Symbol: ZVR
Placeholder ID: zelvori

• Nymbril
Symbol: NMB
Placeholder ID: nymbril

• Ruveth
Symbol: RVH
Placeholder ID: ruveth

• Fendrali
Symbol: FDL
Placeholder ID: fendrali

Each currency starts with 100,000 tokens in its pool. Customize names, symbols, colors and item materials. Between 1 and 10 currencies are supported. Keep existing currency IDs unchanged because player holdings are linked to them.

Requirements and quick start

Minecraft Java Edition • Paper 26.2 • Java 25

1. Stop your server and place AstralExchange-1.0.0.jar in the plugins folder.
2. For the default VAULT mode, install Vault and an economy provider supporting at least two decimal places. Vault alone does not store balances.
3. Optionally install PlaceholderAPI. The astral expansion registers automatically; no eCloud download is needed.
4. Start your server and customize plugins/AstralExchange/config.yml. Perform a full restart after configuration changes.
5. Run /gielda or /crypto, open the bank, deposit funds and confirm the transfer. Then select a currency and quantity, review the quote and confirm your trade.

Default closure: every day, 23:00–07:00, Europe/Warsaw. The bank, portfolio and history remain accessible while trading is closed. New accounts start with a balance of 0.

To run without Vault, set economy.mode: INTERNAL and restart. Use the server console to grant exchange funds with gieldaadmin credit PlayerName 10000.00; the player must be online. This command creates new funds and is also available in Vault mode.

Commands

• /gielda
Action: Opens the main exchange GUI.
Permission: astralexchange.use

• /crypto
Action: Alias of /gielda.
Permission: astralexchange.use

• /exchange
Action: Alias of /gielda.
Permission: astralexchange.use

• /gieldaadmin
Action: Opens the administration GUI.
Permission: astralexchange.admin

• /gieldaadmin status
Action: Displays exchange status.
Permission: astralexchange.admin

• /gieldaadmin close
Action: Manually closes trading; the closure survives restarts.
Permission: astralexchange.admin

• /gieldaadmin schedule
Action: Removes the manual closure and returns to the configured schedule.
Permission: astralexchange.admin

/gieldaadmin schedule does not force trading open during a scheduled closure. Set dates and times in the configuration file. There is no reload command; perform a full server restart after changes.

Server console commands

These commands require the server process console. Players, RCON and command blocks cannot run them. Replace arguments shown in <angle brackets> with actual values.

gieldaadmin credit <player> <amount>

Grants newly created exchange funds to an online player. <amount> is a positive amount such as 10000.00. This does not transfer funds from another player.

gieldaadmin pending

Lists up to 100 pending Vault transfers and the IDs needed for reconciliation.

gieldaadmin reconcile <player-uuid> <transfer-uuid> applied

Resolves a pending transfer when the Vault-side operation did take place.

gieldaadmin reconcile <player-uuid> <transfer-uuid> not-applied

Resolves a pending transfer when the Vault-side operation did not take place.

Before using reconcile, verify the UUIDs, direction and amount against your economy provider logs. applied refers to the Vault-side outcome: an exchange deposit withdraws server economy funds; an exchange withdrawal deposits server economy funds. Reconciliation never calls Vault again. Choosing the wrong outcome can misstate balances.

Permissions

• astralexchange.use
Default: Everyone
Access: Player GUI and commands.

• astralexchange.trade
Default: Everyone
Access: Buying and selling tokens.

• astralexchange.bank
Default: Everyone
Access: Vault deposits and withdrawals.

• astralexchange.admin
Default: Operator (OP)
Access: Administration GUI and status, close and schedule.

Opening the player GUI requires astralexchange.use; trading and banking also check their respective permissions. The admin permission does not bypass the console-only restriction on grants and bank recovery commands.

PlaceholderAPI - complete reference

Requires PlaceholderAPI. For currency placeholders, replace velunor with an ID from the currency table, such as %astral_price_nymbril%. Numbers use a decimal point without currency symbols or thousands separators.

• %astral_status%
Value: Status: open, closed, loading or storage-error.

• %astral_open%
Value: Whether trading is open: true/false.

• %astral_market_count%
Value: Number of loaded markets.

• %astral_loaded%
Value: Whether the account is loaded in memory: true/false.

• %astral_balance%
Value: Available exchange cash balance.

• %astral_portfolio%
Value: Spot value of all player tokens.

• %astral_equity%
Value: Token value plus available cash.

• %astral_realized%
Value: Realized player profit/loss.

• %astral_unrealized%
Value: Spot value minus open-position cost basis.

• %astral_pending%
Value: Whether the account has a transfer awaiting settlement.

• %astral_price_velunor%
Value: Current spot price of the currency.

• %astral_change_velunor%
Value: Approximately 24h percentage change, without the % sign.

• %astral_volume_velunor%
Value: Approximately 24h volume in server money.

• %astral_liquidity_velunor%
Value: Cash reserve in the liquidity pool.

• %astral_reserve_velunor%
Value: Token reserve in the liquidity pool.

• %astral_holdings_velunor%
Value: Number of tokens held by the player.

• %astral_value_velunor%
Value: Spot value of the player position.

• %astral_cost_velunor%
Value: Remaining cost basis of the player position.

• %astral_halted_velunor%
Value: Whether this currency is in a circuit-breaker pause.

Placeholders read memory only, including known offline accounts. They do not create accounts, access storage or call Vault. Missing accounts return 0 for player numbers and loaded=false.

Scheduling with a 24-hour clock

Combine daily, weekly, monthly and one-time closures. Times use HH:mm in your configured time zone. Example:

Example closures - Europe/Warsaw:

• DAILY: every day, 23:00-07:00.
• WEEKLY: Saturday and Sunday, 12:00-13:00.
• MONTHLY: day 1 of each month, 00:00-06:00.
• ONCE: 2026-12-24, 15:00-23:59.

Configure these rules in config.yml under schedule.closures.

Trading closes whenever at least one rule is active. A 23:00–07:00 closure crosses midnight; weekdays and days of the month refer to the start date. Start times are inclusive and end times exclusive. Daylight-saving transitions are handled using the configured zone.

For round-the-clock trading, set schedule.closures: [], restart the server and remove any manual closure with /gieldaadmin schedule.

Your language. Your colors.

English en_US and Polish pl_PL are included. Add another language by copying a file in languages, for example to de_DE.yml, translating its values and setting language-name. Preserve variables such as {price} and {balance}. The language setting selects the default; players can save their own choice in the GUI.

Text supports #A78BFA, &#A78BFA, legacy codes such as &a and &f, and formatting with &l, &o and &r. Theme and currency color fields accept #RRGGBB or a color from &0 to &f. Quote these values in YAML. Tags such as <purple> are not used.

Example theme colors:

• accent: #A78BFA
• positive: #34D399
• negative: #FB7185
• text: #E2E8F0
• muted: #94A3B8

Administrators configure languages, colors, icons and market settings in files. Changes require a full restart. The administration GUI provides manual closure and a return to the configured schedule.

Performance and transaction safeguards

• Smooth inventory refresh: changed slots update without reopening the inventory, with refresh work spread across ticks.
• Bounded workload: click cooldowns and limits on open GUIs, accounts and queued operations. Defaults allow up to 100 open GUIs and 128 queued operations.
• Consistent accounting: integer money calculations, serialized transactions and a durable journal written before changes are applied.
• Validated actions: quote confirmation, permission checks and controls that block item movement through inventory clicks and dragging.
• Trade limits: defaults of 1 to 1,000,000 money units and up to 20% of the current token reserve per trade. Sell-all orders follow the same limits.
• Failure handling: storage errors stop trading. Vault transfers with an uncertain outcome await console reconciliation instead of being automatically retried.
• No plugin network services: no external price requests, telemetry or runtime library downloads. Disk work runs off the main thread; Vault calls run on the main thread.

Designed for Paper 26.2. Folia and shared data across multiple servers are not supported. A listing on SpigotMC does not imply compatibility with the Spigot server implementation. The Vault plugin is required.





Nowy wymiar ekonomii serwera

AstralExchange zamienia pieniądze serwera w interaktywny rynek fikcyjnych kryptowalut. Gracze wpłacają środki, kupują tokeny, śledzą kursy i zarządzają portfelem w czytelnym GUI ekwipunku. Autor: Szkogis.

• Rynek zależny od graczy - kupno podnosi kurs, sprzedaż go obniża, a większe zlecenia mocniej wpływają na cenę.
• 10 autorskich walut na start - każda z osobną pulą płynności, symbolem, kolorem i ikoną.
• Cała obsługa gracza w GUI - rynek, kupno i sprzedaż, portfel, bank, historia oraz wybór języka. Bez wymaganego resource packa.
• Dane aktualizowane podczas gry - domyślnie co 20 ticków, czyli około sekundy przy 20 TPS. Statystyki około 24h, siedem ostatnich świec 5-minutowych i 20 ostatnich transakcji konta.
• Kontrola godzin handlu - codzienne, tygodniowe, miesięczne i jednorazowe przerwy. Zapis 24-godzinny i wybrana strefa czasowa.
• Dopasowanie do serwera - Vault, opcjonalne PlaceholderAPI, polski i angielski oraz własne języki i kolory HEX lub &.

Rynek, na który mają wpływ gracze

Każda waluta ma rezerwę gotówki i tokenów. Model AMM stałego iloczynu wylicza kurs na podstawie tych rezerw. Zakup usuwa tokeny z puli i zwiększa cenę. Sprzedaż zwraca tokeny i obniża cenę. Pula początkowa pozwala handlować również przy małej liczbie graczy.

• Płynność i poślizg cenowy: większe zlecenie otrzymuje mniej korzystny średni kurs. GUI pokazuje koszt lub przychód, prowizję i wpływ transakcji na cenę przed zatwierdzeniem.
• Prowizja domyślnie 0,30%: jest usuwana z obiegu. Nie trafia na konto administratora.
• Wycena ważna do 10 sekund: jeśli inny gracz zmieni kurs tej waluty, trzeba pobrać i potwierdzić nową wycenę. Nieaktualne zlecenie jest odrzucane bez pobrania pieniędzy.
• Przerwa ochronna: domyślnie zmiana ceny o 20% w aktywnym oknie do 60 sekund uruchamia 60-sekundową przerwę dla danej waluty. Transakcja wywołująca przerwę zostaje wykonana.

To samodzielna ekonomia gry: bez pobierania prawdziwych kursów, arkusza zleceń, zleceń limit/stop, dźwigni i krótkiej sprzedaży. Bez transakcji kurs pozostaje stały. Wartość portfela jest wyceną spot; kwota sprzedaży uwzględnia poślizg i prowizję.

10 walut. Własny charakter każdej z nich.

• Velunor
Symbol: VLU
ID do placeholderów: velunor

• Draveli
Symbol: DRV
ID do placeholderów: draveli

• Korynth
Symbol: KYN
ID do placeholderów: korynth

• Mivora
Symbol: MVR
ID do placeholderów: mivora

• Thalvex
Symbol: TVX
ID do placeholderów: thalvex

• Oryndel
Symbol: OYD
ID do placeholderów: oryndel

• Zelvori
Symbol: ZVR
ID do placeholderów: zelvori

• Nymbril
Symbol: NMB
ID do placeholderów: nymbril

• Ruveth
Symbol: RVH
ID do placeholderów: ruveth

• Fendrali
Symbol: FDL
ID do placeholderów: fendrali

Każda waluta zaczyna ze 100 000 tokenów w puli. Można zmieniać nazwy, symbole, kolory i materiały ikon. Obsługiwane jest 1–10 walut. Zachowaj identyfikatory już używanych walut - są powiązane z portfelami graczy.

Wymagania i szybki start

Minecraft Java Edition • Paper 26.2 • Java 25

1. Zatrzymaj serwer i umieść AstralExchange-1.0.0.jar w folderze plugins.
2. W domyślnym trybie VAULT zainstaluj Vault oraz plugin ekonomii obsługujący przynajmniej dwa miejsca po przecinku. Sam Vault nie przechowuje salda.
3. Opcjonalnie zainstaluj PlaceholderAPI. Rozszerzenie astral zarejestruje się automatycznie; nie pobieraj go z eCloud.
4. Uruchom serwer i dostosuj plugins/AstralExchange/config.yml. Po zmianach konfiguracji wykonaj pełny restart.
5. Wpisz /gielda lub /crypto, otwórz bank, wpłać środki i potwierdź przelew. Następnie wybierz walutę, ilość i zatwierdź wycenę.

Domyślna przerwa: codziennie 23:00-07:00, Europe/Warsaw. Bank, portfel i historia pozostają dostępne podczas zamknięcia. Nowe konta mają saldo 0.

Tryb bez Vault: ustaw economy.mode: INTERNAL i zrestartuj serwer. Środki giełdowe przyznaje konsola przez gieldaadmin credit NazwaGracza 10000.00; gracz musi być online. Ta komenda emituje nowe środki i działa także w trybie Vault.

Komendy

• /gielda
Działanie: Otwiera główne GUI giełdy.
Permisja: astralexchange.use

• /crypto
Działanie: Alias /gielda.
Permisja: astralexchange.use

• /exchange
Działanie: Alias /gielda.
Permisja: astralexchange.use

• /gieldaadmin
Działanie: Otwiera GUI administratora.
Permisja: astralexchange.admin

• /gieldaadmin status
Działanie: Wyświetla stan giełdy.
Permisja: astralexchange.admin

• /gieldaadmin close
Działanie: Włącza ręczne zamknięcie, zachowane po restarcie.
Permisja: astralexchange.admin

• /gieldaadmin schedule
Działanie: Usuwa ręczną blokadę i przywraca działanie według harmonogramu.
Permisja: astralexchange.admin

/gieldaadmin schedule nie wymusza otwarcia podczas zaplanowanej przerwy. Daty i godziny ustawia się w konfiguracji. Plugin nie udostępnia komendy reload; po zmianach wykonaj pełny restart.

Komendy wyłącznie z konsoli serwera

Poniższe polecenia wymagają lokalnej konsoli procesu serwera. Nie można ich wykonać jako gracz, przez RCON ani blok poleceń. Nawiasy <...> oznaczają argumenty do zastąpienia.

gieldaadmin credit <player> <amount>

Przyznaje nowe środki giełdowe graczowi online. <amount> to dodatnia kwota, np. 10000.00. Nie przenosi środków od innego gracza.

gieldaadmin pending

Pokazuje do 100 oczekujących przelewów Vault wraz z identyfikatorami potrzebnymi do rozliczenia.

gieldaadmin reconcile <player-uuid> <transfer-uuid> applied

Rozlicza oczekujący przelew, gdy operacja po stronie Vault została wykonana.

gieldaadmin reconcile <player-uuid> <transfer-uuid> not-applied

Rozlicza oczekujący przelew, gdy operacja po stronie Vault nie została wykonana.

Przed reconcile sprawdź UUID, kierunek i kwotę w logach dostawcy ekonomii. applied dotyczy wyniku po stronie Vault: przy wpłacie na giełdę jest to pobranie pieniędzy z ekonomii serwera; przy wypłacie - dodanie pieniędzy do ekonomii serwera. Rozliczenie nie wywołuje Vault ponownie. Błędny wybór może błędnie zaksięgować środki.

Permisje

• astralexchange.use
Domyślnie: Wszyscy
Dostęp: GUI i komendy gracza.

• astralexchange.trade
Domyślnie: Wszyscy
Dostęp: Kupowanie i sprzedawanie tokenów.

• astralexchange.bank
Domyślnie: Wszyscy
Dostęp: Wpłaty i wypłaty przez Vault.

• astralexchange.admin
Domyślnie: Operator (OP)
Dostęp: GUI administracji oraz status, close i schedule.

Dostęp do GUI wymaga astralexchange.use; handel i bank sprawdzają dodatkowo własne uprawnienia. Uprawnienie administratora nie zastępuje ograniczenia „tylko konsola” dla operacji finansowych i naprawczych.

PlaceholderAPI - pełna lista

Wymaga zainstalowanego PlaceholderAPI. W wariantach walutowych zastąp velunor identyfikatorem z tabeli walut, np. %astral_price_nymbril%. Liczby używają kropki dziesiętnej, bez symbolu waluty i separatorów tysięcy.

• %astral_status%
Wartość: Stan: open, closed, loading lub storage-error.

• %astral_open%
Wartość: Czy handel jest otwarty: true/false.

• %astral_market_count%
Wartość: Liczba załadowanych rynków.

• %astral_loaded%
Wartość: Czy konto znajduje się w pamięci: true/false.

• %astral_balance%
Wartość: Dostępna gotówka giełdowa gracza.

• %astral_portfolio%
Wartość: Wartość spot wszystkich tokenów gracza.

• %astral_equity%
Wartość: Wartość tokenów plus dostępna gotówka.

• %astral_realized%
Wartość: Zrealizowany wynik gracza.

• %astral_unrealized%
Wartość: Wartość spot minus koszt otwartych pozycji.

• %astral_pending%
Wartość: Czy konto oczekuje na rozliczenie przelewu.

• %astral_price_velunor%
Wartość: Aktualny kurs spot waluty.

• %astral_change_velunor%
Wartość: Zmiana około 24h w procentach, bez znaku %.

• %astral_volume_velunor%
Wartość: Obrót około 24h w pieniądzu serwera.

• %astral_liquidity_velunor%
Wartość: Rezerwa gotówki w puli.

• %astral_reserve_velunor%
Wartość: Rezerwa tokenów w puli.

• %astral_holdings_velunor%
Wartość: Liczba tokenów posiadanych przez gracza.

• %astral_value_velunor%
Wartość: Wartość spot pozycji gracza.

• %astral_cost_velunor%
Wartość: Nierozliczony koszt pozycji gracza.

• %astral_halted_velunor%
Wartość: Czy trwa przerwa ochronna danej waluty.

Placeholdery korzystają z pamięci, również dla znanych kont offline. Nie tworzą kont, nie zapisują danych i nie wywołują Vault. Dla nieistniejącego konta wartości liczbowe gracza wynoszą 0, a loaded=false.

Harmonogram w formacie 24-godzinnym

Połącz zamknięcia dzienne, tygodniowe, miesięczne i jednorazowe. Godziny HH:mm są interpretowane w ustawionej strefie czasowej. Przykład konfiguracji:

Przykładowe zamknięcia - Europe/Warsaw:

• DAILY: codziennie, 23:00-07:00.
• WEEKLY: sobota i niedziela, 12:00-13:00.
• MONTHLY: pierwszy dzień miesiąca, 00:00-06:00.
• ONCE: 2026-12-24, 15:00-23:59.

Reguły ustaw w config.yml w sekcji schedule.closures.

Wystarczy jedna aktywna reguła, aby wstrzymać handel. Przedział 23:00–07:00 przechodzi przez północ; dzień tygodnia lub miesiąca oznacza dzień rozpoczęcia. Początek jest włączony, koniec wyłączony. Obsługiwane są zmiany czasu letniego i zimowego.

Dla handlu przez całą dobę ustaw schedule.closures: [], zrestartuj serwer i w razie potrzeby zdejmij ręczną blokadę komendą /gieldaadmin schedule.

Twój język. Twoje kolory.

W zestawie znajdują się pl_PL i en_US. Aby dodać język, skopiuj plik z folderu languages, np. do de_DE.yml, przetłumacz wartości i ustaw language-name. Zachowaj zmienne takie jak {price} i {balance}. Ustawienie language wybiera język domyślny, a gracz może zapisać własny wybór w GUI.

Tekst obsługuje #A78BFA, &#A78BFA, kody &a, &f oraz formatowanie &l, &o, &r. Pola kolorów motywu i walut przyjmują #RRGGBB lub kolor &0– &f. W YAML ujmuj te wartości w cudzysłowy. Tagi takie jak <purple> nie są używane.

Przykładowe kolory motywu:

• accent: #A78BFA
• positive: #34D399
• negative: #FB7185
• text: #E2E8F0
• muted: #94A3B8

Administrator konfiguruje języki, kolory, ikony i parametry rynku w plikach. Zmiany wymagają pełnego restartu. GUI administratora służy do ręcznego zamknięcia i przywrócenia harmonogramu.

Wydajność i ochrona transakcji

• Spokojne odświeżanie GUI: aktualizacja zmienionych slotów bez ponownego otwierania okna; praca rozłożona między ticki.
• Ograniczone obciążenie: limity kliknięć, liczby okien, kont i kolejki zleceń. Domyślnie do 100 otwartych GUI i 128 operacji w kolejce.
• Spójne rozliczenia: pieniądze liczone całkowitoliczbowo, jedna kolejka transakcji i trwały dziennik zapisywany przed zastosowaniem zmiany.
• Kontrola operacji: potwierdzanie wycen, weryfikacja uprawnień i blokada przenoszenia przedmiotów przez kliknięcia oraz przeciąganie w GUI.
• Limity zleceń: domyślnie od 1 do 1 000 000 jednostek pieniądza i do 20% bieżącej rezerwy tokenów na transakcję. Dotyczą również „sprzedaj wszystkie”.
• Obsługa awarii: błąd zapisu zatrzymuje handel. Przelew Vault o nieznanym wyniku pozostaje do rozliczenia w konsoli, bez automatycznego ponawiania.
• Brak usług sieciowych pluginu: bez pobierania kursów, telemetrii i pobierania bibliotek podczas działania. Operacje dyskowe odbywają się poza głównym wątkiem; wywołania Vault pozostają na głównym wątku.

Plugin jest przeznaczony dla Paper 26.2. Folia i wspólna baza kilku serwerów nie są obsługiwane. Publikacja na SpigotMC nie oznacza zgodności z samym silnikiem Spigot. Wymagany jest plugin Vault