Skip to main content
This guide walks through a complete payout: quote, recipient, transfer, deposit, and status check. Each step is a single API call you can run from your terminal.

​
Prerequisites

Before you begin, you must have:
Replace mw_live_<keyId>_<secret> in every example with your own key, and set a base URL variable to keep commands short: export MW=https://business.madhousewallet.com.

​
Get started

1

Get a quote

Request a live rate for a USD to EUR payout. Save the quoteId — it is valid for 5 minutes and single-use.
curl "$MW/api/payouts/quote?targetCurrency=EUR&sourceAmount=1000" \
  -H "Authorization: Bearer mw_live_<keyId>_<secret>"
The response includes quoteId, usdToTargetRate, fees, and an estimated delivery time. See Quotes and fees.
2

Find the recipient's required fields

Each currency needs different bank details. Ask which fields to collect for EUR.
curl "$MW/api/payouts/account-requirements?currency=EUR" \
  -H "Authorization: Bearer mw_live_<keyId>_<secret>"
The response lists account types (for example iban) and their fields. See Recipients and account requirements.
3

Create a recipient

Create the recipient with the fields you collected. Note the returned id.
curl -X POST "$MW/api/payouts/recipients" \
  -H "Authorization: Bearer mw_live_<keyId>_<secret>" \
  -H "Content-Type: application/json" \
  -d '{
    "currency": "EUR",
    "type": "iban",
    "accountHolderName": "Jane Doe",
    "details": { "legalType": "PRIVATE", "iban": "DE89370400440532013000" },
    "wallet": "0xAb5801a7D398351b8bE11C439e05C5B3259aeC9B"
  }'
4

Initiate the transfer

Submit the transfer with your quote_id, the recipientId, and the wallet that will send the USDC. You receive a unique deposit_address.
curl -X POST "$MW/api/payouts/transfer" \
  -H "Authorization: Bearer mw_live_<keyId>_<secret>" \
  -H "Content-Type: application/json" \
  -d '{
    "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"
  }'
The customer_uuid must be globally unique — a duplicate is rejected with 409.
5

Send the USDC

Send exactly the quoted amount of USDC from wallet_address to the returned deposit_address, on the same source_network. MW detects the deposit and starts the fiat payout automatically.
6

Check the status

Poll the transfer until it reaches a terminal status.
curl "$MW/api/payouts/transfer/507f1f77bcf86cd799439011" \
  -H "Authorization: Bearer mw_live_<keyId>_<secret>"
Status moves from ready_to_process to processing, transfer_created, and finally completed. See Transfer lifecycle.

​
Next steps

v1 vs v2 transfers

Choose the right transfer pipeline for your integration.

Compliance

Learn how wallet verification and sanctions screening work.
Need help? Email support@madhousewallet.com.