Create a recipient

curl --request POST \
  --url https://business.madhousewallet.com/api/payouts/recipients \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "currency": "EUR",
  "type": "iban",
  "accountHolderName": "Jane Doe",
  "details": {
    "legalType": "PRIVATE",
    "iban": "DE89370400440532013000"
  },
  "wallet": "0xAb5801a7D398351b8bE11C439e05C5B3259aeC9B"
}
'

{
  "id": 12345678,
  "accountHolderName": "Jane Doe",
  "currency": "EUR",
  "type": "iban",
  "active": true,
  "details": {},
  "country": "DE"
}

Recipients

Create a recipient

Creates a new payout recipient linked to your account. Use GET /api/payouts/account-requirements first to determine the correct type and details fields for the target currency.

Wallet verification: wallet is required and must be a KYC-verified wallet (EVM or SVM). Unverified wallets are rejected with 403 — verify your wallet at kyc.madhousewallet.com.

Email transfer recipients: Pass type: "wise_email_recipient" to create an email-based EUR recipient. currency must be EUR. No account requirements lookup needed — provide only details: { email: "recipient@example.com" }. Email recipients carry no transfer fee.

Country format: When details.address is present, details.address.country is required and must be a valid ISO 3166-1 alpha-2 code (two letters, e.g. US, GB, DE). Country names ("United States") and ISO-3 codes ("USA") are rejected with 400. This ensures the sanctions screen can reliably match country against the sanctioned record’s country list.

Compliance screening: The recipient is screened against a sanctions database before creation. The screen matches on three signals: accountHolderName (case-folded + accent-stripped exact match), details.address.country (ISO 2-letter code), and details.address (street + city + postal-code token overlap). A request is rejected with 403 only if all available signals match the same sanctioned entity. When either the sanctioned record or the recipient lacks a country or address, that check falls through to name-only matching to ensure sparse sanctions data still catches matches.

Rate limit: 30 requests/minute.

POST

api

payouts

recipients

Create a recipient

curl --request POST \
  --url https://business.madhousewallet.com/api/payouts/recipients \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "currency": "EUR",
  "type": "iban",
  "accountHolderName": "Jane Doe",
  "details": {
    "legalType": "PRIVATE",
    "iban": "DE89370400440532013000"
  },
  "wallet": "0xAb5801a7D398351b8bE11C439e05C5B3259aeC9B"
}
'

{
  "id": 12345678,
  "accountHolderName": "Jane Doe",
  "currency": "EUR",
  "type": "iban",
  "active": true,
  "details": {},
  "country": "DE"
}

Authorizations

Authorization

string

header

required

Pass your API key as a Bearer token: Authorization: Bearer mw_live_<keyId>_<secret>

Body

application/json

currency

string

required

ISO 4217 target currency code (e.g. EUR, GBP, USD)

Example:

"EUR"

type

string

required

Account type returned by GET /api/payouts/account-requirements (e.g. iban, sort_code, aba). Use wise_email_recipient to create an email-based EUR transfer recipient — no account requirements lookup needed. wise_email_recipient is only valid when currency is EUR.

Example:

"iban"

accountHolderName

string

required

Full legal name of the account holder

Example:

"Jane Doe"

details

object

required

Account-type-specific fields. For standard types (e.g. iban, sort_code, aba): provide the fields returned by GET /api/payouts/account-requirements. When the account type requires an address, details.address.country must be a valid ISO 3166-1 alpha-2 code (e.g. US, GB, DE). For wise_email_recipient: provide only { "email": "recipient@example.com" }.

Example:

{
  "legalType": "PRIVATE",
  "iban": "DE89370400440532013000"
}

wallet

string

Your wallet address (EVM 0x + 40 hex, or Solana base58 32–44 chars). Conditionally required: only needed if your account requires KYC verification. When required, it must be a KYC-verified wallet — unverified wallets are rejected with 403 (verify at kyc.madhousewallet.com). If KYC is not enabled for your account, this field may be omitted.

Example:

"0xAb5801a7D398351b8bE11C439e05C5B3259aeC9B"

Response

Recipient created

A payout recipient account

integer

required

Recipient account ID

Example:

12345678

accountHolderName

string

required

Name on the account

Example:

"Jane Doe"

currency

string

required

ISO 4217 currency code

Example:

"EUR"

type

string

required

Account type (e.g. iban, sort_code, aba)

Example:

"iban"

active

boolean

required

Whether the recipient is active

Example:

true

details

object

required

Account-type-specific details (routing/account numbers, IBAN, etc.)

country

string | null

ISO 3166-1 alpha-2 country code

Example:

"DE"

List recipients Get a recipient

⌘I