Skip to main content

Monero wallet setup

XMR Stagenet XMR Mainnet supported

Before you start​

  • A Manatee Test API key
  • The official Monero CLI or GUI
  • A synchronized Stagenet daemon or remote Stagenet node
  • A public HTTPS webhook URL
important

Manatee needs the primary address and private view key. Never submit the mnemonic seed, private spend key, or wallet password. The view key cannot spend XMR, but it reveals incoming amounts and wallet activity.

What you'll do​

Create a dedicated Stagenet wallet, configure its view-only data, wait for synchronization, create a unique-subaddress payment, and verify pending → detected → confirmed.

Step 1 — Start Monero on Stagenet​

monerod --stagenet --prune-blockchain

Wait until the daemon is synchronized before testing payment detection.

Expected result
The local height matches the Stagenet network height.

Step 2 — Create a dedicated wallet​

monero-wallet-cli --stagenet --generate-new-wallet manatee-stagenet

Back up the seed offline. In the wallet, run:

address
viewkey
height

Record the primary address, private view key, and a restore height just before the wallet was created.

Step 3 — Configure XMR in the dashboard​

Open Dashboard → Wallets → Test → Monero. Enter the primary Stagenet address, private view key, and restore height. The view key is write-only in the dashboard and encrypted at rest.

note

Manatee allocates a fresh subaddress for every payment. The XMR payment endpoint never accepts a manually supplied destination address or integrated address.

Expected result
Provisioning becomes ready and wallet synchronization reaches synced before payment creation.

Step 4 — Create a test payment​

curl https://api.manatee-api.io/v1/xmr/payments \
  -H "Authorization: Bearer <TEST_API_KEY>" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1042-xmr" \
  -d '{
    "amount_atomic": "25000000000",
    "reference": "order-1042",
    "webhook_url": "https://shop.example/webhooks/manatee",
    "confirmations_required": 10
  }'

amount_atomic is a decimal string in piconero; 1 XMR equals 1,000,000,000,000 piconero.

Expected result
The response reports asset: "xmr", network: "stagenet", atomic_unit: "piconero", and a unique subaddress.

Step 5 — Verify the synthetic webhook​

Send an XMR test event and verify its timestamp and HMAC signature against the raw body. Confirm your parser preserves amount_atomic and received_atomic as decimal strings.

Step 6 — Complete a Stagenet transfer​

Send the exact amount to the returned subaddress. A transfer may be detected before it is unlocked; wait for the configured confirmations before fulfillment.

Expected result
Your application handles detected and confirmed as separate states and processes each event ID once.

Failure and recovery​

  • Provisioning failed: confirm the primary address and private view key belong to the same wallet and network.
  • Synchronization remains pending: verify daemon health and lower the restore height if it starts after the wallet's first activity.
  • Payment not detected: confirm exact piconero amount, subaddress, scanner height, and transaction unlock state.
  • Lost webhook: query GET /v1/xmr/payments/{id}; API state is authoritative.
  • Exposed view key: rotate to a new dedicated wallet because historical incoming activity may be visible.

Step 7 — Prepare Mainnet​

Create a separate Mainnet wallet, use a dedicated Mainnet API key, and repeat the address/view-key match and restore-height checks. Never copy a Stagenet address into Mainnet configuration.

Next steps
Complete Going to production, review Security, and define a reconciliation process before accepting real XMR.
Last updated on