Create a transfer

curl --request POST \
  --url https://business.madhousewallet.com/api/payouts/transfer \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "quote_id": "3f7a2b1c-4d5e-6f7a-8b9c-0d1e2f3a4b5c",
  "amount": 1000,
  "recipientId": 12345678,
  "customer_uuid": "550e8400-e29b-41d4-a716-446655440000",
  "customer_email": "user@example.com",
  "source_token": "usdc",
  "source_network": "base",
  "wallet_address": "0xAb5801a7D398351b8bE11C439e05C5B3259aeC9B",
  "keep_recipient": false
}
'

import requests

url = "https://business.madhousewallet.com/api/payouts/transfer"

payload = {
    "quote_id": "3f7a2b1c-4d5e-6f7a-8b9c-0d1e2f3a4b5c",
    "amount": 1000,
    "recipientId": 12345678,
    "customer_uuid": "550e8400-e29b-41d4-a716-446655440000",
    "customer_email": "user@example.com",
    "source_token": "usdc",
    "source_network": "base",
    "wallet_address": "0xAb5801a7D398351b8bE11C439e05C5B3259aeC9B",
    "keep_recipient": False
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    quote_id: '3f7a2b1c-4d5e-6f7a-8b9c-0d1e2f3a4b5c',
    amount: 1000,
    recipientId: 12345678,
    customer_uuid: '550e8400-e29b-41d4-a716-446655440000',
    customer_email: 'user@example.com',
    source_token: 'usdc',
    source_network: 'base',
    wallet_address: '0xAb5801a7D398351b8bE11C439e05C5B3259aeC9B',
    keep_recipient: false
  })
};

fetch('https://business.madhousewallet.com/api/payouts/transfer', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://business.madhousewallet.com/api/payouts/transfer",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'quote_id' => '3f7a2b1c-4d5e-6f7a-8b9c-0d1e2f3a4b5c',
    'amount' => 1000,
    'recipientId' => 12345678,
    'customer_uuid' => '550e8400-e29b-41d4-a716-446655440000',
    'customer_email' => 'user@example.com',
    'source_token' => 'usdc',
    'source_network' => 'base',
    'wallet_address' => '0xAb5801a7D398351b8bE11C439e05C5B3259aeC9B',
    'keep_recipient' => false
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://business.madhousewallet.com/api/payouts/transfer"

	payload := strings.NewReader("{\n  \"quote_id\": \"3f7a2b1c-4d5e-6f7a-8b9c-0d1e2f3a4b5c\",\n  \"amount\": 1000,\n  \"recipientId\": 12345678,\n  \"customer_uuid\": \"550e8400-e29b-41d4-a716-446655440000\",\n  \"customer_email\": \"user@example.com\",\n  \"source_token\": \"usdc\",\n  \"source_network\": \"base\",\n  \"wallet_address\": \"0xAb5801a7D398351b8bE11C439e05C5B3259aeC9B\",\n  \"keep_recipient\": false\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://business.madhousewallet.com/api/payouts/transfer")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"quote_id\": \"3f7a2b1c-4d5e-6f7a-8b9c-0d1e2f3a4b5c\",\n  \"amount\": 1000,\n  \"recipientId\": 12345678,\n  \"customer_uuid\": \"550e8400-e29b-41d4-a716-446655440000\",\n  \"customer_email\": \"user@example.com\",\n  \"source_token\": \"usdc\",\n  \"source_network\": \"base\",\n  \"wallet_address\": \"0xAb5801a7D398351b8bE11C439e05C5B3259aeC9B\",\n  \"keep_recipient\": false\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://business.madhousewallet.com/api/payouts/transfer")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"quote_id\": \"3f7a2b1c-4d5e-6f7a-8b9c-0d1e2f3a4b5c\",\n  \"amount\": 1000,\n  \"recipientId\": 12345678,\n  \"customer_uuid\": \"550e8400-e29b-41d4-a716-446655440000\",\n  \"customer_email\": \"user@example.com\",\n  \"source_token\": \"usdc\",\n  \"source_network\": \"base\",\n  \"wallet_address\": \"0xAb5801a7D398351b8bE11C439e05C5B3259aeC9B\",\n  \"keep_recipient\": false\n}"

response = http.request(request)
puts response.read_body

{
  "transfer": {
    "id": "507f1f77bcf86cd799439011",
    "user_id": "usr_550e8400e29b41d4a716446655440000",
    "type": "payout",
    "amount": 1000,
    "currency": "EUR",
    "status": "ready_to_process",
    "status_label": "Ready to Process",
    "recipientId": 12345678,
    "recipient": {
      "id": 12345678,
      "accountHolderName": "Jane Doe",
      "currency": "EUR",
      "type": "iban",
      "country": "DE",
      "details": {
        "legalType": "PRIVATE",
        "iban": "DE89370400440532013000"
      }
    },
    "customerUuid": "550e8400-e29b-41d4-a716-446655440000",
    "customerEmail": "user@example.com",
    "sourceToken": "usdc",
    "sourceNetwork": "base",
    "quote": {
      "sourceAmount": 1000,
      "providerCharge": 2,
      "serviceFeePercent": 1.5,
      "targetCurrency": "EUR",
      "usdToTargetRate": 0.9183,
      "targetAmount": 915.28,
      "transferFee": 0.58,
      "estimatedDelivery": "2026-03-30T12:00:00Z"
    },
    "wallet_address": "0xAb5801a7D398351b8bE11C439e05C5B3259aeC9B",
    "deposit_address": "0x1234567890AbCdEf1234567890AbCdEf12345678",
    "error": null,
    "refund_tx_hash": null,
    "reference": "507f1f77bcf86cd799439011",
    "timestamp": "2026-03-28T10:00:00.000Z"
  }
}

{
  "error": "<string>"
}

{
  "error": "<string>"
}

{
  "error": "<string>"
}

{
  "error": "<string>"
}

{
  "error": "<string>"
}

{
  "error": "<string>"
}

{
  "error": "<string>"
}

Payouts

Create a transfer

Creates a payout transfer and returns a unique deposit address on the network specified by source_network. Send USDC from wallet_address to that address — MW handles the rest of the conversion and delivery pipeline automatically.

Wallet verification: Before any other processing, wallet_address must be a KYC-verified wallet. Unverified wallets are rejected with 403 — verify your wallet at kyc.madhousewallet.com.

Compliance screening: The supplied wallet_address is also screened against a third-party risk database. Wallets that fail the screen are rejected with a 403. The screener supports EVM addresses only, so wallet_address is currently restricted to the EVM format (0x + 40 hex chars). Solana and Tron addresses are temporarily not accepted on this endpoint.

Prerequisites:

Your account must have a deployed Safe wallet.
Call GET /api/payouts/quote within the last 5 minutes — pass the returned quoteId as quote_id.
The recipientId must be a recipient belonging to your account.

Concurrent transfers: Multiple transfers can be in flight simultaneously — each gets a unique deposit address and is settled independently.

Workflow:

GET /api/payouts/quote → save quoteId.
POST /api/payouts/transfer with quote_id, amount, recipientId, source_network, wallet_address → receive deposit_address and transfer_id.
Send exactly amount USDC from wallet_address to deposit_address on source_network.
MW detects the deposit and automatically initiates the fiat payout to your recipient — email confirmation sent.

Rate limit: 20 requests/minute.

POST

api

payouts

transfer

Create a transfer

curl --request POST \
  --url https://business.madhousewallet.com/api/payouts/transfer \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "quote_id": "3f7a2b1c-4d5e-6f7a-8b9c-0d1e2f3a4b5c",
  "amount": 1000,
  "recipientId": 12345678,
  "customer_uuid": "550e8400-e29b-41d4-a716-446655440000",
  "customer_email": "user@example.com",
  "source_token": "usdc",
  "source_network": "base",
  "wallet_address": "0xAb5801a7D398351b8bE11C439e05C5B3259aeC9B",
  "keep_recipient": false
}
'

import requests

url = "https://business.madhousewallet.com/api/payouts/transfer"

payload = {
    "quote_id": "3f7a2b1c-4d5e-6f7a-8b9c-0d1e2f3a4b5c",
    "amount": 1000,
    "recipientId": 12345678,
    "customer_uuid": "550e8400-e29b-41d4-a716-446655440000",
    "customer_email": "user@example.com",
    "source_token": "usdc",
    "source_network": "base",
    "wallet_address": "0xAb5801a7D398351b8bE11C439e05C5B3259aeC9B",
    "keep_recipient": False
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    quote_id: '3f7a2b1c-4d5e-6f7a-8b9c-0d1e2f3a4b5c',
    amount: 1000,
    recipientId: 12345678,
    customer_uuid: '550e8400-e29b-41d4-a716-446655440000',
    customer_email: 'user@example.com',
    source_token: 'usdc',
    source_network: 'base',
    wallet_address: '0xAb5801a7D398351b8bE11C439e05C5B3259aeC9B',
    keep_recipient: false
  })
};

fetch('https://business.madhousewallet.com/api/payouts/transfer', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://business.madhousewallet.com/api/payouts/transfer",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'quote_id' => '3f7a2b1c-4d5e-6f7a-8b9c-0d1e2f3a4b5c',
    'amount' => 1000,
    'recipientId' => 12345678,
    'customer_uuid' => '550e8400-e29b-41d4-a716-446655440000',
    'customer_email' => 'user@example.com',
    'source_token' => 'usdc',
    'source_network' => 'base',
    'wallet_address' => '0xAb5801a7D398351b8bE11C439e05C5B3259aeC9B',
    'keep_recipient' => false
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://business.madhousewallet.com/api/payouts/transfer"

	payload := strings.NewReader("{\n  \"quote_id\": \"3f7a2b1c-4d5e-6f7a-8b9c-0d1e2f3a4b5c\",\n  \"amount\": 1000,\n  \"recipientId\": 12345678,\n  \"customer_uuid\": \"550e8400-e29b-41d4-a716-446655440000\",\n  \"customer_email\": \"user@example.com\",\n  \"source_token\": \"usdc\",\n  \"source_network\": \"base\",\n  \"wallet_address\": \"0xAb5801a7D398351b8bE11C439e05C5B3259aeC9B\",\n  \"keep_recipient\": false\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://business.madhousewallet.com/api/payouts/transfer")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"quote_id\": \"3f7a2b1c-4d5e-6f7a-8b9c-0d1e2f3a4b5c\",\n  \"amount\": 1000,\n  \"recipientId\": 12345678,\n  \"customer_uuid\": \"550e8400-e29b-41d4-a716-446655440000\",\n  \"customer_email\": \"user@example.com\",\n  \"source_token\": \"usdc\",\n  \"source_network\": \"base\",\n  \"wallet_address\": \"0xAb5801a7D398351b8bE11C439e05C5B3259aeC9B\",\n  \"keep_recipient\": false\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://business.madhousewallet.com/api/payouts/transfer")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"quote_id\": \"3f7a2b1c-4d5e-6f7a-8b9c-0d1e2f3a4b5c\",\n  \"amount\": 1000,\n  \"recipientId\": 12345678,\n  \"customer_uuid\": \"550e8400-e29b-41d4-a716-446655440000\",\n  \"customer_email\": \"user@example.com\",\n  \"source_token\": \"usdc\",\n  \"source_network\": \"base\",\n  \"wallet_address\": \"0xAb5801a7D398351b8bE11C439e05C5B3259aeC9B\",\n  \"keep_recipient\": false\n}"

response = http.request(request)
puts response.read_body

{
  "transfer": {
    "id": "507f1f77bcf86cd799439011",
    "user_id": "usr_550e8400e29b41d4a716446655440000",
    "type": "payout",
    "amount": 1000,
    "currency": "EUR",
    "status": "ready_to_process",
    "status_label": "Ready to Process",
    "recipientId": 12345678,
    "recipient": {
      "id": 12345678,
      "accountHolderName": "Jane Doe",
      "currency": "EUR",
      "type": "iban",
      "country": "DE",
      "details": {
        "legalType": "PRIVATE",
        "iban": "DE89370400440532013000"
      }
    },
    "customerUuid": "550e8400-e29b-41d4-a716-446655440000",
    "customerEmail": "user@example.com",
    "sourceToken": "usdc",
    "sourceNetwork": "base",
    "quote": {
      "sourceAmount": 1000,
      "providerCharge": 2,
      "serviceFeePercent": 1.5,
      "targetCurrency": "EUR",
      "usdToTargetRate": 0.9183,
      "targetAmount": 915.28,
      "transferFee": 0.58,
      "estimatedDelivery": "2026-03-30T12:00:00Z"
    },
    "wallet_address": "0xAb5801a7D398351b8bE11C439e05C5B3259aeC9B",
    "deposit_address": "0x1234567890AbCdEf1234567890AbCdEf12345678",
    "error": null,
    "refund_tx_hash": null,
    "reference": "507f1f77bcf86cd799439011",
    "timestamp": "2026-03-28T10:00:00.000Z"
  }
}

{
  "error": "<string>"
}

{
  "error": "<string>"
}

{
  "error": "<string>"
}

{
  "error": "<string>"
}

{
  "error": "<string>"
}

{
  "error": "<string>"
}

{
  "error": "<string>"
}

Authorizations

Authorization

string

header

required

Pass your API key as a Bearer token: Authorization: Bearer mw_live_<keyId>_<secret>

Body

application/json

quote_id

string

required

The quoteId returned by GET /api/payouts/quote (valid for 5 minutes; single-use)

Example:

"3f7a2b1c-4d5e-6f7a-8b9c-0d1e2f3a4b5c"

amount

number

required

USD amount to transfer (max 2 decimal places, must match the quoted amount ±$0.01)

Example:

100

recipientId

integer

required

Recipient account ID (must belong to your account)

Example:

12345678

customer_uuid

string<uuid>

required

Your own UUID for this transfer — stored for audit and support lookups. Must be globally unique across all transfers; a duplicate UUID is rejected with 409.

Example:

"550e8400-e29b-41d4-a716-446655440000"

customer_email

string<email>

required

Email address of the end user. Used to send transfer status notifications.

Example:

"user@example.com"

source_token

string

required

Token to send. Supported values: usdc, usdt. Use GET /api/payouts/deposit-options to retrieve the full list of supported token/network combinations.

Example:

"usdc"

source_network

string

required

Network to send from: arbitrum, avalanche, base, ethereum, polygon, solana, tron.

Example:

"base"

wallet_address

string

required

The address on source_network that will send USDC or USDT to the deposit address. Currently restricted to EVM addresses only (0x + 40 hex chars) because every transfer is pre-screened for compliance and the screener supports Ethereum-family addresses only. Solana and Tron addresses are temporarily rejected on this endpoint. The deposit address returned will be on the same network as source_network.

Example:

"0xAb5801a7D398351b8bE11C439e05C5B3259aeC9B"

keep_recipient

boolean

When true, the recipient account is not automatically deleted after the transfer reaches a terminal state (completed or failed). Use this for saved/reusable recipients that you manage yourself. Defaults to false — recipients are deleted automatically after each transfer.

Example:

false

Response

Transfer created — send USDC to deposit_address to trigger the payout pipeline

Wrapper returned by both POST /api/payouts/transfer and GET /api/payouts/transfer/:id

transfer

object

required

Show child attributes

Overview

Payouts

Recipients

Create a transfer

Authorizations

Body

Response