WalletPress Documentation

Complete reference for the WalletPress 30-chain wallet generation engine. CLI, REST API, deployment, and security.

Base URL: http://localhost:8000/api/v1/chain-vault · v1.0.0 · 86 API routes

Quickstart

WalletPress runs as a Docker Compose stack. After purchasing, you get the full source code as a .tar.gz archive.

# 1. Extract
tar xzf walletpress-1.0.0.tar.gz && cd walletpress

# 2. Start (one command)
docker compose up -d

# 3. Verify the API is running
curl http://localhost:8000/api/v1/chain-vault/healthz

# 4. Generate your first wallet
vault-package generate eth --count 3

# Or via REST API
curl -X POST http://localhost:8000/api/v1/chain-vault/generate \
  -H "Content-Type: application/json" \
  -d '{"chain":"eth","count":1}'

What's Included

Component	Description	Lines
`wallet_factory.py`	Core engine: 30-chain generation, encryption, keccak verification	~950
`wallet_factory_router.py`	86 REST API endpoints, vault management, authentication	~850
`wallet_features.py`	Multi-chain generation, validation, key management	501
`wallet_phase2.py`	Advanced features: balances, RPC, proofs, sweep	589
`wallet_enhancements.py`	HD wallets, paper wallets, import, webhooks, bulk ops	221
`wallet_premium.py`	API keys, tx builder, alerts, multisig, gas dashboard	376
`wallet_enterprise.py`	Bulk 1000, unlinkable wallets, auto-funding, batch proofs	~400
`shamir.py`	Shamir's Secret Sharing over GF(256) — pure Python	~200
`wallet_killer.py`	Mnemonic recovery, chain adder, wallet DNA, plugins	563
`wallet_rbac.py`	Role-based access control for multi-user deployments	138
`Dockerfile + compose.yaml`	Containerized deployment with health checks	—
`vault-package` CLI	Bash CLI with SSH auto-tunnel, 14 commands	—

Supported Chains (30 Total)

Every major blockchain family. Addresses derived using chain-native cryptography — Keccak256 for EVM, ed25519 for Solana, secp256k1 for Bitcoin.

Bitcoin (Legacy)

Bitcoin (SegWit)

Bitcoin (Native SW)

Ethereum

Base

Polygon

Arbitrum

Optimism

Avalanche

BSC

Fantom

Gnosis

Solana

TRON

Dogecoin

Litecoin

Bitcoin Cash

Dash

Zcash

Cardano

NEAR

Sui

Aptos

XRP

Polkadot

Cosmos

Algorand

Tezos

Monero

TON

13 chain families: Bitcoin, EVM (9 L1/L2), Solana, TRON, Doge-family (4), Privacy (2), Cardano, NEAR, Sui, Aptos, XRPL, Polkadot, Cosmos, Algorand, Tezos, Monero, TON.

Architecture

┌─────────────────────────────────────────┐
│              Docker Compose              │
│  ┌─────────────┐  ┌──────────────────┐  │
│  │   FastAPI    │  │  Encrypted Vault │  │
│  │  Port :8000  │◀─│  (Fernet + AES)  │  │
│  │  86 Routes   │  │  Volume-mounted  │  │
│  └──────┬───────┘  └──────────────────┘  │
│         │                                 │
│  ┌──────▼──────────────────────────────┐ │
│  │      Wallet Factory Engine          │ │
│  │  eth-hash · coincurve · ecdsa ·    │ │
│  │  bip_utils · PyNaCl · base58 ·     │ │
│  │  monero · cryptography              │ │
│  └─────────────────────────────────────┘ │
│             30 Chains · 13 Families       │
└─────────────────────────────────────────┘

Key Design Decisions

Keccak256 for EVM — Not SHA3-256. Ethereum uses Keccak with different padding. We use eth-hash for correct address derivation.
On-chain verification — Every address derived by the factory is independently verified against each chain's canonical library (eth-keys, coincurve, PyNaCl, etc.).
Zero external dependencies at runtime — No API calls, no cloud services, no telemetry. The container is fully self-contained.
Volume-persisted vault — Wallet data stored on a Docker volume, surviving container restarts and upgrades.

Security Model

IMPORTANT: Private keys are cryptographic secrets. Follow these guidelines to protect your wallets.

Never expose port 8000 publicly — Run behind nginx reverse proxy with TLS or keep local-only.
Enable API key authentication — Set ADMIN_API_KEY in your environment. All vault endpoints then require X-API-Key header.
Use client-side encryption — Keys can be encrypted in your browser/CLI before reaching the server (zero-knowledge).
Enable Fernet encryption — Auto-enabled on first run. All private keys encrypted at rest in the vault JSON.
Rotate keys regularly — Use /rotate endpoint or vault-package rotate. Full audit trail tracks every rotation.
Use RBAC for multi-user — Role-based access: admin, operator, viewer roles with granular permissions.

Cryptographic Standards

Component	Algorithm	Standard
EVM / TRON	Keccak256 (secp256k1)	Ethereum Yellow Paper
Bitcoin / Doge-family	secp256k1 + RIPEMD-160	BIP32/39/44/84
Solana	ed25519 (Curve25519)	SLIP-0010
Cosmos / Polkadot	sr25519 / ed25519	Substrate
NEAR / Sui / Aptos	ed25519	BIP44
Vault encryption	Fernet (AES-128-CBC + HMAC-SHA256)	Python cryptography
Shamir MPC	Shamir's Secret Sharing GF(256)	Threshold cryptography

Encryption Modes

Mode	Description	Security Level	Use Case
None	Keys stored as plaintext in vault	Low	Testnets, development
Server-side (Fernet)	Keys encrypted with auto-generated key. Vault stored encrypted on disk.	Medium	Production, single-user
Client-side (AES-256-GCM)	Keys encrypted with user passphrase before transmission. Server never sees plaintext.	High	Multi-user, shared infra
Shamir MPC	Key split into N shares. Need threshold M to reconstruct. No single point of failure.	Highest	Enterprise, custody

CLI Reference

The vault-package CLI auto-detects whether it's running on your server or remotely. On remote machines it tunnels through SSH automatically.

generate

Generate wallets on any chain.

# Generate 5 Ethereum wallets
vault-package generate eth --count 5

# With labels
vault-package generate sol --count 10 --label airdrop-batch-1

# Include private keys (CAUTION)
vault-package generate btc --count 3 --include-keys

# JSON output for scripting
vault-package generate eth --count 1 --json

list

vault-package list                          # All wallets
vault-package list --chain eth              # Filter by chain
vault-package list --limit 100              # Paginate

import

vault-package import eth 0xabc123... --label "cold-storage"

validate

vault-package validate eth 0x847ca23452c3418358be201d41f6ed7ea8bcd95a
# → Valid: True

balances

vault-package balances           # Check all vault wallet balances

gas

vault-package gas                # Gas prices across all 30 chains

paper

vault-package paper a1b2c3d4              # Generate printable wallet
vault-package paper a1b2c3d4 -o ~/out.html # Custom output path

export

vault-package export              # Export vault to JSON
vault-package export --csv         # Export as CSV

rotate

vault-package rotate a1b2c3d4     # Rotate a specific wallet key
vault-package rotate --chain eth   # Rotate all ETH wallets

chain

vault-package chain               # Table of all 30 chains
vault-package chain --json         # JSON output

stats

vault-package stats               # Vault stats: count, chains, encryption

hd

vault-package hd "abandon abandon abandon ..." --label "main-hd"

bulk

vault-package bulk eth --count 1000      # Generate 1,000 wallets
vault-package bulk --status batch-abc123  # Check bulk job status

REST API — Base URL & Authentication

All endpoints are under /api/v1/chain-vault/. The API serves JSON on port 8000.

Auth: If ADMIN_API_KEY is set, include X-API-Key: your-key header on all requests. Without it, the vault is open to localhost-only access.

Core Endpoints

POST/generateGenerate wallets

Generate one or more wallets on any chain. Supports batch labels.

{"chain":"eth","count":3,"include_private_key":false,"label":"my-batch"}

GET/vaultList all wallets

Returns all wallets in the vault. Supports ?chain=eth and ?limit=100 query params.

GET/vault/{id}Get wallet by ID

Returns a single wallet with full details. Private key only included if ?include_key=true and auth is valid.

POST/importImport existing wallet

Import a wallet by private key hex. Validates the key against chain format before storing.

{"chain":"eth","private_key_hex":"abc123...","label":"imported"}

GET/chainsList all 30 chains

Returns chain metadata: name, symbol, family, address format, derivation path.

GET/statsVault statistics

Returns generation count, chain breakdown, encryption status, vault health.

POST/validateValidate address

Validate an address against its chain format rules. Returns {"valid": true/false}.

{"chain":"eth","address":"0x847ca..."}

POST/rotateRotate wallet keys

Rotate keys for a specific wallet or all wallets on a chain. Audit trail logged.

{"wallet_id":"a1b2c3d4"}

GET/exportExport vault

Export vault data. ?format=csv for CSV, default is JSON.

Security & Key Management

POST/split-keyShamir MPC split

Split a private key into N shares using Shamir's Secret Sharing. Default: 3 shares, threshold 2. Pure Python GF(256) implementation.

{"private_key_hex":"64-char-hex","shares":3,"threshold":2}

POST/reconstruct-keyReconstruct from shares

Reconstruct a private key from N shares. Any threshold number of shares works.

{"shares":["share1...","share2..."]}

GET/audit-trailView audit log

Returns all wallet operations: generation, rotation, import, export with timestamps.

GET/health-score/{id}Wallet health score

Returns a health score for a wallet based on key age, rotation status, and encryption state.

Operations

GET/balancesCheck all balances

Returns balances for all vault wallets grouped by chain. Uses live RPC for EVM chains.

GET/gasGas dashboard

Gas prices for all 30 chains. Live RPC for 7 EVM chains, static estimates for 23 non-EVM chains.

POST/hd-walletHD wallet from mnemonic

Generate deterministic wallets from a BIP39 mnemonic.

{"mnemonic":"abandon abandon ...","label":"hd-main"}

GET/rpc-chainsRPC health check

Returns which chains have live RPC endpoints and their latency.

POST/paperGenerate paper wallet

Generate an HTML paper wallet with QR codes for a wallet ID.

{"wallet_id":"a1b2c3d4"}

POST/link/proofGenerate ownership proof

Generate a cryptographic proof of wallet ownership (signed message).

Enterprise

POST/generate/bulkBulk 1,000 wallets

Generate up to 1,000 wallets in a background thread. Returns batch ID. Poll GET /generate/bulk/{id} for status.

{"chain":"eth","count":1000,"label":"airdrop"}

POST/generate/unlinkableUnlinkable wallets

Generate N wallets with independent entropy. No common seed. Cryptographically provable independence.

{"chain":"eth","count":10}

POST/proof/signBatch proof signing

Sign a message with N wallet keys in a single API call. Returns Merkle-like proof hash.

POST/funding-plansAuto-funding plans

Create auto-funding rules: "when a wallet is generated, fund it with X ETH from master wallet."

POST/tx/buildBuild transaction

Build and sign a raw transaction. Specify recipient, amount, gas.

{"wallet_id":"a1b","to":"0xdef...","amount_wei":"1000000000000000000"}

Deployment

WalletPress ships as a self-contained Docker Compose project. Requirements: Linux server, Docker Engine 20.10+, 1GB+ RAM, 5GB+ disk.

# 1. Extract the archive
tar xzf walletpress-1.0.0.tar.gz && cd walletpress

# 2. Configure (optional — see below)
export ADMIN_API_KEY=your-secure-api-key

# 3. Start the stack
docker compose up -d

# 4. Check logs
docker compose logs -f backend

# 5. Verify health
curl http://localhost:8000/api/v1/chain-vault/healthz

Configuration

Variable	Required	Default	Description
`ADMIN_API_KEY`	Recommended	none	API key for vault endpoints. If unset, localhost-only access.
`VAULT_DIR`	No	`/app/.rmi/wallets`	Path to vault data directory (volume-mounted).
`LOG_LEVEL`	No	`INFO`	Python logging level: DEBUG, INFO, WARNING, ERROR.
`PORT`	No	`8000`	API listen port.

Post-Deployment Verification

# Health check
curl http://localhost:8000/api/v1/chain-vault/healthz
# → {"status":"ok","service":"wallet-factory","version":"1.0.0"}

# Generate a test wallet
curl -X POST http://localhost:8000/api/v1/chain-vault/generate \
  -H "Content-Type: application/json" \
  -d '{"chain":"eth","count":1}'

# Check chains
curl http://localhost:8000/api/v1/chain-vault/chains | jq '.total_chains'
# → 30

Downloads & Resources

Resource	Format	Size	Download
Complete Documentation	PDF	~2.1 MB	walletpress-docs.pdf
API Reference (this page)	HTML	—	docs.html
Quickstart Cheat Sheet	Coming soon	—	—

← Back to WalletPress · Need help? [email protected]

WalletPress Documentation

Quickstart

What's Included

Supported Chains (30 Total)

Architecture

Key Design Decisions

Security Model

Cryptographic Standards

Encryption Modes

CLI Reference

generate

list

import

validate

balances

gas

paper

export

rotate

chain

stats

hd

bulk

REST API — Base URL & Authentication

Core Endpoints

Security & Key Management

Operations

Enterprise

Deployment

Configuration

Post-Deployment Verification

Downloads & Resources

📄 WalletPress Documentation PDF