> ## Documentation Index
> Fetch the complete documentation index at: https://docs.komerza.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Self-Custody Setup

> Receive crypto payments directly into wallets you control — zero fees, no third party ever holds your funds

**Komerza Self-Custody** settles crypto payments straight into wallets you own. Komerza only watches your addresses to confirm payments and mark orders as paid — it never holds, moves, or has access to your funds.

It sits alongside the processor options (NOWPayments, Heleket) on the Cryptocurrency page, but works differently:

* **Zero fees** — keep 100% of every crypto payment. Processors take a cut (NOWPayments 0.5–1%, Heleket 0.4%); self-custody takes nothing.
* **You hold the keys** — payments settle to a wallet you control; funds never touch Komerza.
* **No extra accounts** — just link a wallet address or `xpub`/`zpub`. No third-party signup or API keys.

You link a wallet **per chain**, in one of two ways depending on the chain:

| Chain           | Link method   |
| --------------- | ------------- |
| Solana (SOL)    | WalletConnect |
| Ethereum (ETH)  | WalletConnect |
| BNB Chain (BNB) | WalletConnect |
| Polygon (POL)   | WalletConnect |
| Bitcoin (BTC)   | Account xpub  |
| Litecoin (LTC)  | Account xpub  |
| Dogecoin (DOGE) | Account xpub  |

* **WalletConnect chains** — connect a wallet and Komerza reads a **deposit address** to watch.
* **xpub chains** — paste an **account xpub** and Komerza derives a fresh receiving address for every payment, so your private keys never leave your wallet.

## Prerequisites

* A store on the **Business plan** — Self-Custody is a Business-tier feature.
* A wallet for each chain you want to accept. WalletConnect chains work with almost any wallet; xpub chains need a wallet that can **export an account xpub** (see [Which wallets can export an xpub](#which-wallets-can-export-an-xpub)).

## Open Komerza Self-Custody

<Steps>
  <Step title="Go to Cryptocurrency settings">
    In your dashboard, open **Settings** under **Online Store**, then go to **Cryptocurrency**. Under **Processors**, find the **Komerza Self-Custody** card.

    <img className="block dark:hidden rounded-lg border border-gray-200 dark:border-gray-800" src="https://mintlify.s3.us-west-1.amazonaws.com/komerza/images/self-custody/1-light.png" alt="Komerza Self-Custody card on the Cryptocurrency settings page" />

    <img className="hidden dark:block rounded-lg border border-gray-200 dark:border-gray-800" src="https://mintlify.s3.us-west-1.amazonaws.com/komerza/images/self-custody/1-dark.png" alt="Komerza Self-Custody card on the Cryptocurrency settings page" />

    <Note>
      If you don't see Self-Custody, confirm your store is on the **Business plan**.
    </Note>
  </Step>

  <Step title="Click Link Wallet">
    On the Komerza Self-Custody card, click **Link Wallet**. The **Link a receiving wallet** dialog opens.

    <img className="block dark:hidden rounded-lg border border-gray-200 dark:border-gray-800" src="https://mintlify.s3.us-west-1.amazonaws.com/komerza/images/self-custody/2-light.png" alt="Link a receiving wallet dialog with chain selector" />

    <img className="hidden dark:block rounded-lg border border-gray-200 dark:border-gray-800" src="https://mintlify.s3.us-west-1.amazonaws.com/komerza/images/self-custody/2-dark.png" alt="Link a receiving wallet dialog with chain selector" />

    Pick the **Chain** you want to set up. The dialog then shows either a **Connect Wallet** button or a **Link via account xpub** option, depending on the chain. Follow the matching section below, and repeat the whole process for each currency you want to accept.
  </Step>
</Steps>

## Path A — WalletConnect chains (SOL, ETH, BNB, Polygon)

These chains are the quick path. You click **Connect Wallet** to link a wallet with WalletConnect, and Komerza reads the deposit address to watch.

<Steps>
  <Step title="Select the chain and Connect Wallet">
    In **Link a receiving wallet**, choose the chain (e.g. Ethereum) and click **Connect Wallet**. A WalletConnect QR code and connection link appear.

    <img className="block dark:hidden rounded-lg border border-gray-200 dark:border-gray-800" src="https://mintlify.s3.us-west-1.amazonaws.com/komerza/images/self-custody/3-light.png" alt="WalletConnect connection screen" />

    <img className="hidden dark:block rounded-lg border border-gray-200 dark:border-gray-800" src="https://mintlify.s3.us-west-1.amazonaws.com/komerza/images/self-custody/3-dark.png" alt="WalletConnect connection screen" />
  </Step>

  <Step title="Approve in your wallet">
    Open your wallet and connect:

    * **On mobile** — tap the connection link (or scan the QR from another device) to open your wallet app, then approve.
    * **On desktop** — scan the QR code with your mobile wallet, or use a browser-extension wallet.

    Approve the connection request. Komerza records the wallet's address for that chain and starts watching it.
  </Step>

  <Step title="Repeat for each chain">
    Wallets are linked **per chain**, so connect once for every currency you want to accept.

    <Note>
      **EVM chains (ETH, BNB, Polygon)** can all use the same wallet (MetaMask, Trust, Rabby, etc.) — you just run the connect step once per chain. **Solana (SOL)** needs a Solana wallet such as Phantom or Solflare.
    </Note>
  </Step>
</Steps>

## Path B — xpub chains (BTC, LTC, DOGE)

For these chains you paste an **account xpub** from your wallet. Komerza derives a fresh receiving address from it for each payment — your private keys never leave your wallet, and Komerza can only *watch*, never spend.

<Note>
  **Any format works.** Komerza auto-detects the derivation, so paste whatever extended public key your wallet gives you — `xpub`, `ypub`, or `zpub` for Bitcoin; `Ltub`/`Mtub` for Litecoin; `dgub` for Dogecoin. You don't need to convert it.
</Note>

<Steps>
  <Step title="Export the xpub from your wallet">
    Find and copy your wallet's account xpub. Steps vary by wallet — see [Export your xpub by wallet](#export-your-xpub-by-wallet) below.

    <Warning>
      Only ever paste an **account xpub** (`xpub`/`ypub`/`zpub`/…). **Never** paste your seed phrase or private key — Komerza never needs them, and no legitimate service ever will.
    </Warning>
  </Step>

  <Step title="Paste it into Komerza">
    In **Link a receiving wallet**, select the chain, choose **Link via account xpub**, and paste your key into the **Account xpub** field. Komerza confirms it will derive a fresh receiving address per payment.

    <img className="block dark:hidden rounded-lg border border-gray-200 dark:border-gray-800" src="https://mintlify.s3.us-west-1.amazonaws.com/komerza/images/self-custody/4-light.png" alt="Link via account xpub — Account xpub field" />

    <img className="hidden dark:block rounded-lg border border-gray-200 dark:border-gray-800" src="https://mintlify.s3.us-west-1.amazonaws.com/komerza/images/self-custody/4-dark.png" alt="Link via account xpub — Account xpub field" />

    <Warning>
      Double-check the chain and key before saving. Payments are sent on-chain and **cannot be reversed** — an xpub pasted under the wrong chain sends funds somewhere you may not control.
    </Warning>
  </Step>

  <Step title="Verify with a test payment">
    We strongly recommend a small test order (for example a **\$1** purchase) to confirm the payment is detected and the order is marked as paid before you go live.
  </Step>
</Steps>

### Export your xpub by wallet

<AccordionGroup>
  <Accordion title="Electrum (Bitcoin) / Electrum-LTC (Litecoin)" icon="desktop">
    1. Open Electrum with the wallet loaded.
    2. Go to **Wallet → Information**.
    3. Copy the **Master Public Key** shown — for a default Electrum wallet this starts with `zpub`. That's your account xpub; paste it into Komerza as-is.

    <Note>Electrum is the most reliable option for Litecoin. For Dogecoin, use **Trezor Suite** below — the Dogecoin Electrum fork is poorly maintained.</Note>
  </Accordion>

  <Accordion title="Sparrow Wallet (Bitcoin)" icon="desktop">
    1. Open your wallet in Sparrow.
    2. In the left sidebar, click **Settings**.
    3. In the **Keystore** section, the extended public key is shown — you can toggle the format (e.g. **XPUB / ZPUB**). Copy it.
    4. Paste it into Komerza.
  </Accordion>

  <Accordion title="Trezor Suite (Bitcoin, Litecoin, Dogecoin)" icon="wallet">
    Trezor supports all three UTXO chains, which makes it a good single option.

    1. Connect your Trezor and open **Trezor Suite**.
    2. Select the coin account (**Bitcoin**, **Litecoin**, or **Dogecoin**) in the left sidebar.
    3. Open the **Details** tab and click **Show public key**.
    4. Verify the key **on your Trezor device**, then copy it and paste it into Komerza.
  </Accordion>

  <Accordion title="BlueWallet (Bitcoin, mobile)" icon="mobile">
    1. Open the wallet and tap the **••• (top right)** to open **Wallet Settings**.
    2. Tap **Show Wallet XPUB**.
    3. The xpub appears as a QR code and text — tap the text to copy it.
    4. Paste it into Komerza.

    <Note>BlueWallet is Bitcoin-only — use another wallet from this list for Litecoin or Dogecoin.</Note>
  </Accordion>

  <Accordion title="Exodus (desktop only)" icon="desktop">
    Exodus can export an xpub from its **desktop** app only — the mobile app doesn't expose it.

    1. Open the **Exodus desktop** app and select the asset (e.g. Bitcoin).
    2. Click the **••• (three dots)** at the top right.
    3. Click **Export XPub**. Exodus saves a `.txt` file in an **`exodus-exports`** folder and shows you where — for example `…/exodus-exports/exodus_0-bitcoin-xpub.txt`.
    4. Open that file. It lists several keys — a legacy `xpub` (starts with `xpub…`) followed by one or more native-segwit keys (start with `zpub…`).
    5. Copy the **`zpub`** line — it's the newer native-segwit format and matches the addresses Exodus actually receives to. Paste it into Komerza.

    <Note>On mobile, use the desktop app instead, or another wallet from this list.</Note>
  </Accordion>

  <Accordion title="Ledger (Ledger Live)" icon="wallet">
    Ledger Live shows the xpub for UTXO coins — **Bitcoin, Litecoin, Dogecoin**.

    1. Open **Ledger Live** and connect your device.
    2. Go to **Accounts** and select the coin account (e.g. Bitcoin).
    3. Click the **tool/wrench icon** at the top right of the account.
    4. Open **Advanced Logs** and copy the value that starts with `xpub`.

    <Note>Ledger Live shows one **generic `xpub`** for the account regardless of address type (Legacy / SegWit / Native SegWit) — Komerza accepts it as-is.</Note>
  </Accordion>
</AccordionGroup>

### Which wallets can export an xpub

<Warning>
  These popular wallets **cannot** export an xpub, so they can't be used for the xpub chains: **Trust Wallet**, **Coinbase Wallet**, and **MetaMask** (MetaMask is EVM-only and doesn't support these chains anyway). **Exodus** works too, but from its **desktop app only** — the mobile app can't export an xpub. If your wallet can't, move the relevant coins to a wallet from the list above — such as **Electrum**, **Sparrow**, **Trezor Suite**, or **BlueWallet**.
</Warning>

## Route your coins to self-custody

Linking a wallet tells Komerza *where* to settle — but each coin also needs to be **routed** to the Komerza Self-Custody processor. On the Cryptocurrency page, open **Coin routing** and set each coin you want to self-custody to **Komerza Self-Custody**, or confirm default routing already points there.

<Note>
  If a coin is routed to a processor (NOWPayments or Heleket) instead of Komerza Self-Custody, payments for that coin settle to the processor and incur its fee — even if you've linked a self-custody wallet for the same chain.
</Note>

## How payments settle

1. A customer chooses one of your self-custody currencies at checkout.
2. Komerza shows them a receiving address:
   * For **WalletConnect chains**, your linked deposit address.
   * For **xpub chains**, a fresh address derived from your xpub for that order.
3. The customer pays. Funds land **directly in your wallet** — Komerza never touches them.
4. Komerza detects the on-chain payment and marks the order as paid, triggering delivery.

## Troubleshooting

| Problem                         | Fix                                                                                                                                                                                                      |
| ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Self-Custody option not visible | Confirm your store is on the **Business plan**.                                                                                                                                                          |
| Coin still charging a fee       | Check **Coin routing** — the coin is likely routed to NOWPayments or Heleket. Set it to **Komerza Self-Custody**.                                                                                        |
| xpub rejected when pasting      | Make sure you copied the full **account xpub** (not a single address, seed phrase, or private key). Any format — `xpub`/`ypub`/`zpub`/`Ltub`/`dgub` — is accepted; copy the whole string with no spaces. |
| Test payment not detected       | Give the network a few confirmations, and double-check you paid the correct chain. For xpub chains, confirm the xpub belongs to the wallet you're watching for the payment.                              |
| Wallet can't export an xpub     | Your wallet isn't supported for that chain — move the coins to a wallet from [the supported list](#export-your-xpub-by-wallet).                                                                          |
| WalletConnect won't connect     | Refresh the dialog to generate a new QR/link, make sure your wallet is on the same chain you're linking, and update your wallet app if the session times out.                                            |