/api/system/encryption-status

GET

Lightweight probe used by clients to decide whether to prompt the user for a login password.

http://localhost:8080/api/system/encryption-status

Description

Reports two facts about the running server:

  • key_set — Is a password loaded this session? (Has /api/system/load-password already been called and is the derived key still in memory?)
  • encrypted_files_exist — Are there any .bin files in the registered wallets' Bank or Fracked folders whose on-disk header marks them as encrypted?

From those two facts the server derives login_required: true if encrypted files exist AND no key is set (the user must supply the password before any encrypted-coin operation can succeed). The client can branch on login_required instead of running its own scan.

Type 10 transition

File encryption is being rebuilt on the Type 10 format (encrypted files are exactly 612 bytes; plaintext Type 9 files are 439 bytes). In the current build, encrypted_files_exist: true can only mean leftover files from the removed legacy scheme — they are unsupported and should be restored from a plaintext backup. Once Type 10 lands, this endpoint will additionally report a state of encrypted, decrypted, or mixed (mixed = an interrupted encrypt/decrypt run that should be finished by re-running the same endpoint).

Use this before login

This endpoint is the recommended first call for a fresh client. It tells you whether the user even needs a password prompt — many users will see encrypted_files_exist: false and can skip the login step entirely.

Parameters

None.

Response

Success — 200 OK

No encrypted files yet, no login
{
  "command": "encryption-status",
  "success": true,
  "key_set": false,
  "encrypted_files_exist": false,
  "login_required": false
}
Encrypted files exist; user has not logged in yet
{
  "command": "encryption-status",
  "success": true,
  "key_set": false,
  "encrypted_files_exist": true,
  "login_required": true
}
User is logged in
{
  "command": "encryption-status",
  "success": true,
  "key_set": true,
  "encrypted_files_exist": true,
  "login_required": false
}

Response Fields

FieldTypeDescription
key_setbooltrue if a derived encryption key is currently held in memory (someone has logged in and not logged out).
encrypted_files_existbooltrue if at least one .bin file in any registered wallet's Bank or Fracked folder has encryption_type != 0 in its header.
login_requiredboolConvenience: encrypted_files_exist && !key_set. Branch on this in the client.

Decision table for clients

key_setencrypted_files_existlogin_requiredWhat the client should do
falsefalsefalseNo password is needed. The wallet is decrypted (no .bin files also counts as decrypted). The user MAY encrypt via the Security menu.
falsetruetruePrompt for password (before the dashboard appears) and POST to /api/system/load-password.
trueanyfalsePassword already loaded this session. Proceed.

Example Usage

curl "http://localhost:8080/api/system/encryption-status"
const res = await fetch('http://localhost:8080/api/system/encryption-status');
const s = await res.json();

if (s.login_required) {
  // show password prompt, then POST /api/system/load-password
} else if (!s.key_set && !s.encrypted_files_exist) {
  // optional: ask the user if they want to set a password now
}
import requests
s = requests.get('http://localhost:8080/api/system/encryption-status').json()
print(s)
# {'command': 'encryption-status', 'success': True,
#  'key_set': False, 'encrypted_files_exist': True, 'login_required': True}

Related Endpoints