Wallet API webhooks

We watch every address you create and tell you when money arrives. Set a webhook URL once under Dashboard → Webhooks, and it’s used for checkout, off-ramp, onramp, and the Wallet API.

wallet.deposit.received

Sent once for every deposit to a wallet you created. It’s signed like every other Minisend webhook, with the X-Minisend-Signature header and your webhook_secret. See webhook verification.

{
  "event": "wallet.deposit.received",
  "deposit_id": "7b2e1a3f-...",
  "wallet_id": "3f6b2e1a-...",
  "wallet_ref": "user-9214",
  "address": "0xabc1230000000000000000000000000000dead",
  "chain": "MATIC",
  "token": "USDC",
  "amount": "10.500000",
  "tx_hash": "0x55a572efe1720250e442f38741477a4fc3f7f152e5cd208cc52f8222a1c2a13b",
  "from_address": "0x9f2c...",
  "state": "confirmed",
  "detected_at": "2026-08-07T09:12:03.000Z",
  "created_at": "2026-08-07T09:12:03.000Z"
}

string

required

Use this to spot repeats. If we send an update for the same deposit later, it has the same deposit_id.

string

required

Your own ID for the wallet, exactly as you sent it when you created the address.

string

required

The network the money actually arrived on. An address is the same on every network, so a wallet you created on Base can also receive on Polygon, Arbitrum, or any other supported network. Always check this field rather than assuming it’s the network you created the wallet on.

string

required

Text, not a number. Store and compare it as an exact decimal, not a floating-point number, so you don’t lose precision.

string

The blockchain transaction ID. It can be null for a moment in the very first message about a deposit.

string

required

confirmed or complete. You might get confirmed first and complete a moment later for the same deposit_id. Both mean the money has arrived.

A transfer between two of your own users doesn’t send wallet.deposit.received for the receiving address. It’s reported as wallet.transfer.completed instead, so if you counted both, you’d count the money twice.

You can also look up deposits through the API instead of waiting for a webhook. See get wallet deposits and list all deposits. They’re useful for catching up after your server was down, or if you’d rather check yourself.

wallet.withdrawal.completed and wallet.withdrawal.failed

Sent when a withdrawal you asked for with POST /api/v1/withdrawals, or a recovery with POST /api/v1/recover, is finished.

{
  "event": "wallet.withdrawal.completed",
  "withdrawal_id": "9f2c4e1a-...",
  "source": "master",
  "chain": "BASE",
  "token": "USDC",
  "amount": "50.000000",
  "destination_address": "0x9f2c000000000000000000000000000000dead",
  "tx_hash": "0x55a572efe1720250e442f38741477a4fc3f7f152e5cd208cc52f8222a1c2a13b",
  "state": "completed"
}

string

"master" if the money came from your master wallet. Otherwise, the wallet_ref of the address it came from.

string

The blockchain transaction ID. null on wallet.withdrawal.failed, because nothing was sent.

string

required

completed or failed.

This message doesn’t say why a withdrawal failed. You’ll find that in your dashboard. You can also check get a withdrawal instead of, or as well as, waiting for this webhook.

wallet.transfer.completed and wallet.transfer.failed

Sent when a transfer between two of your users is finished.

{
  "event": "wallet.transfer.completed",
  "transfer_id": "8f21c3d0-...",
  "from": "user-42",
  "to": "user-7",
  "chain": "BASE",
  "token": "USDC",
  "amount": "12.500000",
  "tx_hash": "0x9b3e51c7a2d84f06e1b9c3a7d5f2e8b4c6a0d1f3e5b7c9a2d4f6e8b0c1a3d5f7",
  "state": "completed"
}

string

required

Use it together with event to spot repeats.

string

required

The walletRef that paid.

string

required

The walletRef that received the money. Credit them when you get this event.

string

The blockchain transaction ID. null on wallet.transfer.failed, because nothing was sent.

wallet.transfer.failed means nothing moved, and the money is still at the from address. In the rare case we can’t tell for sure what happened, we don’t send wallet.transfer.failed, because the money may have moved. Get a transfer shows it as under_review while we check.

wallet.deposit.settled

Sent when a deposit has finished moving under your settlement setting. It’s now USDC, at your user’s own address, on your settlement network.

{
  "event": "wallet.deposit.settled",
  "deposit_id": "7b2e1a3f-...",
  "wallet_id": "3f6b2e1a-...",
  "wallet_ref": "user-9214",
  "address": "0xabc1230000000000000000000000000000dead",
  "source_chain": "ETH",
  "source_token": "USDT",
  "source_amount": "100.000000",
  "settlement_chain": "MATIC",
  "token": "USDC",
  "amount_settled": "99.410000",
  "tx_hash": "0x55a572efe1720250e442f38741477a4fc3f7f152e5cd208cc52f8222a1c2a13b",
  "settled_at": "2026-09-28T09:14:03.000Z"
}

string

required

The network the original deposit arrived on.

string

required

How much the deposit was, in source_token, before converting.

string

required

What arrived on settlement_chain. Usually a little less than source_amount, because converting and moving money between networks both cost something. Your business covers that cost, not your user’s recorded deposit.

wallet.deposit.settlement_failed

Sent when we couldn’t move a deposit under your settlement setting.

{
  "event": "wallet.deposit.settlement_failed",
  "deposit_id": "7b2e1a3f-...",
  "wallet_id": "3f6b2e1a-...",
  "wallet_ref": "user-9214",
  "address": "0xabc1230000000000000000000000000000dead",
  "source_chain": "ETH",
  "source_token": "USDT",
  "source_amount": "100.000000",
  "settlement_chain": "MATIC",
  "funds_location": "source_chain",
  "funds_chain": "ETH",
  "funds_token": "USDT",
  "message": "Could not be settled. The funds are safe at the user's address on Ethereum, as USDT."
}

string

required

Where the money is now. source_chain: safe at the user’s address on the network where it arrived. base: safe at the user’s address on Base, as USDC. under_review: we’re still confirming where it is. That doesn’t mean it’s unsafe, only that we won’t say until we’re sure.

string

Set for source_chain and base. null for under_review.

string

required

A sentence you can show as it is, based on funds_location. It’s the same wording as the deposit’s settlement.error field.

There’s no separate “delayed” event. A settlement that’s taking longer than usual is still moving and can still finish by itself. It shows as delayed on the deposit’s settlement field, and we never report it as failed while that’s the case.

Get Started

Dashboard

Payments

Off-ramp API

Onramp API

Wallet API

Webhooks

Help

Wallet API webhooks

wallet.deposit.received

wallet.withdrawal.completed and wallet.withdrawal.failed

wallet.transfer.completed and wallet.transfer.failed

wallet.deposit.settled

wallet.deposit.settlement_failed

​wallet.deposit.received

​wallet.withdrawal.completed and wallet.withdrawal.failed

​wallet.transfer.completed and wallet.transfer.failed

​wallet.deposit.settled

​wallet.deposit.settlement_failed

wallet.deposit.received

wallet.withdrawal.completed and wallet.withdrawal.failed

wallet.transfer.completed and wallet.transfer.failed

wallet.deposit.settled

wallet.deposit.settlement_failed