Documentation

• Ubuntu 22.04+ or Debian 12+; Mint 21+ and Pop!_OS 22+.
• Fedora 42+; Rocky, AlmaLinux, RHEL, Oracle Linux or CentOS Stream 9–10.
• openSUSE Leap 16+ or Tumbleweed; Arch, Manjaro or EndeavourOS.

Choose a vendor-maintained release. Higher OS requirements take precedence: openSUSE Leap 16 calls for more than 40 GB of disk.

More chains and concurrent invoices may need more CPU and RAM. A bigger VPS does not remove RPC quotas. Setup flows have automated tests; full fresh-VPS testing is not complete for every distribution.

Need a specific release? On a fresh VPS, add --version 7.8.1 to install that exact signed version. Without it, setup uses the latest stable release.

Resume keeps the selected release and completed steps, including with GitHub fallback. It never downgrades an existing installation.

Inspect the installer. Add --check to the command for a compatibility check without installing, or --help for options.

Resume saved progress without replacing keys or settings:

bash <(curl -fsSL https://releases.whollycrypto.com/setup_wholly.sh) --resume

Additional base domains can use the same service names. Any IPv6 records must also point to this VPS. Enable a Cloudflare proxy only after domain validation.

New recognized stablecoin quotes round up: 1.321 USDC → 1.33 USDC, even with zero tolerance. Minimum: 0.01 token.

Existing invoices, balances and partial-payment remainders stay exact. Other/custom tokens keep normal precision.

Your Basic Auth login is saved in /root/whollycrypto/config/setup-credentials.txt. It is separate from the console email/password.

New projects inherit system currency and timezone defaults; stores use the project currency. Existing account timezones are managed separately in Settings → Account.

whollycrypto welcome shows your console URL.

1. Shared nodes, rates, domains, installation credits and updates belong in the Operator panel.
2. Open Wallets → Create receiving wallets for BTC, ETH and Ethereum USDC/USDT. Back up both independent recovery phrases. This dedicated project cannot issue sales invoices; an existing receiving store is preserved.
3. Add a merchant with a credit currency, fee and administrator email. Share the invitation and merchant Basic Auth privately. They choose their password. Never share operator Basic Auth.
4. Merchants top up through your checkout, or you record an explained credit adjustment. Credit is required before creating projects/stores. Manage users and credit history under Merchants → Manage.

Operator setup asks for a fourth address, such as operator.example.com, and its own Basic Auth username and password. Choose your label, point DNS to the VPS, check DNS and activate HTTPS. The panel opens directly on that address. Your merchant, checkout and API addresses stay separate.

Use the new operator Basic Auth login, then your administrator email/password. Merchant Basic Auth stays unchanged. Setup can resume after DNS or certificate errors. Operators upgrading from 7.0.0 complete this step too; existing live addresses stay available.

At 3%, a 100 EUR invoice costs 3 EUR of merchant credit. If its credit currency differs, the creation-time fiat rate is saved with the fee.

The operator pays the normal Wholly Crypto installation fee separately. Customer funds are not split on-chain. Credit purchases are not charged again.

Only automatically verified settlement credits a top-up. Opening a checkout or manually accepting an invoice does not. Reversals create ledger entries; a reversed top-up that returns requires operator review.

Low hosted credit pauses IPN, webhooks, sweeps and creation of new projects/stores. Existing customer invoices and receiving continue. Low installation credit can pause automation across hosted businesses. Disabling a merchant also blocks login and new invoices, while old payments remain monitored.

This is application-level isolation, not a separate VPS for every merchant. Merchants cannot access each other's projects, wallets, API credentials, exchanges or credits. The server administrator can access hosted hot-wallet keys. Tell merchants before onboarding; use trusted hosting, independent backups and suitable capacity for shared workloads.

From 7.2.0, Wallets manages receiving balances, addresses and backups; Sweep handles sends and automatic rules. Keep ETH for token fees. Merchant top-ups tracks their purchases. Header credits pay installation fees separately. My business opens your own console in a new tab.

Open Finances for fees earned, verified installation charges, estimated margin and current merchant credits. Filter by date, merchant or reporting currency; export CSV.

Reports group invoices by first settlement and reflect their latest fee reversals. Prepaid balances are not revenue. Own-business charges stay separate. Pending charges or missing rates leave affected margins unavailable. Converted amounts use current cached fiat rates; gas and running costs are not included.

Add merchant creates an invitation. From 7.3.0, choose a free starting credit in the merchant's credit currency; zero is allowed. This does not refill your operator balance. Send invitation by email is checked by default.

Configure your SMTP provider in Settings → Invitation email first, using TLS or STARTTLS. The connection test sends no email. Alternatively, uncheck email and share the link privately. A failed email keeps the account and credit; do not create the merchant again.

For another link or a password reset, open Merchants → Manage → User accounts. SMTP acceptance is not guaranteed inbox delivery. Share merchant Basic Auth separately, never operator credentials.

Invitations last 48 hours; resets last one hour. Each works once. Replace or revoke a link from the same screen. A reset signs out existing sessions but keeps 2FA enabled. Merchant Basic Auth is still required.

Create accounts directly with a password or send invitations. Manage users, projects, stores, fees and local prepaid credits; read reports and subscribe to signed lifecycle events. First-login custody consent, 2FA and tenant isolation stay in place.

Every write needs a saved idempotency key. Credit grants are local account adjustments, not installation top-ups. Wallet secrets, sending and server configuration stay out of this API.

Use api.your-domain.com/v1/operator. Keep Operator keys on your backend, never in a browser or with a hosted merchant.

Settings → Address book: save a chain/address. Native coins and matched CoinGecko tokens appear automatically. Read-only, admin-managed; checkout acceptance stays unchanged.

Token readers cover 22 chains. Private balances and Bitcoin/CashTokens/Kaspa overlays need separate access or indexers. Failed reads show errors, not zeroes.

Collect invoice balances into another wallet with manual sending or automatic sweeps. Token transfers also need the chain's native coin for fees.

Price unavailable concerns rates, not balances.

1. Store → Payment methods → EVM or Solana → Custom token.
2. Enter contract/mint, name and ticker. Choose fixed USD or automatic DEX pricing.

Network/decimals are checked. Project-wide prices leave existing quotes unchanged. A catalog match alone does not enable checkout.

Automatic pricing

DEX Screener requires an exact-contract pool, $10,000 liquidity and a trade within an hour. Rates refresh each minute; failed or five-minute-old rates block new quotes.

DEX prices can be manipulated; checks are not audits. Use trusted standard ERC-20 or classic SPL tokens. Token-2022/extensions are unsupported. Without a suitable pool, use fixed pricing.

Scanner offline? Invoices keep configured methods while detection waits. Check supported APIs in Chain connections; healthy doesn’t mean scanner-compatible. Default: two independent providers.

Wallets/rates remain required. Monero/Lightning services must issue payment requests.

API/MCP errors include error.details.payment_methods. SDK 2.4.0 adds safe explanations: PHP getPaymentMethodIssues(), Python payment_method_issues, Node paymentMethodIssues. Error reference →

Crypto quotes round upward and include the store's spread. A fiat-priced invoice does not convert the received crypto into a bank balance.

Zero confirmations settles on detection, without network-confirmation protection. Native EVM payments are detected as direct transfers. Review unusual or uncertain payments under Needs attention.

Blocked by default. Enable Stores → Invoice → Allow zero-amount invoices to allow manual/API zero totals. They complete immediately, without a payment, receiving address, transaction or processing fee.

status is the invoice state at event creation; event_type tells you what happened.

• Ethereum example: payment.received + processing, then invoice.settled + settled.
• Solana example: already final when detected, so payment.received and invoice.settled both carry settled.

Either flow can happen on other chains. These are distinct events, not necessarily two payments. They can share sequence but have different event_id values. Delivery order is not guaranteed; do not require processing first.

Events: invoice.created, payment.received, invoice.processing, invoice.settled, invoice.expired, invoice.invalid, invoice.cancelled. Full event table and exception rules →

amount_status: none, partial, paid, overpaid. paid includes tolerance, not finality. timing_status: on_time or late. resolution: automatic, manually_settled or manually_invalidated. Apply your exception policy when requires_review is true.

invoice_id matches the API response. amount, currency and order_id describe your original order. payment_info adds transfers, exact crypto amounts, locked quote/spread/tolerance and advisory rates. Customer data and metadata are private.

paid_chain, paid_asset, paid_payment_method_id, paid_asset_amount, paid_asset_amount_received and settlement_exchange_rate summarize settlement. They stay frozen; missing evidence/history stays null. For later receipts use payment_info or the payments API.

Use decimal strings. Never combine assets or treat unconfirmed funds as missing. Handle exceptions explicitly; a warning alone never authorizes fulfilment or refund. Verified internal gas top-ups are not customer payments and do not trigger payment.received.

Separate signing secrets: Store → IPN signs IPN deliveries, including an invoice's custom ipn_url. Each endpoint in Store → Webhooks has its own secret, shown when created or rotated.

Both use Wholly-Signature and the same SDK verifier, but need the matching secret, not an API key. Rotating the IPN secret does not change webhook secrets.

Verify raw body, timestamp and project/store scope. Save durably, then return HTTP 2xx. A worker checks the current invoice through your configured API host and fulfils once in a database transaction. Headers are unsigned; use version 2's signed body identity.

Event-based: deduplicate signed event_id, then filter invoice.settled. SDK state-based: collapse project + invoice_id + sequence, then check state regardless of event type. Do not add an event filter after this collapse. Both need separate order-level duplicate protection.

Retries keep the original body and event ID. Older revisions must not overwrite newer ones. IPN makes up to eight attempts; webhook retries are optional. Low credits pause deliveries, not payments.

Store → IPN / Webhooks → History → Details shows the saved body and result. Payloads expire after 90 days. Resend is not proof of settlement.

1. Settings → Exchanges: connect a dedicated key, check balances and grant projects. No withdrawal permissions; restrict the key to your VPS IP.
2. Project → Sweep: verify asset, network, address and token contract. For each chain/token, choose either another wallet or one exchange.

Markets refresh every two minutes. Only matched, credited deposits can convert; stale markets stop new orders. A 1% source reserve stays at the exchange for fees/rounding, separate from processing credits.

Keep minimum amount reserves coins/tokens project-wide after automatic sweeps. Separate from the trigger; zero keeps none. Fees use the excess. Manual sends stay unchanged.

Resume uncertain transfers; never replace them. Wallets stay reserved until confirmation or unused-quote expiry. Large sweeps need batches.

Exchange custody, KYC, regional limits and fees apply. No bank payouts or leverage. Low credits pause new conversions; submitted orders still reconcile.

Open Auto top-up after Requests. Choose a backed-up receiving wallet, threshold, purchase amount, daily limit and network-fee cap. Authorize and save. It starts off.

Use BTC, ETH or Ethereum USDC/USDT when offered. Token sending addresses need ETH; this rule does not fund missing gas. Operators use dedicated receiving wallets; hosted merchants pay their Operator.

The approved top-up can run while low credits pause Sweep. Only the receiving service confirms credit. One automatic purchase runs at a time. Disabling stops unsent work, not submitted transactions.

In Auto top-up, use Check payment. Resume the same valid payment, or close a verified failed Ethereum transfer and pause the rule. Pending or uncertain payments stay on hold to prevent duplicate sending. An expired quote is not proof of failure.

The default 1% uses the settled invoice's original fiat value. Customer crypto payments are not split.

Fees continue accruing into a negative balance. Clear the negative amount and restore usable credit above your account's grace threshold. Balance changes normally appear within 10–15 seconds on a healthy connection.

Installing updates requires verified credit above zero, even with an automation grace allowance. Top-ups never install updates automatically.

Paused notifications consume no attempts. Retained deliveries resume; normal expiry still applies. Reconcile missed events through the invoice API.

If the operator disables processing fees, no new processing fees or credit restrictions apply. Previous charges remain in history. An unpaired installation can configure projects/stores, but needs verified billing to issue invoices. Already issued invoices remain monitored.

• Revenue shows settled invoice values before fees/refunds, using settlement dates. It is not wallet balance or profit.
• Conversions use current cached rates, not historical accounting rates. Original currency totals remain available if rates are missing.
• Invoice-status charts use invoice creation dates. Needs-attention figures show current unresolved issues.

• Fixed fiat: each new checkout uses current crypto rates and the store spread, then locks the quote until expiry.
• Fixed crypto: request exact units of one accepted on-chain asset. A fresh fiat value, rounded up, is recorded for reporting and fees; no spread changes the crypto amount.
• Donations: let customers enter an amount within your limits. Add quick amounts and optional name/email fields.
• Point of sale: enter an amount or order reference and show the checkout QR. Wait for settled, not just payment detected.
• Scheduled requests: send once, weekly or monthly in your chosen timezone. Customers pay each invoice themselves. No automatic wallet debits.

Store appearance, confirmations and callbacks still apply. Pausing a tool stops new requests, not existing payments. History links to each invoice. Missed periods do not create an email burst; resending reuses the same unpaid, unexpired invoice.

Customer checkout, payment links and scheduled emails support English, German, Spanish, Brazilian Portuguese, Italian, Russian, Simplified Chinese, French, Korean and Japanese.

Store → Invoice → Checkout language sets the default. Override per invoice or payment tool. Emails and resends keep the invoice language. Your text stays unchanged; Merchant and Operator consoles stay English.

1. Open Settings → Notifications & alerts. Console notifications are built in.
2. For email or Telegram, add a channel, send a verification code and enter it. Then enable the channel and select it on your rules.
3. Choose alerts for payment exceptions, failed callbacks, transfer issues, low gas, delayed scanning, low credits or failed backups. Settled-payment alerts are optional.

Repeated issues are grouped. History lasts 30 days; project permissions still apply. Reading an alert does not resolve the issue. Human alerts do not replace store IPN or webhooks.

Bitcoin mainnet and supported EVM coins/ERC-20 only. Customers pay project-controlled wallets first, not vendors directly. Keep free native coins for fees. Ordinary sweeps exclude protected receiving addresses.

The processing fee applies once to the original invoice, separately from your commission. Underpayments and uncertain receipts need review. Refunds after vendor payout require separate funds, not an automatic clawback.

Set up multi-vendor payments · Marketplace API reference

1. Choose a period, reporting currency and timezone. Filter by project or store, then search invoice, order, asset or transaction references.
2. Review missing rates, fees and payment exceptions in Checks. Details link back to the existing invoice or transfer.
3. Download an accountant ZIP with a printable summary and detailed CSV files. Up to 10,000 records per download; use a shorter period for larger histories.

Confirmed receipts, refunds and recorded costs are separate from wallet transfers and prepaid credit purchases. Invoice totals are counted once, even with multiple payments.

Historical values use retained evidence, not today's prices. Older rates and actual fees may be unavailable; missing costs are never assumed zero. Incomplete evidence keeps the net total unavailable.

This covers records tracked by Wholly Crypto, not every external wallet or exchange transaction. It is a bookkeeping aid, not a tax return or profit statement. Share exports securely: they can contain customer emails.

BTC, EVM, SOL and TRX are joined by 18 native adapters. Use a submission-capable provider. ZEC is transparent-only; ADA retains token outputs; DOT uses Asset Hub; HBAR needs a relay. Outgoing memo/tag/comment destinations need an external wallet.

1. Open Project → Wallets → asset → Send. Choose an address-book entry or enter a destination. Check the full address and network.
2. Choose an exact amount or sweep available, then a fee level. For supported tokens, Use project ETH for gas (or the chain's native coin) can fund missing fees from the same project/chain.
3. Click Prepare transfer. Review sources, destination, amount, maximum fees and any gas allocation. Approve & send authorizes this plan; preparation alone sends nothing.

Gas funding, confirmations and token sending continue in the background after approval. Follow Transfer activity, even after closing the window. Broadcast is not confirmation.

Keep in project wallet ETH: 0 adds no reserve; it does not spend all your ETH. 0.005 keeps at least 0.005 ETH for later, so you need additional funds for this workflow. Saved automatic rules stay unchanged.

1. Open Automatic Sweep Setup → asset → Setup. Choose a wallet address or supported exchange destination, not both.
2. Set the sweep minimum and Keep minimum amount. Example: trigger at 100 USDC, keep 20 USDC, send up to 80 USDC. The reserve is project-wide, not per address.
3. For tokens, review Use project ETH for gas and enter a Daily funding limit. Turn on Auto sweep, then Save rule and confirm. Opening Setup alone enables nothing.

The daily limit caps native gas allocated per token rule over a rolling 24 hours. €1 can be a starting limit for light use, not a guaranteed cost or daily charge. Funding transactions also have fees. Maximum network fee % can limit combined funding/transfer fees.

Checks run automatically. Only eligible token-holding addresses receive gas; empty addresses do not. An underfunded address below the sweep minimum waits. Gas limits explained →

• Back up wallets and test a small transfer. Send tokens before draining native coins. ETH elsewhere in the project must first reach each token address; unused gas stays in your wallets.
• Use fresh balances, healthy providers and sufficient native funds. Automatic rules need an active, backed-up wallet and the asset enabled in an enabled store. Low processing credits can pause sending.
• In Transfer activity, inspect progress, Gas funding and explorer links. On an uncertain result, refresh the same transfer; do not create a replacement. Resume only after reviewing the reason and limits.

Sending disabled? Check whollycrypto transfers status. Review every enabled rule before whollycrypto transfers enable: it applies server-wide and may run saved rules immediately. Stopping future steps cannot reverse broadcasts.

Store → Basic: choose active merchant/pay/API hosts. Links prefer store → default store → system; retired names fall back. Configure SDK hosts separately. Signed retries keep their original links.

• Use Full (strict), not Flexible; no API key needed.
• Disable caching and browser/bot challenges for console, checkout and API.
• Allow /.well-known/acme-challenge/ on port 80 without redirects/challenges for renewals.

Checks query authoritative DNS and verify the origin: Direct or Cloudflare. Visitors may cache older DNS.

Console saves/deletes use POST since 5.6.2; no “Not GET or POST” exception needed. Login and CSRF stay active. On api.*, allow the public API’s documented methods.

Replacing codes or disabling 2FA needs your password and an authenticator or unused recovery code. Other sessions are signed out. Keep phone/server clocks synchronized; 2FA does not secure a compromised server.

The theme icon cycles Light → Dim → Dark and remembers this browser's choice. Store checkout themes are separate.

Optionally add Cloudflare access rules. Exempt HTTPS renewal challenges; avoid interactive login challenges on API and checkout. Proxy mode alone is not an IP restriction.

Locked out? Run whollycrypto access-reset --domain merchant.example.com over SSH. Only that hostname reopens, within five seconds; account authentication stays enabled.

Run whollycrypto ssl --domain merchant.example.com --reissue for a forced replacement. Issuance limits apply. If Cloudflare blocks the HTTP challenge, temporarily use DNS-only. Wallets, authentication and domains stay unchanged.

Older updater blocked? Run this once. Your installed key verifies the helper.

bash <(curl -fsSL https://releases.whollycrypto.com/update_wholly.sh)

Setup and updates automatically try the official GitHub mirror. Signature, checksum and credit checks remain required.

Checks are read-only, with a non-zero exit when attention is needed. --fix only repairs managed permissions and a missing CLI link. It never changes billing, deletes data or restarts services.

whollycrypto reset
# Preview without changing anything:
whollycrypto reset --scope business --check
whollycrypto reset --scope project --project YOUR_PROJECT_IDENTIFIER --check

Choose one project, all business projects, or repair only. Project resets permanently erase the selected projects, stores, wallet records and payment history. Repair only checks and fixes managed permissions and the CLI link.

Disable selected projects, resolve open payments/transfers and move known wallet balances first. Accounts, domains, nodes, credits, billing identity and installation mode stay. Operator receiving wallets and hosted credit records are protected. This does not reopen the setup wizard.

A destructive reset requires a typed confirmation and creates a verified recovery backup before erasure. Keep an off-server wallet backup too: old addresses can still receive funds, but deleted projects stop tracking them. Cached balances do not prove wallets are empty.

whollycrypto uninstall --check
whollycrypto uninstall

Stops checkout, API and workers; removes runtime files and managed server integration after backup and typed confirmation. Pending payments or transfers block removal. Files move into the recovery backup rather than being wiped.

Database, configuration, keys and backups remain. Shared Nginx/PostgreSQL packages and TLS certificates are untouched. The command prints an offline recovery command; do not run fresh setup over retained data.

Reset/removal commands are for native VPS installs, not Docker or Umbrel. For containers, use your integration’s backup and stop commands; keep the volumes. Neither destructive command accepts --yes.

whollycrypto htaccess

Select a user, choose a name/password and confirm. This resets the browser's first login prompt, not your console account. Other users and API credentials stay unchanged.

whollycrypto admin-reset

Choose an admin by email and confirm the new password. Sessions and account login locks are cleared; IP restrictions remain.

Normal resets keep 2FA. If both authenticator and recovery codes are lost, explicitly run whollycrypto admin-reset --email admin@example.com --reset-2fa. Set up 2FA again after login.

Needs the database, not the app or old password. Other accounts, wallets and permissions stay unchanged; disabled accounts stay disabled.

Lost both authenticator and recovery codes? Choose an account as root.

whollycrypto 2fa-reset
# Or select the account directly:
whollycrypto 2fa-reset --email user@example.com

Removes sessions, authenticator and recovery codes. Log in with the existing password and configure 2FA again. Permissions, wallets and Basic Auth stay unchanged; disabled accounts stay disabled.

Requires the database, not the app or credits. Non-interactive: --email and --yes.

Enter generates a password in /root/whollycrypto/config/credential-resets/: private, unencrypted, usable after success. Manually entered passwords aren't saved.

whollycrypto htaccess --user admin --new-user operator
whollycrypto admin-reset --email admin@example.com

Without a terminal, specify the existing account plus --generate or --password-file /root/private-password.txt, and --yes. Password files must be root-owned, mode 600. Never put passwords in commands or environment variables.

--yes skips confirmation only. Finish interrupted-update recovery first; concurrent account changes stop resets.