> For the complete documentation index, see [llms.txt](https://docs.madhousewallet.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.madhousewallet.com/quickstart.md).

# Getting Started

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](https://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:

```http
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.).

```bash
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

```bash
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:**

```json
{
  "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

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

**Response includes:**

```json
{
  "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

```bash
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:**

```json
{
  "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

```bash
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](/quickstart/api-reference.md) — full endpoint docs
* [Transfer Flow](/quickstart/transfer-flow.md) — architecture deep dive
* [Supported Currencies](/supported-countries.md) — all 85 currencies and rails