Connect self-hosted Monero

What you need

Field	What it does
Mint endpoint URL	Your server's public address-minting route. We call it to get a fresh address for each order. Not secret.
Webhook secret	A shared secret your server signs with and we verify. It can never touch your wallet. Secret.

This option is for people who want to take Monero on their own. You run a few small programs on your own computer: the Monero wallet app, a wallet helper, a ready-made server, and a public address tool. This guide walks through all of it on a Mac. If you would rather not run anything, connect a hosted crypto service instead.

Why we ask for each field

Mint endpoint URL

When a buyer clicks Buy, we ask your server for a fresh address to show them. That request goes to this one public route. It hands back an address and nothing else; your wallet stays private behind it.

Webhook secret

Your server tells us "this order is paid" by sending us a signed message. This shared secret lets us confirm the message really came from your server, so nobody can forge a paid event. It can read nothing and move nothing.

Set up

Get the Monero app and the tools
Three free downloads from getmonero.org and nodejs.org. Get all three now.
1. The Monero wallet app (the GUI wallet). This is where you make your wallet.
2. The Monero command-line tools (the CLI wallet). This holds the wallet helper you start later. Unzip it, rename the folder to monero-tools, and move it to your Desktop.
3. Node.js (the green LTS button at nodejs.org). This runs the small server that hands out addresses.
Download the wallet app
Download the command-line tools
The first time you run the command-line tools, your Mac may block them because it does not know the maker. Step 6 shows how to allow them.
Open the app and pick Simple mode
Open the Monero app. On the Mode selection screen choose Simple mode and leave Portable mode unchecked. Then it explains Simple mode and asks you to agree.
1. Open the app and continue past the welcome screen.
2. Choose Simple mode and continue.
3. Check the box that says you understand a third-party server is used, then click Next.
Open the Monero app
Mode selection, choose Simple mode
Check the box and click Next
Simple mode borrows a public Monero computer so you do not download the whole blockchain. Your secret words never leave your machine.
Prefer to run your own node? (advanced)
To use no outside node at all, choose Advanced mode on this screen instead of Simple mode. Advanced mode runs your own node and downloads the full Monero history first, which takes a while. You also change one line when you start the wallet helper, shown in that step.
Make your wallet
On the Welcome screen choose Create a new wallet. Then name it, save your words, and set a password.
1. Choose Create a new wallet (the top choice).
2. Give it a name and note the folder path it shows. You need that path in step 6.
3. Write the 25 words on paper, in order, and keep them safe. They are the only key to your money.
4. Set a password and write it down too.
5. When the wallet opens, close it. The wallet helper in step 6 needs it closed.
Choose Create a new wallet
Name your wallet
Write down your 25 words
Set a wallet password
Your new wallet is ready
Make your secret code
One shared secret signs and verifies the paid message. Make it once with the command below, or click Generate when you add the provider in the dashboard. Either way, use the same value in both places, and keep it private.
```
openssl rand -hex 32
```
Make your project and copy the id
Sign in to the dashboard, make a project, and copy its project id. It starts with proj_. You use it when you start the server.
Copy your project id
Start the wallet helper
This program opens your wallet and answers the server. Run it in Terminal from your monero-tools folder. It asks for your wallet password, hidden, so the password never shows. Replace YOUR-WALLET-PATH with the path from step 3 (in Finder, right-click the wallet file and choose Copy as Pathname).
```
cd ~/Desktop/monero-tools
./monero-wallet-rpc \
  --wallet-file 'YOUR-WALLET-PATH' \
  --prompt-for-password \
  --rpc-bind-ip 127.0.0.1 --rpc-bind-port 18083 \
  --disable-rpc-login \
  --daemon-address nodes.hashvault.pro:18081 --untrusted-daemon
```
Mac may block it the first time
Privacy & Security, Allow Anyway
The wallet helper is running
If your Mac blocks it, open System Settings, Privacy & Security, click Allow Anyway, then run the command again and click Open. Leave this window open.
Using your own node instead of a public one?
If you chose Advanced mode, start your own node first, then point the wallet helper at it.
```
monerod --data-dir ~/.bitmonero --prune-blockchain --restricted-rpc
```
Then in the command above, swap --daemon-address nodes.hashvault.pro:18081 --untrusted-daemon for --daemon-address 127.0.0.1:18081 --trusted-daemon. For real money, keep your spend key on a separate offline machine and run a view-only wallet on the machine that faces the internet.
Download and start the server
A ready-made server hands out an address for each sale and watches for the money. You do not edit it. Run the lines below, then answer two questions: your project id and your secret code (the secret shows as stars).
```
mkdir ~/Desktop/coinmoebius-server
cd ~/Desktop/coinmoebius-server
curl -fsSL https://coinmoebius.com/tools/monero-server.mjs -o server.mjs
npm init -y
npm install @aquarian-metals/coin-moebius-monero @aquarian-metals/coin-moebius-server
node server.mjs
```
Get the ready-made server
It asks two questions, then runs
Put your server online
Your server needs a public web address so we can reach it. A free tool called ngrok makes one.
1. Make a free account at ngrok.com and download ngrok for Mac.
2. Add your authtoken (ngrok shows the exact line on its setup page).
3. Run the command below, then copy the https address it shows next to Forwarding.
```
./ngrok http 8787
```
Copy the ngrok Forwarding address
Connect in the dashboard
Add provider, choose Be your own provider, then Monero. Paste two things and save.
1. Mint endpoint URL: your ngrok address with /coin-moebius/monero/mint added to the end.
2. Webhook secret: the secret code from step 4.
Add provider, Be your own provider
Search and pick Monero
Paste the URL and the secret
When you save, we quietly check that we can reach your server. Your wallet helper, server, and ngrok all need to be running.

Add the buy button to your page

Make a product in the dashboard, then copy its buy button code onto your page. It is two pieces: one script line near the bottom of the page, and one button block where you want the button.

<script src="https://sdk.coinmoebius.com/latest/sdk.global.js" crossorigin="anonymous" defer></script>

<coin-moebius-buy
  project-id="proj_yourprojectid"
  product-id="your-product"
  amount="59.99"
  currency="USD"
  label="Buy now">
</coin-moebius-buy>

Take your first payment
There is no sandbox for a self-hosted setup, so a small real payment is the test. Keep all three windows running (wallet helper, server, ngrok).
1. Open your page, click Buy, and pick Monero. The window shows an address, a QR code, and the amount.
2. Send that exact amount of Monero from any wallet.
3. Wait for confirmations. Monero takes about twenty minutes to fully confirm, by design. The window keeps checking the whole time.
4. When it shows the payment is complete, your whole setup is working end to end.
The buy window shows the address
The payment is complete

After you connect

Your first real payment is the test, and the step above walks through it. Here is what to check while it settles. Keep all three windows running: the wallet helper, the server, and ngrok.

After you pay, the buy window keeps checking. A 404 on the status check means not confirmed yet, not an error.
Monero takes about twenty minutes to fully confirm, by design.
Open the Transactions tab in the dashboard. When the new row reaches succeeded, your whole setup is working end to end.

Troubleshooting

Checkout fails right away.

We could not reach your server. Make sure all three windows are running, and that the mint endpoint URL in the dashboard is your ngrok address with /coin-moebius/monero/mint on the end.

The wallet helper says no connection to daemon.

The public Monero node is busy. Open monero.fail, pick another node, put it after --daemon-address in the step 6 command, and start the wallet helper again.

The buyer paid but the order stays pending, and the status check shows 404.

That is normal while the payment confirms. A 404 here means not confirmed yet, not an error. It turns into paid once the payment reaches ten confirmations, about twenty minutes after it lands.

It still says pending after thirty minutes.

Either the server is not running, or its secret does not match. Confirm the server is up and that the secret you typed matches the webhook secret in the dashboard.

Good to know

Run it on a computer that stays on. The test runs on your own computer. For an everyday store, run the same parts on a computer that stays on all the time, with a fixed web address.

Downtime is cheap. The server catches up after an outage and reports the payments it missed. Nothing is lost, so a home computer is fine.

Keep a view-only wallet for real money. When you sell for real, keep your spend key on a separate offline machine and run a view-only wallet on the machine that faces the internet.

Rotating the secret. Make a new secret anytime, then use it in both the server and the dashboard.

Questions? Join our Discord

Monero