Send a transfer

Moves money from one of your users’ addresses to another user’s address on your account. Use it when your users pay each other, split a bill, or settle up inside your product.

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

A transfer is a normal blockchain payment between two addresses you created, sent when you ask for it. Because both addresses are yours, the receiving one doesn’t need to be on your approved list the way a withdrawal does.

Endpoint

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

Authorization: Bearer wsk_live_your_key_here

Transfers are switched on per account, and they start off. Contact us to turn them on. Once they’re on, any of your API keys can send them.

Body

string

required

The walletRef of the user paying.

string

required

The walletRef of the user being paid. It has to be a different address from from.

string

required

The network to send on. Both addresses need to work on it. Transfers stay on one network. To gather balances from several networks into one, use settlement.

string

required

USDC or USDT.

number

required

A positive amount of the coin, with up to 6 decimal places. The smallest transfer is 0.1 on most networks, 0.5 on Avalanche, and 20 on Ethereum.

string

Any text unique to this transfer. If you send the same key with the same request again, you get the original transfer back instead of a second one. Sending it with a different from, to, chain, token, or amount is refused with 409. Transfers and withdrawals share keys, so a key you’ve used for a withdrawal can’t be used for a transfer.

Example

curl -X POST https://merchant.minisend.xyz/api/v1/transfers \
  -H "Authorization: Bearer wsk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "user-42",
    "to": "user-7",
    "chain": "BASE",
    "token": "USDC",
    "amount": 12.5,
    "idempotency_key": "split-8841"
  }'

Response (202)

{
  "transfer": {
    "id": "8f21c3d0-...",
    "state": "queued",
    "from": "user-42",
    "to": "user-7",
    "chain": "BASE",
    "token": "USDC",
    "amount": "12.500000",
    "tx_hash": null,
    "created_at": "2026-10-01T09:00:00.000Z",
    "updated_at": "2026-10-01T09:00:00.000Z"
  }
}

202 means we’ve accepted the transfer and it goes out shortly. Check get a transfer or wait for wallet.transfer.completed. If you send an idempotency_key you’ve used before, you get 200 with the original transfer.

string

required

queued, sending, completed, failed, or under_review. failed means nothing moved, and the money is still at the from address. under_review is rare: we couldn’t confirm what happened, so we’re checking. Don’t treat it as paid or failed yet.

string

The blockchain transaction ID, once the transfer completes. null until then, and when failed.

The receiving address doesn’t get a wallet.deposit.received for a transfer. Credit the person receiving it when you get wallet.transfer.completed, so the same money is never counted twice.

Errors

Status	Meaning
`400`	Something isn’t right: the request fields, an amount below the network’s minimum, an address that doesn’t work on `chain`, or `from` doesn’t have enough of `token` there. Money already set aside for transfers or withdrawals still in progress counts as spent
`403`	Transfers aren’t switched on for your account yet
`404`	There’s no address with the `walletRef` in `from` or `to`
`409`	One of the addresses is frozen, the `idempotency_key` was used for a different request, or transfers aren’t available yet

Listing your transfers

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

Needs a key with wallets:read. Newest first.

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.

{
  "transfers": [
    {
      "id": "8f21c3d0-...",
      "state": "completed",
      "from": "user-42",
      "to": "user-7",
      "chain": "BASE",
      "token": "USDC",
      "amount": "12.500000",
      "tx_hash": "0x9b3e51c7a2d84f06e1b9c3a7d5f2e8b4c6a0d1f3e5b7c9a2d4f6e8b0c1a3d5f7",
      "created_at": "2026-10-01T09:00:00.000Z",
      "updated_at": "2026-10-01T09:00:41.000Z"
    }
  ],
  "total": 1,
  "limit": 20,
  "offset": 0
}

Getting one transfer

GET https://merchant.minisend.xyz/api/v1/transfers/{transferId}

Needs a key with wallets:read. Returns { "transfer": { ... } } with the same fields as above, or 404 if the id isn’t yours.

Overview

Endpoints

Off-ramp endpoints

Onramp endpoints

Wallet API endpoints

Send a transfer

Endpoint

Body

Example

Response (202)

Errors

Listing your transfers

Getting one transfer

​Endpoint

​Body

​Example

​Response (202)

​Errors

​Listing your transfers

​Getting one transfer

Endpoint

Body

Example

Response (202)

Errors

Listing your transfers

Getting one transfer