Create a wallet

Creates an address for your walletRef, or gives you the existing one if you’ve already created it. You never end up with two addresses for the same user.

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

Endpoint

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

Authorization: Bearer wsk_live_your_key_here

Body

string

required

Your own ID for this user or wallet: 1 to 128 characters, using letters, numbers, and _ : . -. Your own user ID works well. Each one can only belong to one wallet on your account.

string

default:"BASE"

BASE, ARB, AVAX, ETH, OP, MATIC, or ARC. It has to be a network your plan includes. See pricing. This never creates a second address. Your user’s address already works on every network your plan includes, so passing another network here just checks it’s allowed and gives you back the same address. ARC is USDC only, see Arc.

object

Any JSON object. We save it with the wallet and give it back when you fetch the wallet later.

Example

curl -X POST https://merchant.minisend.xyz/api/v1/wallets \
  -H "Authorization: Bearer wsk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"walletRef": "user-9214"}'

const res = await fetch('https://merchant.minisend.xyz/api/v1/wallets', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer wsk_live_your_key_here',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ walletRef: 'user-9214' }),
});

if (!res.ok) throw new Error((await res.json()).error);
const { wallet } = await res.json();

import requests

res = requests.post(
    "https://merchant.minisend.xyz/api/v1/wallets",
    headers={
        "Authorization": "Bearer wsk_live_your_key_here",
        "Content-Type": "application/json",
    },
    json={"walletRef": "user-9214"},
)

res.raise_for_status()
wallet = res.json()["wallet"]

Response (201)

{
  "wallet": {
    "id": "3f6b2e1a-...",
    "tenant_id": "a7c9e2d0-...",
    "master_wallet_id": "d4f81b3c-...",
    "wallet_ref": "user-9214",
    "address": "0xabc1230000000000000000000000000000dead",
    "chain": "BASE",
    "chains": ["BASE", "MATIC", "ARB", "OP", "ETH", "AVAX", "ARC"],
    "status": "active",
    "mode": "live",
    "metadata": null,
    "created_at": "2026-07-29T09:00:00.000Z"
  }
}

string

required

Our ID for this wallet. Use it with get wallet.

string

required

Your account’s ID. It’s the same on every wallet you create.

string

required

The master wallet (your business’s main wallet) this address sits under.

string

required

The ID you sent.

string

required

The crypto address, in lowercase.

string

required

The network this address was first created on. Always BASE.

array

required

Every network this address works on: BASE first, then each other network your plan includes. On a paid plan, that’s every network listed under pricing. On the Free plan, it’s just ["BASE"].

string

required

active or frozen.

string

required

Always live. The Wallet API doesn’t have a test mode yet.

object

Whatever you sent when creating it, or null.

Errors

Status	Meaning
`400`	Something isn’t right: the `walletRef` format, `metadata` isn’t a JSON object, your plan doesn’t include that `chain`, or you haven’t switched on Base yet
`401`	Your API key is missing or wrong
`403`	Your account is switched off
`429`	Too many requests (the limit is 60 a minute)

Overview

Endpoints

Off-ramp endpoints

Onramp endpoints

Wallet API endpoints

Create a wallet

Endpoint

Body

Example

Response (201)

Errors

​Endpoint

​Body

​Example

​Response (201)

​Errors

Endpoint

Body

Example

Response (201)

Errors