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 RefreshMinutes for the whole server, in the Currency you 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 price from 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 LaunchPrice from 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 + Step x 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 Fee is 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 AtmModels models 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 to AtmModels.
  • Unpaid invoices are never deleted. On purpose: an unpaid invoice is money owed. Only paid and cancelled ones are removed after Config.Retention.invoices days. The sender can cancel an old one.
  • A job removed from Jobs still 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.