> ## Documentation Index
> Fetch the complete documentation index at: https://docs.awokenlabs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Investing & stocks

> A live stock market players trade from the bank app - NPC tickers, job-driven sectors, and player-owned businesses that float shares and pay dividends.

Awoken Banking ships a full **stock market** players trade from the **Invest** tab of the bank app. Prices move on a server tick, trades run through the same ledger and fees as everything else, and businesses can list themselves to raise capital and pay dividends. Everything here is in `config/stocks.lua`.

## The three kinds of stock

Every ticker is one of three kinds. Each is independently toggleable, so you can run any mix.

<CardGroup cols={3}>
  <Card title="Public" icon="building">
    NPC flavour tickers (Maze Bank, Fleeca, ...). The price **drifts on its own** by its volatility, pulled gently back toward its seed price. Pure speculation. Config kind: `ambient`.
  </Card>

  <Card title="Sector" icon="briefcase">
    Unowned, **activity-driven** tickers - e.g. a job's economy. No shares are issued by anyone; an external script pushes the price with `adjustStockPrice` as work happens. Config kind: `index`.
  </Card>

  <Card title="Business" icon="store">
    A **player- or org-owned** business floats part of itself. Buyers of the primary float pay the business (a capital raise); shares then trade peer-to-peer, and the business can pay dividends. Config kind: `business`.
  </Card>
</CardGroup>

```lua config/stocks.lua theme={"dark"}
Config.Stocks = {
    enabled = true,
    kinds   = { ambient = true, index = true, business = true },
}
```

Turn a kind off and its tickers are hidden and untradeable, while the others keep working. Set `enabled = false` to switch the whole market off.

## What moves a price

| Kind                   | What drives it                                                                                                                                                                |
| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Public** (`ambient`) | A random drift each tick, sized by the ticker's `volatility`, plus a **mean reversion** pull back toward its seed price.                                                      |
| **Sector** (`index`)   | Nothing automatic - your script calls `adjustStockPrice(symbol, deltaPct)` (or `setStockPrice`) to move it from work done, revenue, or deliveries.                            |
| **Business**           | Two things: **peer trades** set the price to the last traded price, and between trades a **book-value gravity** pull nudges it toward the company's `balance / total shares`. |

<Note>
  Buying from a business's primary **float** pays the company at the current price but does not move the price itself - only peer-to-peer fills and the book-value pull do.
</Note>

## Market settings

| Setting            | What it does                                                                                                              | Default |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------- | ------- |
| `tickSeconds`      | How often the market ticks (drift, mean reversion, book-value pull, dividend checks, history snapshot). Lower = livelier. | `60`    |
| `tradeFeePct`      | Fee on each buy / sell, `0`-`1` (`0` = free).                                                                             | `0.01`  |
| `minTrade`         | Fewest shares per trade.                                                                                                  | `1`     |
| `maxTrade`         | Most shares in a single trade (`0` = unlimited).                                                                          | `0`     |
| `marketMakerToTax` | Route Public/Sector trade fees into the tax/revenue pool (else they sink).                                                | `true`  |
| `meanReversion`    | How hard Public tickers are pulled back to their seed each tick, `0`-`1` (`0` = pure random walk).                        | `0.05`  |
| `historyPoints`    | Price snapshots kept per ticker (drives the spark + chart).                                                               | `60`    |

### Public / Sector price band

Public and Sector tickers are clamped to a price band so a spammed or runaway ticker can't spiral. These are the defaults; a per-ticker cap set in `registerStock` (or the in-game add command) overrides them.

```lua config/stocks.lua theme={"dark"}
minPrice = 1,   -- floor for a Public/Sector price
maxPrice = 0,   -- ceiling (0 = no cap)
```

## Business stocks

Business tickers are the deep end: a real business account issues shares, sells a **float** to raise capital, and pays **dividends** out of its balance. The owner manages all of this from the **Company Stock** page in the bank app (a job account they're an admin on). Investors trade from the normal **Invest** tab.

### Book value

A business share is anchored to the company's book value:

```
book value / share = (account balance / total shares) x bookValueMultiplier
```

Each tick the price is pulled `bookValuePull` of the way toward that book value, so a cash-rich business drifts up and one that bleeds its account drifts down.

| Setting               | What it does                                                                            | Default |
| --------------------- | --------------------------------------------------------------------------------------- | ------- |
| `bookValuePull`       | Fraction of the gap to book value closed each tick, `0`-`1` (`0` = pure trader market). | `0.05`  |
| `bookValueMultiplier` | Scales book value into a share price. Raise it if `balance / shares` feels too low.     | `1.0`   |

<Tip>
  `bookValueMultiplier` lets you keep sensible share prices without huge share counts. A business holding \*\*$670,000** across **10,000** shares books at `$67`/share at `1.0`, `$335` at `5.0`, or `$670`at`10.0\`.
</Tip>

### Business guard rails

All of these live under `Config.Stocks.business` and apply only when `kinds.business` is on. Every cap uses `0` to mean "no cap".

| Setting                         | What it does                                              | Default    |
| ------------------------------- | --------------------------------------------------------- | ---------- |
| `minPrice` / `maxPrice`         | Floor / ceiling for a business share's **trading** price. | `10` / `0` |
| `minListPrice` / `maxListPrice` | Range a business may **list or float** shares at.         | `10` / `0` |
| `minDividendPerShare`           | Reject a dividend below this per share.                   | `0`        |
| `maxDividendPerShare`           | Clamp a dividend above this per share.                    | `0`        |
| `maxDividendPerPlayer`          | Cap what one holder receives in a single payout.          | `0`        |

The owner can also set a **reserve** from the Company Stock page - a block of treasury shares kept out of the float so they can never be sold by accident.

### Who can list a business

By default only trusted resources and staff can create a business listing (via the `registerStock` export or the in-game add command). You can let job owners self-list from the app, gated so it can't be spammed.

| Setting                 | What it does                                                              | Default  |
| ----------------------- | ------------------------------------------------------------------------- | -------- |
| `allowBusinessListings` | Let a job owner list their own company from the app.                      | `false`  |
| `listingFee`            | Charged from the business account on a successful self-listing.           | `50000`  |
| `minListingBalance`     | Minimum business balance required to self-list.                           | `100000` |
| `minAccountAgeDays`     | Minimum age of the business account before it may list.                   | `0`      |
| `maxPlayerListings`     | Cap on how many businesses one player may have listed.                    | `25`     |
| `orderExpiryHours`      | Default auto-expire for asks / bids / private offers (owner-overridable). | `48`     |

## Seeded tickers

On first run, an empty market is seeded with the Public tickers under `Config.Stocks.symbols`. Each is `{ symbol, name, price, volatility }`. Edit the list to change the NPC market; add Sector and Business tickers at runtime through the exports.

```lua config/stocks.lua theme={"dark"}
symbols = {
    { symbol = 'MAZE', name = 'Maze Bank', price = 320, volatility = 0.04 },
    { symbol = 'FLCA', name = 'Fleeca',    price = 220, volatility = 0.03 },
    -- ...
},
```

## Driving prices from your scripts

Sector and Business tickers are meant to move with your server's economy. Register a ticker and push its price from real activity through the [stock exports](/resources/awoken-banking/exports#stocks-and-investing):

```lua server-side only theme={"dark"}
-- List a courier "sector" index and nudge it up on every delivery
exports.awoken_banking:registerStock({ symbol = 'CRUR', name = 'Courier Index', kind = 'index', price = 100 })

AddEventHandler('my_courier:delivered', function()
    exports.awoken_banking:adjustStockPrice('CRUR', 0.015)   -- +1.5%
end)
```

<Note>
  Money in the market is whole units, like everywhere else in Awoken Banking. Prices, dividends, and share counts are all integers.
</Note>