Create a wallet

Creates an address for your walletRef, or returns the existing one if you’ve already created it. Never mints a second address for the same reference and chain.

Backend only. Never call from frontend.

Endpoint

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

Authorization: Bearer wsk_live_your_key_here

Body

string

required

Your own identifier for this user or wallet: 1 to 128 characters, letters, numbers, and _ : . -. Your own user ID works well. Unique per your account and chain.

string

default:"BASE"

BASE, ARB, AVAX, ETH, OP, or MATIC. Must already be activated on your account — see activating a chain.

object

Any JSON object. Stored alongside the wallet and returned when you fetch it 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",
    "status": "active",
    "mode": "live",
    "metadata": null,
    "created_at": "2026-07-29T09:00:00.000Z"
  }
}

string

required

Minisend’s identifier for this wallet. Use it with get wallet.

string

required

Your account identifier. The same on every wallet you create.

string

required

The master wallet this address was issued under, for the chain you requested.

string

required

Echoes the reference you provided.

string

required

The on-chain address, lowercased.

string

required

The chain this address lives on.

string

required

active or frozen.

string

required

Always live. The Wallet API has no sandbox today.

object

Whatever you passed at creation, or null.

Errors

Status	Meaning
`400`	Invalid `walletRef`, unsupported `chain`, `metadata` isn’t a JSON object, or `chain` isn’t activated on your account yet
`401`	Missing or invalid API key
`403`	Account inactive
`429`	Rate limit exceeded (60 requests/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