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
}
'

{
  "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"
  }
}

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
}
'

{
  "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"
  }
}

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

Get a quote Create a v2 transfer

⌘I