# The bank: accounts in your server's coins

> An account for every player in the server's own coins: deposit, withdraw, /pay anybody, a ledger of every change, a banker players click - and plots, zone unlocks and Create shops paying from it. New in 0.5.0, off by default.

Source: https://stygion.eu/docs/keystone/bank
Updated: 2026-11-16

The module `bank` (**off by default** - it holds people's money, so a server turns it on knowingly) gives every player an account in the coins your server already uses. Coins stay real items: the bank is where they wait when nobody wants to carry them. Nothing here depends on STYGION.

## The coins

`bank.coins` lists them, one line per coin - the same lines as `crates.items` and plots' coins: a value in the smallest unit, a short name, the item, its look and its name.

```toml
coins = [
  "1 obol mymod:coin_obol look=mymod:coin_obol Obol",
  "8 ember mymod:coin_ember look=mymod:coin_ember Ember Hex",
  "64 seal mymod:coin_seal look=mymod:coin_seal Styx Seal",
  "512 sovereign mymod:coin_sovereign look=mymod:coin_sovereign glint Sovereign"
]
```

A balance is kept in the smallest unit and written back in coins (`3 seal 2 obol`). An amount can be typed either way: `200` or `3seal`. Only an item carrying the coin's mark (`look=`) counts: the same item without it, or with another mark, is never taken.

## For players

- `/bank` - your balance.
- `/bank deposit` - every coin you carry goes onto your account.
- `/bank withdraw <amount>` - paid out in coins; `/bank withdraw 2seal` asks for that coin (that is how you change money), a plain number for the largest coins that make it. At most an inventory of coins (2304) at once; what does not fit goes back onto the account.
- `/bank history` - the last changes on your account.
- `/pay <player> <amount>` - money to somebody else, online or away. A name that two accounts have carried is refused rather than guessed; the receiver is told at once, or reads it in `/bank history`. `bank.transfer-fee` takes a percent of each payment (rounded up) out of the economy: the receiver gets the amount less the fee, nobody gets the fee.

`/bank` needs `keystone.bank` and `/pay` needs `keystone.bank.pay`; the `default` group has both, so a server that wants accounts without transfers between players takes the second away.

## A banker players click

`bank.banker.place` puts one figure in the world that a right click turns into the bank - K → Bank for a player with Keystone in their game, the balance and the commands in chat for one without.

```toml
[banker]
place = "minecraft:overworld 209.5 131 43.5 69"   # world, x, y, z, where it looks (degrees)
entity = "minecraft:villager"                     # any entity: a wandering trader, an armour stand, a mod's
name = "Banker"                                   # over its head; empty = no name
data = "{VillagerData:{profession:\"minecraft:librarian\",level:5,type:\"minecraft:plains\"}}"
```

The banker does nothing else: no trades, no AI, no damage, never led away, renamed or - by a mod that picks villagers up through a click - carried off; every click on it is cancelled before the entity hears it. While its chunk is loaded Keystone looks after it every five seconds: a missing banker comes back, a second copy goes, a moved one is put back. Nothing is loaded for it. Emptying `place` removes it. A server with `spawn-npcs=false` in `server.properties` removes every villager and wandering trader itself, a banker too - give it another entity there.

## Paying from the account

Plots, zone unlocks and Create shops take money from the pocket and the account together. `bank.pay-order` says which first: `pocket-first` (the default), `bank-first`, or `bank-only`. Change is given back in the largest coins that make it.

**Create shops** (`bank.create-shops`, on): at a Table Cloth shop, a buyer who lacks the price coins gets the missing ones taken from their account just before the Stock Keeper counts the payment - after Create has checked its stock, so nothing is taken for a purchase that cannot happen. Without Create nothing of it runs.

A plot's seller is paid onto their account, even when they are away. `bank.crates-to-bank` puts coins from crates and votes on the account instead of in the inventory. Quests and chapters can pay coins straight onto the account (`coins 2seal` as a reward).

## Nothing lost, nothing made

Both sides of a `/pay` are one change and one database transaction. A deposit takes only what the account can take; a withdrawal is worked out in coins before the account is touched, and coins that cannot be handed over go back. A write the database refuses is kept, tried again, and named in the log at stop if it never went through.

**After a crash** the world comes back at its last save and the accounts do not roll back with it. Every exchange of coins between an inventory and the bank is numbered in the player's own saved data; at their next join the exchanges that data never saw are put right, once:

- a deposit whose coins came back is taken off the account (`bank.crash-revert.take-back`, `on` or `log-only`);
- a withdrawal whose coins may be lost **waits for the owner** (`bank.crash-revert.give-back`, `log-only` by default): coins handed on before the crash still exist and the bank cannot tell, so giving them back on its own word would let a player who can crash the server copy money. They are listed under `/bank waiting` and on the editor's Bank screen, where the owner gives them back or dismisses them.

## The ledger

Every change is one line: when, whose, how much, what kind (`deposit`, `withdraw`, `pay`, `paid`, `plot`, `plot-sold`, `refund`, `unlock`, `shop`, `crate`, `quest`, `staff`, `crash-revert`, `crash-waiting`), with whom, a note, and the balance after.

## The editor and the API

The editor's **Bank** screen lists every account and all the money on accounts, a player's history, the whole ledger, what waits after a crash, and lets staff add to or take from an account with a reason the player reads.

| Route | Scope | What |
|---|---|---|
| `GET /v1/bank` | `bank.read` | accounts, largest first; the total; the coins, the fee, the payment order; what waits after a crash |
| `GET /v1/bank/history?player=<uuid>&most=50` | `bank.read` | one player's ledger, newest first |
| `GET /v1/bank/ledger?most=100` | `bank.read` | the whole server's ledger |
| `POST /v1/bank/adjust` | `bank.write` | `player` (uuid or name), `amount` (minus to take), `reason` |
| `POST /v1/bank/waiting` | `bank.write` | `id`, `action` = `give` or `dismiss` |

Both are **owner's** scopes only, and the bank's settings (`bank.*`, the unlocks' prices, `plots.player-sales.fee`, `crates.items`) can be written in the game only by the owner - not by a group that holds `keystone.settings.write`.

For addons: `Player.savedNumber` / `saveNumber` keep a number in a player's saved data, `Player.save()` writes it now.

## Settings

`bank.coins`, `bank.pay-order` (`pocket-first`), `bank.transfer-fee` (0), `bank.create-shops` (on), `bank.crates-to-bank` (off), `bank.crash-revert.take-back` (`on`), `bank.crash-revert.give-back` (`log-only`), `bank.banker.place` (empty), `bank.banker.entity` (`minecraft:villager`), `bank.banker.name` (`Banker`), `bank.banker.data` (empty). The bank replaces the exchange module of 0.3.
