> ## Documentation Index
> Fetch the complete documentation index at: https://developer.madhousewallet.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Changelog

> Notable changes to the MW Payouts API.

<Update label="v1.3.23" description="2026-06-02">
  **Changed** — Raised the rate limit on `GET` and `POST /api/payouts/account-requirements` from 60 to 500 requests/minute per key.
</Update>

<Update label="v1.3.22" description="2026-06-01">
  **Changed** — `GET /api/payouts/transfer/:id` lookup is now global by `transfer_id`. Any valid API key can retrieve any transfer by its ID — including transfers created from the dashboard or with a different key. Transfer IDs are unguessable 24-character identifiers. A correct ID that previously returned `404` (owned by another account) now returns the transfer.
</Update>

<Update label="v1.3.21" description="2026-06-01">
  **Changed** — The transfer reference is now the bare transfer ID (for example `507f1f77bcf86cd799439011`) instead of `Recipient {recipientId} Ref {transferId}`. This keeps the reference within the length limits enforced by some destination currencies. No request changes are required.
</Update>

<Update label="v1.3.20" description="2026-05-30">
  **Changed** — `POST /api/payouts/transfer` (v1) now requires your account to be explicitly provisioned for this transfer method. Unprovisioned accounts receive `403`. Contact support to enable it. `POST /api/payouts/transfer/v2` is unaffected.
</Update>

<Update label="v1.3.19" description="2026-05-30">
  **Added** — `POST /api/payouts/transfer/v2` now performs wallet compliance screening when enabled for your account (the default). When enabled, `wallet_address` is required, must be an EVM address, and is screened before any other processing; a failing wallet is rejected with `403`. Solana addresses are not accepted while screening is enabled, and an unavailable screening service fails closed with `503`. When screening is disabled, behavior is unchanged.
</Update>

<Update label="v1.3.18" description="2026-05-29">
  **Changed** — The `wallet` field is now conditionally required instead of always required. On `POST`/`PATCH /api/payouts/recipients`, `DELETE /api/payouts/recipients/:id` (query parameter), and `POST /api/payouts/transfer/v2`, the wallet is only required if your account requires KYC verification. `POST /api/payouts/transfer` (v1) is unchanged — `wallet_address` remains required there.
</Update>

<Update label="v1.3.17" description="2026-05-27">
  **Added** — KYC wallet verification is now enforced on recipient management and transfer initiation. `POST`/`PATCH /api/payouts/recipients` require a `wallet` field, and `DELETE /api/payouts/recipients/:id` requires a `?wallet=` query parameter.

  **Changed** — These endpoints now reject wallets that are not KYC-verified with `403`. If the verification service is unreachable, the request fails closed with `503`. Verify your wallet at [kyc.madhousewallet.com](https://kyc.madhousewallet.com).
</Update>

<Update label="v1.3.16" description="2026-05-26">
  **Removed** — BGN (Bulgarian Lev) is no longer a supported `targetCurrency`. Use EUR for recipients in Bulgaria. The supported-currency count is now 81.
</Update>

<Update label="v1.3.15" description="2026-05-26">
  **Added** — `GET /api/payouts/quote` now includes a transfer-fee breakdown: `feeFxPercent`, `feeFxAmount`, and `feePayoutAmount`. `feeFxAmount + feePayoutAmount` equals `transferFee`. All three are `null` when a breakdown is unavailable.
</Update>

<Update label="v1.3.14" description="2026-05-26">
  **Changed** — `GET /api/payouts/quote` now computes `quote.targetAmount` and `quote.transferFee` from the internal per-currency fee schedule, tracking delivered amounts to within \~1%. Response shape is unchanged.
</Update>

<Update label="v1.3.13" description="2026-05-26">
  **Added** — `GET /api/payouts/quote` now accepts `v2_offloader=true`. The response uses the v2 fee structure: `serviceFeePercent` reflects your configured bips plus the 20-bip processing cut, `serviceFeeFixed` is `0`, and `providerCharge` is omitted. The `quoteId` can be passed to `POST /api/payouts/transfer/v2`.
</Update>

<Update label="v1.3.12" description="2026-05-24">
  **Changed** — `DELETE /api/payouts/recipients/:id` no longer blocks deletion while a transfer is in progress. In-progress transfers are marked failed before deletion, and the response now includes a `transfers_failed` count.
</Update>

<Update label="v1.3.10" description="2026-05-24">
  **Added** — `POST /api/payouts/transfer/v2`, a USDC-only transfer endpoint that returns a fixed deposit address with no expiry. Supported networks: base, solana, polygon, arbitrum, avalanche, ethereum.

  **Added** — `POST /api/payouts/transfer/v2/confirm-transfer` to link an on-chain `tx_hash` to a v2 transfer. Each hash may be used only once across the platform; a second identical call is idempotent.
</Update>

<Update label="v1.3.9" description="2026-05-24">
  **Removed** — `POST /api/payouts/transfer/cancel`. Pending transfers expire automatically; for transfers already in progress, contact support.
</Update>

<Update label="v1.3.8" description="2026-05-23">
  **Added** — `GET /api/payouts/transfer/:id` gains a `refunded` status and a `refund_tx_hash` field containing the on-chain Base hash of the USDC refund. The field is non-null only when the status is `refunded`.
</Update>

<Update label="v1.3.7" description="2026-05-23">
  **Removed** — The `user_id` field is removed from `POST /api/payouts/recipients`, `POST /api/payouts/transfer`, and recipient responses. Ownership is enforced server-side by the authenticated API key.
</Update>

<Update label="v1.3.6" description="2026-05-23">
  **Added** — `POST /api/payouts/transfer` gains the optional boolean `keep_recipient`. When `true`, the recipient is not auto-deleted after the transfer reaches a terminal state. Defaults to `false`.
</Update>

<Update label="v1.3.5" description="2026-05-22">
  **Added** — `POST /api/payouts/recipients` supports `type: "wise_email_recipient"` for EUR recipients, using `details: { "email": "..." }`. Email recipients carry no transfer fee. `GET /api/payouts/quote` accepts `recipientType=wise_email_recipient`, returning `transferFee: 0`.
</Update>

<Update label="v1.3.0" description="2026-05-17">
  **Added** — `POST /api/payouts/transfer` now pre-screens every `wallet_address` against a third-party risk database. Failing wallets are rejected with `403`; an unavailable service returns `503`.

  **Removed** — `wallet_address` on `POST /api/payouts/transfer` no longer accepts Solana or Tron addresses — EVM only, because the screener supports Ethereum-family addresses.
</Update>

<Update label="v1.2.0 – v1.2.6" description="2026-03-29 – 2026-04-16">
  **Added** — USDT support on Tron and Ethereum, and `avalanche` as a source network. The `deposit_address` is now returned on the network specified by `source_network` rather than always Base.

  **Changed** — `source_token` and `source_network` are now required on `POST /api/payouts/transfer` (previously defaulted to `usdc`/`base`).
</Update>

<Update label="v1.1.0" description="2026-03-29">
  **Added** — `POST /api/payouts/transfer` gains the required `wallet_address` field, returned in both the transfer creation and lookup responses.
</Update>