Request a withdrawal

Moves a balance from your master wallet, or from one of your users’ addresses, out to an external destination.

Backend only. Never call from frontend.

Before you can withdraw, the destination address needs to be on your approved list, added from Dashboard → Wallets → Settings. This can’t be done with an API key: a key that could both withdraw and approve its own destination would be able to empty a balance on its own.

Endpoint

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

Authorization: Bearer wsk_live_your_key_here

Requires the withdraw scope. This scope defaults off on every key, including keys created before scopes existed — turn it on explicitly for a key that should be able to move money.

Body

string

required

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

string

required

The chain to withdraw on.

string

required

USDC or USDT.

number

required

A positive number, in the token’s units. Refused, not rounded, if it carries more decimal places than the token supports — rounding could silently send more than you asked for.

string

required

Must already be on your approved destinations list for this account.

string

Reusing the same key with the same request returns the original withdrawal instead of creating a second one. Reusing 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"
  }
}

202, not 200: the withdrawal is accepted and queued, and the transfer itself happens shortly after. Poll get a withdrawal or listen for wallet.withdrawal.completed to learn the outcome. Replaying an idempotency_key returns 200 with the original withdrawal instead.

string

required

queued, sending, completed, or failed.

string

Echoes what you sent: "master", or the walletRef you withdrew from.

string

The on-chain transaction, once sent. null until then, and while failed.

Listing your withdrawals

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

Needs wallets:read.

number

default:"20"

Page size, max 100.

number

default:"0"

Rows to skip.

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

Each entry is the same shape as the response above.

Errors

Status	Meaning
`400`	Invalid body, amount below the chain’s minimum, amount above your available balance, or the destination is one of your own addresses
`401`	Missing or invalid API key
`403`	The destination isn’t on your approved list yet
`404`	No active wallet for that chain, or no address with that reference
`409`	The `idempotency_key` was already used with a different request, or that withdrawal was already submitted
`429`	Rate limit exceeded
`503`	Could not check your balance or submit the withdrawal right now. Retry

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