Getting Started

Make your first API call in minutes

This guide walks you through creating a recipient, getting a quote, and initiating a transfer via the Madhouse Wallet off-ramp API.

---

1. Get an API Key

Sign in at business.madhousewallet.com and navigate to Developers → API Keys. Create a new key. The full key is shown once — copy it immediately.

mw_live_<keyId>_<secret>

Include it on every request:

Authorization: Bearer mw_live_xxxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

---

2. Fetch Account Requirements

Before creating a recipient, fetch the required fields for the target currency. Different currencies require different inputs (routing numbers, IBANs, sort codes, UPI handles, etc.).

curl https://business.madhousewallet.com/api/payouts/account-requirements \
  -H "Authorization: Bearer $API_KEY" \
  -G -d "source=USD" -d "target=KES" -d "sourceAmount=500"

The response returns an array of field groups. Render each field according to its type (text, select, radio) and respect validationRegexp and minLength/maxLength.

If a field has refreshRequirementsOnChange: true, POST the current form state back to this endpoint when that field changes to get updated requirements.

---

3. Create a Recipient

curl -X POST https://business.madhousewallet.com/api/payouts/recipients \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "currency": "KES",
    "type": "kenya_local",
    "accountHolderName": "Jane Mwangi",
    "details": {
      "legalType": "PRIVATE",
      "accountNumber": "1234567890"
    }
  }'

Response:

{
  "id": 123456789,
  "currency": "KES",
  "accountHolderName": "Jane Mwangi"
}

Save the recipient id — you'll use it to get quotes and create transfers.

---

4. Get a Quote

curl "https://business.madhousewallet.com/api/payouts/quote" \
  -H "Authorization: Bearer $API_KEY" \
  -G -d "targetCurrency=KES" -d "sourceAmount=200"

Response includes:

{
  "quoteId": "a1b2c3d4-...",
  "txFee": 2,
  "netUsdAmount": 198,
  "eurAmount": 183.12,
  "quote": {
    "paymentOptions": [{ "targetAmount": 28450.00, "fee": { "total": 1.20 } }],
    "deliveryEstimate": "Within hours"
  }
}

Quotes are valid for 5 minutes. Pass quoteId to the next step.

---

5. Initiate the Transfer

curl -X POST https://business.madhousewallet.com/api/payouts/transfer \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "quote_id": "a1b2c3d4-...",
    "source_wallet": "0xYourUSDCWalletAddress",
    "amount": 200,
    "recipientId": 123456789
  }'

Response:

{
  "transfer_id": "txn_abc123",
  "escrow_wallet": "0xDepositAddress...",
  "amount": 200,
  "currency": "KES",
  "expires_at": "2026-03-29T12:10:00Z"
}

---

6. Send USDC

Send exactly amount USDC from source_wallet to escrow_wallet on any supported chain:

• Arbitrum

• Base

• Ethereum Mainnet

• Optimism

• Polygon

• Solana

The platform detects the deposit on-chain, converts to fiat, and routes to the recipient's bank account automatically.

---

7. Poll for Status

curl "https://business.madhousewallet.com/api/payouts/transfer-status/txn_abc123" \
  -H "Authorization: Bearer $API_KEY"

Status	Meaning
pending	Awaiting USDC deposit
awaiting_deposit	Deposit address issued
deposit_sent	USDC confirmed on-chain
processing	Converting and routing funds
completed	Funds delivered to recipient
failed	Contact support with transfer_id

Poll every 5 seconds. Stop polling on completed or failed.

---

Next Steps

• API Reference — full endpoint docs

• Transfer Flow — architecture deep dive

• Supported Currencies — all 85 currencies and rails