# exec-mcp database scheme (agreed reference)

## Clean generic scheme

### accounts

- `id` → internal primary key, hidden
- `display_name` → arbitrary label shown in UI
- `venue` → exchange name, e.g. `bitstamp`
- `venue_account_ref` → exchange-side account id, e.g. Bitstamp user id
- `description` → optional note
- `enabled` → boolean
- `metadata_json` → optional extra metadata
- `created_at`
- `updated_at`

### account_secrets

- `account_id` → FK to `accounts.id`
- `api_key`
- `api_secret`
- `created_at`
- `updated_at`

### balance_snapshots

- `id` → internal primary key
- `account_id` → FK to `accounts.id`
- `asset_code` → e.g. `BTC`, `EUR`
- `balance_value`
- `captured_at`

### order_records

- `id` → internal primary key
- `account_id` → FK to `accounts.id`
- `instrument` → e.g. `BTC/EUR`
- `side`
- `order_kind`
- `quantity`
- `price`
- `status`
- `raw_json`
- `created_at`
- `updated_at`

## Key rules

- UI never shows `accounts.id`.
- In communication, distinguish clearly:
  - **`id`** = internal id used for operations.
  - **`venue_account_ref`** = external exchange account reference.
- `venue_account_ref` is **not unique** and must **not** be used for operations.
- Dashboard operations (update/delete and similar mutations) must use internal `id` only.