Features
Bank, invoices and crypto
The Bank app, invoices, crypto at live prices and Coin Lab.
Four money features share this page.
| Feature | App | Config |
|---|---|---|
| Bank: balance, transfers, extra accounts, job account, requests, nearest ATM | Bank | Config.Bank |
| Invoices: bills between players and from companies | Invoices, and the Bills tab of Bank | Config.Invoices |
| Crypto: real coins at live prices | The Crypto tab of Bank | Config.Crypto |
| Coin Lab: coins players launch themselves | Coin Lab | Config.Coins |
All of them use the character's bank money from the framework (QBCore, Qbox, ESX). The phone keeps no balance of its own for the main account; it only keeps the history. Money shown on the phone is formatted with Config.Currency.
#1. Bank
#What the player sees
The Bank app has four tabs: Wallet (the balance, cash, the IBAN, recent transactions, the spending chart), Bills, Crypto and Accounts.
- Send Money. The player types a phone number or an IBAN, or picks a contact. The phone shows the name it belongs to before sending (or "a private account" when that player hides their name with streamer mode). Each transfer can carry a note.
- Request Money ("Ask for money"). Sends the other player a personal request. It arrives in their Invoices and in the Bills tab of their Bank, and they pay it with one tap.
- Your Spending. Deposits, withdrawals, money received and sent, for a day, a week, a month or all time.
- Nearest ATM. The 3 closest ATMs around the player, with the street and the distance. Route to the Nearest sets a waypoint.
The receiver of a transfer gets a notification, also when they were offline.
#The IBAN
Every character has an IBAN. It comes from the bank adapter when the bank resource has one for the character (tgiann-bank), otherwise the phone makes one with ServerConfig.IbanGenerate in config_server.lua. Transfers accept either the IBAN or the phone number.
#Bank adapters
The adapter decides two things: where the IBAN comes from, and where job accounts (company money) are kept.
Adapter |
Needs | Job accounts |
|---|---|---|
'tgiann-bank' |
tgiann-bank | tgiann-bank's job accounts |
'qb-management' |
qb-management | qb-management |
'renewed-banking' |
Renewed-Banking | Renewed-Banking |
'esx_society' |
esx_society and esx_addonaccount | society_<job> |
'framework' |
nothing | none |
'auto' uses the first one that runs, in that order. A named adapter that is not running falls back to auto with a warning. The console prints the result at start: bank adapter: <name>. Writing your own adapter is explained in Bank integration.
#Extra accounts
With Accounts.Enabled = true, a character can open up to Accounts.Max extra accounts from the Accounts tab:
| Kind | What it is |
|---|---|
| Savings | The owner's alone |
| Shared | The owner adds other players by phone number, up to Accounts.SharedMembers besides the owner |
A shared account member is either a Member (can put money in and take it out) or a Viewer (can only look). Money moves between accounts with Between Accounts. An account only closes when it is empty. Each account has its own IBAN and its own activity list showing who moved what.
With tgiann-bank running the phone does not keep its own extra accounts. It shows tgiann-bank's extra and shared accounts instead, read only: deposits and withdrawals happen at tgiann-bank's ATMs.
#Job account
With Accounts.JobAccount = true, a player whose grade is a boss grade sees their job's account in the Accounts tab and can move money between it and their own. Taking money out of the job account needs a reason. This needs an adapter with job accounts; with 'framework' there is none.
#Options
| Option | Default | What it does |
|---|---|---|
Adapter |
'auto' |
Bank adapter, see above |
Accounts.Enabled |
true |
Players can open extra accounts |
Accounts.Max |
3 |
Extra accounts one character can own, savings and shared together |
Accounts.SharedMembers |
5 |
People on one shared account besides the owner |
Accounts.JobAccount |
true |
Bosses see their job account and can move money in and out |
Requests |
true |
"Ask for money" in Bank. Works even when Config.Invoices.EveryoneCanSend is false |
AtmModels |
prop_atm_01, prop_atm_02, prop_atm_03, prop_fleeca_atm |
Prop models the Nearest ATM screen looks for |
Also used by the bank:
| Option | Default | What it does |
|---|---|---|
Config.Limits.TransferMax |
1000000 |
Largest transfer, account move, request, invoice and crypto order |
Config.Limits.CashMessageMax |
50000 |
Largest amount sent or requested inside a chat in Messages; see Messaging |
Config.Currency |
{ Code = 'USD', Symbol = '$', Locale = 'en-US' } |
How amounts are written on the phone |
A Turkish server would use Config.Currency = { Code = 'TRY', Symbol = '₺', Locale = 'tr-TR' }. Locale sets the thousands separator, the decimal mark and where the symbol goes.
#2. Invoices
An invoice is a bill one player sends another. It waits in the receiver's Invoices app (and the Bills tab of Bank) until they pay it. Paying takes the amount from the receiver's bank.
| Kind | Who sends it | Who gets the money |
|---|---|---|
| Personal | Any player, when EveryoneCanSend = true |
The sender, in full |
| Company | Players of a job listed in Jobs, with an allowed grade |
Split between the job account and the employee |
| Request | Any player, from Bank's Request Money, when Config.Bank.Requests is on |
The sender, in full |
| Script | Another resource, with AddInvoice |
The job account (with a job), the player named as sender, or nobody (a plain label, such as a fine) |
The receiver can be addressed by phone number. They do not have to be online. The sender can cancel an invoice while it is unpaid; once paid it cannot be undone. The receiver gets a notification for a new invoice, the sender when it is paid.
#Company invoices and the split
luaGradeShare = { Base = 20, PerGrade = 5, Max = 50 },
Jobs = {
police = { label = 'Police', cutSender = 'rest', cutReceiver = 'grade', send = 'all' },
mechanic = { label = 'Mechanic', cutSender = 70, cutReceiver = 30, send = { 2, 3, 4 } },
ambulance = { label = 'EMS', cutSender = 'rest', cutReceiver = 'grade', share = { Base = 10, PerGrade = 5, Max = 40 } },
},
The shipped config.lua holds a long example list. Set Jobs to your server's jobs.
| Field | What it does |
|---|---|
label |
The name on the invoice |
cutSender |
Percent that goes to the job account, or 'rest': whatever the employee does not get |
cutReceiver |
Percent that goes to the employee who sent the invoice, or 'grade': a share that grows with their grade (below) |
share |
Optional { Base, PerGrade, Max } for this job, used instead of GradeShare |
send |
Grades allowed to send: 'all' or a list such as { 2, 3, 4 } |
The names are easy to mix up: cutSender is the company's share, cutReceiver the employee's. Whatever the two leave below 100 is paid to nobody. When they add up to 100, the rounding remainder goes to the job.
#Share by grade
With cutReceiver = 'grade' the employee's percent is GradeShare.Base at grade 0, plus GradeShare.PerGrade for every grade above it, never more than GradeShare.Max. With the defaults that is 20 % at grade 0, 35 % at grade 3 and 50 % from grade 6 up. Add cutSender = 'rest' and the job account gets the other part, so nothing is lost.
The grade is the one the employee had when they sent the invoice; it is stored with it. For an invoice sent before this was stored, the sender's current grade is used if they are online in that job, otherwise grade 0.
If the job's share cannot be paid into a job account (no adapter with job accounts, or the job has no account), the payment is refused, the payer gets the money back, and the app says so. With the 'framework' adapter, set cutSender = 0 for every job.
An employee who is offline when the invoice is paid gets their share through the framework's offline money (QBCore, Qbox, ESX). Where that is not possible it is kept and paid on their next login.
#Options
| Option | Default | What it does |
|---|---|---|
EveryoneCanSend |
true |
Any player can send personal invoices. The admin tablet can change it while the server runs |
GradeShare |
{ Base = 20, PerGrade = 5, Max = 50 } |
The employee's share by grade, for jobs with cutReceiver = 'grade' |
Jobs |
an example list | Jobs that can bill in the company's name, and the split. Set it to your server's jobs |
Config.Retention.invoices |
90 |
Days a paid or cancelled invoice is kept. Unpaid invoices are money owed and are never deleted by the clean-up |
#fx-billingapp
When the bundled Billing app (fx-billingapp, see Config.BundledApps) is running, the phone's own Invoices icon leaves the home screen so players do not see two invoice apps. The invoices themselves stay: Bank still lists bills and requests, and scripts still bill through fx-phone's exports. Set ['fx-billingapp'] = false in Config.BundledApps to keep the phone's own Invoices app.
#3. Crypto
The Crypto tab of Bank lets players buy, sell and send real coins at live prices.
- Prices come from CoinGecko, fetched by the server once every
RefreshMinutesfor the whole server, in theCurrencyyou set. Every phone gets the new prices at once. - If CoinGecko cannot be reached, the last known price stays. Before the first live price, and always when live prices are off, the
pricefrom the config is used. - Buying takes the cost from the bank, rounded up to a whole unit. Selling pays into the bank, rounded down.
- Coins can be sent to another player by phone number or IBAN. The receiver gets a notification.
#Coins
luaCoins = {
{ id = 'bitcoin', symbol = 'BTC', name = 'Bitcoin', price = 65000, canBuy = true, canSell = true, canTransfer = true },
...
},
| Field | What it does |
|---|---|
id |
The CoinGecko id of the coin (bitcoin, ethereum, litecoin, …) |
symbol, name |
What the player sees |
price |
Used until the first live price arrives, and always when live prices are off |
icon |
Optional https:// image |
canBuy, canSell, canTransfer |
Switch each action off for this coin |
Scripts can add their own coin with a price they move themselves (AddCustomCoin), and give or take coins: see Server exports: crypto.
#Options
| Option | Default | What it does |
|---|---|---|
Currency |
'usd' |
CoinGecko quote currency, lower case ('try' for lira) |
RefreshMinutes |
30 |
Minutes between two price fetches. Keep it at 5 or more on the free API |
Coins |
BTC, ETH, LTC | The coins on sale |
In config_server.lua, ServerConfig.Crypto.CoinGecko switches live prices on or off, and ServerConfig.Crypto.ApiKey takes an optional CoinGecko demo key. The keyless API is enough at the default interval.
#4. Coin Lab
Coin Lab (app id coins, not installed by default) lets players launch their own coin and trade it.
- Launching costs
LaunchPricefrom the bank. The player picks a name, a 3 to 6 letter ticker, a mark and a colour. A ticker can only exist once. - The price follows the supply. Price =
BasePrice+Stepx coins in circulation. Every buy raises it, every sell lowers it. - No money is created. What buyers pay goes into the coin's reserve, and sellers are paid from it.
- A fee of
Feeis charged on every buy and sell. A buy's fee leaves the economy; a sell's fee stays in the coin's reserve, backing the coins still held. The launch price leaves the economy too. - Coins are listed by Popular (market cap), New and Volume, each with its price, the last week as a small line and the change over that week.
#What the player sees
| Screen | What is on it |
|---|---|
| Home | A wallet card with the portfolio's value and total open profit/loss, My Coins (holding, value and profit/loss per coin) and the market list |
| A coin | The price chart over 1 hour, 1 day, 1 week, 1 month or since launch (move the pointer over it for the price and time of any moment), My Position, the coin's statistics, the player's own dated trades of it, and Buy / Sell |
| Buy / Sell | The order is quoted by the server before it is placed: the total, the average per coin, the price it leaves behind and, for a sale, what it makes against the cost on record |
| My Portfolio | The portfolio's value over time, cost, open and realised profit/loss, and how the value is spread over the coins held |
| History | Every buy, sale and launch of the character with its date and time, grouped by day; a sale shows what it made |
#How the figures are worked out
- Value is what selling the whole holding right now would pay, fee taken off. On a price line a large holder lowers the price while selling, so "price x coins" would promise money nobody can get.
- Cost is the money that left the bank for the coins held, fees included. Average cost is that divided by the coins it paid for.
- Open profit/loss is value minus cost. Realised profit/loss is what every sale so far paid minus the cost of the coins sold. A sale takes its share of the cost with it, so the average cost of what is left does not change.
- Charts are drawn from the trades: a price only moves when the coin is traded, and each trade stores the price it left behind. Nothing is stored or made up in between, so a quiet coin shows a flat line.
- Coins bought before this was tracked (holdings that existed before the update) have no cost on record. The app says so instead of inventing one: their value is shown, their profit/loss is not, and selling them books no profit. Coins bought afterwards into the same holding are tracked normally. Older trades are also missing from History, because who made them was not stored.
#Options
| Option | Default | What it does |
|---|---|---|
Enabled |
true |
false switches Coin Lab off: the icon goes and every request is refused, trading included. Coins and holdings are kept and come back when it is switched on again |
LaunchPrice |
500 |
Price of launching a coin |
BasePrice |
1.0 |
Price of the first coin |
Step |
0.01 |
How much the price rises per coin in circulation |
Fee |
0.02 |
Share of every buy and sell that is taken (2 %). At most 0.2, higher values are lowered to it |
MaxPerPlayer |
2 |
Coins one character may launch |
MaxTrade |
5000 |
Coins in one order |
#Exports
| Page | Exports |
|---|---|
| Server exports: bank | AddTransaction GetBankData SetBankData |
| Server exports: invoices | AddInvoice GetInvoices DeleteInvoice |
| Server exports: crypto | AddCrypto RemoveCrypto GetOwnedCoin GetCoin AddCustomCoin |
| Client exports: other | GetCryptoWallet GetCoinValue |
#Good to know
- A transfer to an offline player fails with "offline". The framework has no offline money (standalone, or a custom bridge that does not fill
AddOfflineMoney). The sender gets the money back. - Paying a company invoice fails. The bank adapter has no account for that job. Use an adapter with job accounts, or set
cutSender = 0. - No job account in the Accounts tab. The player's grade is not a boss grade,
Accounts.JobAccount = false, or the adapter has no account for that job. - "Open a New Account" is missing. tgiann-bank is running (its own accounts are shown instead), or
Accounts.Enabled = false. - Nearest ATM finds nothing. It only sees props of the
AtmModelsmodels that the game has loaded around the player, so it finds nothing in the countryside. An ATM without a prop, or of another model, is never found: add your custom ATM prop models toAtmModels. - Unpaid invoices are never deleted. On purpose: an unpaid invoice is money owed. Only paid and cancelled ones are removed after
Config.Retention.invoicesdays. The sender can cancel an old one. - A job removed from
Jobsstill has its old unpaid invoices. Paying one sends the full amount to the job account. - Every money move holds a lock per character, so two moves for the same character never run at the same time. A second one in the meantime is refused and can simply be tried again.