# GTA Capital: external server operator handoff

This package connects an authorized existing FiveM server to the agreed GTA Capital platform. It does not create a game host, provision a tenant or contain credentials. Keep the existing GTA Capital web UI; point this resource to that deployment's authorized API origin.

## Required from the platform operator

- The exact HTTPS API origin, with no path or port.
- A dedicated server-role API credential bound to your realm's tenant.
- Confirmation that the platform's durable MySQL database, migrations and tenant are ready.

A public server listing/join code does not grant financial access. Do not use a shared realm key or an administrator credential.

## Install

1. Extract the ZIP. Copy its `gta_capital` folder to `resources/[finance]/gta_capital`; keep the name unchanged.
2. Back up your framework database. Import `gta_capital/install.sql` there. This creates a snapshot table; it does not import or modify player bank money.
3. Select `Config.Framework` in `config.lua`: `qbox`, `qbcore` or `esx`. `auto` is available, but explicit selection avoids ambiguity on customized servers.
4. Configure the following in private server configuration. Replace the placeholders with values supplied privately by the platform operator. Use `set`, never `setr`:

```cfg
set gta_capital_api_url "https://YOUR-AGREED-GTA-CAPITAL-ORIGIN"
set gta_capital_api_key "YOUR-PRIVATE-TENANT-BOUND-SERVER-KEY"
ensure oxmysql
ensure qbx_core
ensure gta_capital
add_ace group.admin gta_capital.admin allow
```

For QBCore use `ensure qb-core`; for ESX use `ensure es_extended`, instead of `ensure qbx_core`. Start installed ownership resources before `gta_capital` if you enable their adapters. Never place API keys in shared/client Lua, public files or Git.

5. Run `capital_status` in the server console. Join with a loaded character and type `/capital`.
6. Confirm the platform administrator sees a fresh heartbeat for your expected server identity. Test accounts, browser sign-in and a Capital transfer before announcing integration.

## Player web access

In `/capital`, choose **Open web dashboard**, then **Open secure link**. The resource requests a character-bound, one-time sign-in code. The code expires in 60 seconds and is consumed by the website. Server credentials stay on FXServer. An unrelated public listing cannot create this session.

## Optional ownership and secured lending

Ownership adapters are off by default. Configure only the exact installed garage/housing schema described in `docs/FIVEM.md`. Vehicle valuations must be supplied by the operator; property values can come from the supported authoritative property table.

Collateral locks are separately disabled until database guards are installed. See `docs/FIVEM_LOCKS.md`; installing the basic resource alone does not activate secured lending. The optional Node installer requires the project's `mysql2` dependency. Run it from the full GTA Capital repository after `npm ci`, as documented, or have the platform operator perform that migration with your authorized database administrator. Do not upload database credentials to the website or send them to players.

## Money boundary

Framework bank/cash balances are read-only snapshots. Capital accounts use the separate tenant-isolated virtual ledger. Automatic deposits/withdrawals between those systems are not enabled by this package. Real Solana assets remain separate, with no currency conversion or cash-out.

## Package verification

`SHA256SUMS` verifies packaged resource/document bytes. On Linux, from the extracted `gta_capital` directory:

```sh
sha256sum -c SHA256SUMS
```

`package-manifest.json` describes the same files. The adjacent download `gta_capital.zip.sha256` verifies the entire ZIP. Frameworks, oxmysql, FXServer binaries and secret configuration are intentionally not bundled.

Full architecture and operator duties: `docs/EXTERNAL-SERVERS.md`. API deployment: `docs/BACKEND.md`. Resource installation: `docs/FIVEM.md`.
