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.

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. Open Store → Payment methods, select a supported EVM chain or Solana, then choose Custom token beside the search.
2. Enter the contract or mint, name and ticker. Choose a fixed USD price or automatic DEX pricing.

The chain and decimals are checked. Prices are shared across the project's stores; existing invoices keep their original quote. A catalog match alone does not make a token ready for checkout.

Automatic pricing

DEX Screener finds exact-contract pools, including Uniswap and PancakeSwap. A pool needs at least $10,000 liquidity and a trade within the last hour. Rates refresh every minute; failed checks or prices older than five minutes block new quotes.

DEX prices can be manipulated. Use trusted standard ERC-20 or classic SPL tokens; verification is not a security audit. Token-2022/extensions are not supported. Use a fixed price if no suitable pool exists.

Invoice cannot be created? Check the chain's scanner badge, not just node health. TRON needs two independent tron-indexer providers. The invoice form lists unavailable methods and fixes; Wallets separates receiving checks from balances and sending gas.

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.

Events: invoice.created, payment.received, invoice.processing, invoice.settled, invoice.expired, invoice.invalid, invoice.cancelled. Not every invoice passes through every state. Version 2 includes signed event_type, event_id and project/store IDs.

The body contains invoice_id (public UUID), status, amount_status, timing_status, resolution, sequence, amount, currency and order_id. Amounts are decimal strings: a €49.90 invoice paid in USDC still sends "amount": "49.9", "currency": "EUR".

Underpaid: amount_status = partial. Overpaid: overpaid. Late: timing_status = late. These are separate from invoice status. paid includes tolerance.

payment_info has exact amounts, transfers and chain/token identities. Customer data and metadata are also included privately.

Settlement identifies paid_chain, paid_asset, paid_payment_method_id and settlement_exchange_rate (asset units per invoice currency unit, before spread). Unproven settlements and unknown historical data stay null. Retries preserve the snapshot.

5.0.1 adds paid_asset_amount (full crypto quote) and paid_asset_amount_received (actual receipts at settlement). Exact decimal strings preserve tolerated shortfalls: "100" requested, "99" received. They stay frozen; older snapshots return null. Later receipts appear in payment_info.

Missing is not unconfirmed. remaining_amount accounts for tolerance. Never resend unconfirmed funds or combine different assets. Preserve exact decimal/atomic strings.

Quote, spread, tolerance and rounding stay locked. Market snapshots are advisory. For truncated histories, use the paginated payments API.

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 the raw body and timestamp, match project/store scope, save durably, then return HTTP 2xx. Re-fetch the invoice from your configured API host and match your order before fulfilment. Event/delivery headers are unsigned; version 2 also puts the event identity inside the signed body.

For an order-state inbox, deduplicate by project, invoice ID and sequence. Different event types may share a revision: compare the original invoice-state fields, not whole JSON bodies. If processing every event, use the signed event ID and still fulfil each order only once.

IPN retries retryable failures up to eight times; webhooks can disable retries. Delivery may be delayed, duplicated or out of order. Never overwrite a newer invoice revision with an older one.

Search Store → IPN / Webhooks → History by order, invoice ID or email. Details shows the saved body and delivery result. Histories also appear in invoice details.

data.invoice_id matches callbacks. SDK 2.1.0 supports version 2 and legacy events; update strict receivers. Saved payloads expire after 90 days. Resend is not proof of success. Low credits pause deliveries, not payments.

1. In Settings → Exchanges, connect a dedicated API key, check balances and grant projects. Enable spot trading only if needed. No withdrawal permissions; restrict keys to your VPS IP.
2. In Project → Sweep, verify the asset, deposit network and address. Token routes may require explicit contract confirmation.
3. For each chain/token, choose either another wallet or one exchange. Select a direct market or keep the coin. Test a small transfer first.

Markets refresh about every two minutes. Stale markets block conversion. Only matched, credited deposits are used; uncertain orders are checked, never blindly resubmitted. A 1% source reserve stays at the exchange for fees and rounding, separate from processing credits.

Exchange custody, KYC, regional limits and trading/network fees apply. No multi-hop trades, leverage or bank withdrawals. Insufficient processing credit pauses new conversions, but submitted orders continue to be checked.

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.

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

Checks query authoritative DNS and verify the origin; results show Direct or Cloudflare. Visitors may temporarily cache older DNS.

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 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.