Request a withdrawal

Sends money from your master wallet, or from one of your users’ addresses, to an address outside Minisend.

Call this from your server only, never from a browser or app, so your API key stays secret.

Before you can withdraw, the address you’re sending to has to be on your approved list. You add it in Dashboard → Wallets → Settings, and it can’t be done with an API key. That’s on purpose: if a key could approve an address and also send to it, anyone who got hold of the key could empty your balance.

Endpoint

POST https://merchant.minisend.xyz/api/v1/withdrawals

Authorization: Bearer wsk_live_your_key_here

The key needs the withdraw permission (scope). It’s off on every key to start with, including older keys, so turn it on only for a key that should be able to send money out.

Body

string

required

"master" to withdraw from your master wallet, or the walletRef of the address to withdraw from.

string

required

The network to send on.

string

required

USDC or USDT.

number

required

A positive amount of the coin. If it has more decimal places than the coin allows, we refuse it rather than round it, because rounding could send more than you meant to.

string

required

Has to be on your approved list already.

string

Any text unique to this withdrawal. If you send the same key with the same request again, you get the original withdrawal back instead of a second one. Sending it with a different source, chain, token, amount, or destination_address is refused with 409.

Example

curl -X POST https://merchant.minisend.xyz/api/v1/withdrawals \
  -H "Authorization: Bearer wsk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "source": "master",
    "chain": "BASE",
    "token": "USDC",
    "amount": 50,
    "destination_address": "0x9f2c000000000000000000000000000000dead"
  }'

Response (202)

{
  "withdrawal": {
    "id": "9f2c4e1a-...",
    "state": "queued",
    "source": "master",
    "chain": "BASE",
    "token": "USDC",
    "amount": "50.000000",
    "destination_address": "0x9f2c000000000000000000000000000000dead",
    "tx_hash": null,
    "created_at": "2026-09-28T09:00:00.000Z",
    "updated_at": "2026-09-28T09:00:00.000Z"
  }
}

You get 202, not 200, because we’ve accepted the withdrawal and send it shortly after. Check get a withdrawal or wait for wallet.withdrawal.completed to see how it went. If you send an idempotency_key you’ve used before, you get 200 with the original withdrawal.

string

required

queued, sending, completed, or failed.

string

What you sent: "master", or the walletRef the money came from.

string

The blockchain transaction ID, once sent. null until then, and when failed.

Listing your withdrawals

GET https://merchant.minisend.xyz/api/v1/withdrawals

Needs a key with wallets:read.

number

default:"20"

How many to return at once, up to 100.

number

default:"0"

How many to skip. Use it to get the next page.

{
  "withdrawals": [ { "id": "9f2c4e1a-...", "state": "completed", "...": "..." } ],
  "total": 12,
  "limit": 20,
  "offset": 0
}

Each one has the same fields as the response above.

Errors

Status	Meaning
`400`	Something isn’t right: the request fields, an amount below the network’s minimum, more than you have available, or the address is one of your own
`401`	Your API key is missing or wrong
`403`	The address isn’t on your approved list yet
`404`	You don’t have a wallet on that network, or there’s no address with that `walletRef`
`409`	The `idempotency_key` was already used for a different request, or this withdrawal was already sent
`429`	Too many requests. Wait a moment and try again
`503`	We couldn’t check your balance or send the withdrawal just now. Try again

Overview

Endpoints

Off-ramp endpoints

Onramp endpoints

Wallet API endpoints

Request a withdrawal

Endpoint

Body

Example

Response (202)

Listing your withdrawals

Errors

​Endpoint

​Body

​Example

​Response (202)

​Listing your withdrawals

​Errors

Endpoint

Body

Example

Response (202)

Listing your withdrawals

Errors