> 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/transfer-flow.md).

# Transfer Flow

This page describes exactly what happens from the moment a transfer is submitted to when funds land in a recipient's bank account.

***

## Overview

```
Partner API call
      ↓
 POST /api/payouts/transfer
      ↓
 Unique USDC deposit address issued
      ↓
 Partner sends USDC on-chain
      ↓
 Platform detects on-chain deposit (5–10 min)
      ↓
 Funds converted at locked FX rate
      ↓
 Outgoing transfer created and funded
      ↓
 Funds delivered to recipient bank/mobile wallet
      ↓
 Status → completed
```

***

## Step-by-Step

### 1. Quote lock

`GET /api/payouts/quote` returns a real-time mid-market FX rate locked for **5 minutes**. The response includes:

* `quoteId` — required for transfer creation
* `txFee` — fixed USD fee ($2 under $1,000 / $3 at or above $1,000)
* `netUsdAmount` — amount after fee deduction
* `eurAmount` — EUR equivalent after conversion
* Estimated `targetAmount` in the recipient's currency
* Delivery estimate

### 2. Transfer intent

`POST /api/payouts/transfer` validates the quote, verifies recipient ownership, and issues a **unique USDC deposit address** for this transfer. No two transfers share the same deposit address — this is how each on-chain deposit is matched to the correct transfer record.

The response includes `expires_at`. Send USDC before this timestamp.

### 3. On-chain USDC deposit

Send exactly `amount` USDC from `source_wallet` to `escrow_wallet`. Any supported chain is accepted:

| Chain            | Notes                                        |
| ---------------- | -------------------------------------------- |
| Base             | Recommended — lowest fees, fast confirmation |
| Arbitrum         | Low fees                                     |
| Optimism         | Low fees                                     |
| Polygon          | Low fees                                     |
| Ethereum Mainnet | Higher gas, slower                           |
| Solana           | Fast, low fees                               |

The platform scans for the deposit continuously. Confirmation typically takes **5–10 minutes** after the transaction is included in a block.

### 4. Conversion

Once the deposit is confirmed, funds are converted from USDC to the target fiat currency at the rate locked in step 1. Conversion uses institutional FX liquidity with a mid-market spread.

### 5. Outgoing transfer

An outgoing transfer to the recipient's bank account (or mobile wallet) is created and funded automatically. No further action is required from the partner.

### 6. Settlement

Settlement time depends on the payment rail:

| Rail                                  | Settlement         |
| ------------------------------------- | ------------------ |
| Local bank transfer (most currencies) | Instant – same day |
| M-PESA (KES)                          | Instant            |
| UPI (INR)                             | Instant            |
| SEPA/IBAN (EUR, GBP, others)          | Same day           |
| ACH (USD)                             | 1–2 business days  |
| SWIFT                                 | 5–7 business days  |

### 7. Completion

`status` transitions to `completed`. If you have an email address on file for the recipient, a notification is sent.

***

## Transfer Statuses

| Status             | Description                                                   |
| ------------------ | ------------------------------------------------------------- |
| `pending`          | Transfer created, awaiting USDC                               |
| `awaiting_deposit` | Deposit address issued, monitoring on-chain                   |
| `deposit_sent`     | USDC confirmed on-chain                                       |
| `processing`       | Funds converting and routing to recipient                     |
| `completed`        | Funds delivered to recipient's bank                           |
| `failed`           | Error — see `error` field; contact support with `transfer_id` |

***

## Concurrent Transfers

Multiple transfers can be in flight simultaneously — for the same account or different accounts. Each transfer has a unique deposit address and is settled independently. There is no serialization or per-user lock.

***

## Failure Handling

The platform automatically retries internal routing steps. If a transfer reaches `failed` status, the `error` field contains a description. Contact support at <support@madhousewallet.com> with the `transfer_id` for resolution.

Transfers that fail before USDC is sent can be cancelled via `POST /api/payouts/transfer/cancel` and retried with a fresh quote.

***

## Idempotency

Pass a `customer_uuid` in the transfer request body to enable safe retries. If you submit the same `customer_uuid` twice, the second request returns `409 Conflict` with the original transfer details — no duplicate is created.