Recover a stray token

Moves a token we don’t price or settle off one of your addresses, to a destination you’ve already approved. Use it when something other than USDC or USDT lands on an address — there’s no automatic path for that, so it just sits there until you move it.

Backend only. Never call from frontend.

The whole balance of that token moves. There’s no partial amount: we hold no price for the token, so there’s nothing to reason about a partial figure with.

Endpoint

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

Authorization: Bearer wsk_live_your_key_here

Requires the withdraw scope, the same one withdrawals need — it moves money out, and it makes no difference that the token isn’t one we price.

Body

string

required

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

string

required

The chain the token is on.

string

required

The contract address of the token to recover. Refused if it’s the canonical USDC or USDT contract on that chain — use a withdrawal for those, which prices and floors them properly.

string

required

Must already be on your approved destinations list, the same list withdrawals use.

Example

curl -X POST https://merchant.minisend.xyz/api/v1/recover \
  -H "Authorization: Bearer wsk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "source": "user-9214",
    "chain": "BASE",
    "token_address": "0x1234000000000000000000000000000000abcd",
    "destination_address": "0x9f2c000000000000000000000000000000dead"
  }'

Response (202)

{
  "recovery": {
    "id": "7a1c2e3f-...",
    "state": "queued",
    "source": "user-9214",
    "chain": "BASE",
    "token": "0x1234000000000000000000000000000000abcd",
    "amount": "25.000000",
    "destination_address": "0x9f2c000000000000000000000000000000dead",
    "tx_hash": null,
    "created_at": "2026-09-28T09:00:00.000Z",
    "updated_at": "2026-09-28T09:00:00.000Z"
  }
}

Same shape and lifecycle as a withdrawal: 202, queued → sending → completed/failed. Track it with get a withdrawal or the wallet.withdrawal.completed webhook.

Errors

Status	Meaning
`400`	Invalid body, or `token_address` is the canonical USDC or USDT contract on that chain
`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
`503`	Could not start the recovery right now. Retry

Overview

Endpoints

Off-ramp endpoints

Onramp endpoints

Wallet API endpoints

Recover a stray token

Endpoint

Body

Example

Response (202)

Errors

​Endpoint

​Body

​Example

​Response (202)

​Errors

Endpoint

Body

Example

Response (202)

Errors