Beneficiaries

A beneficiary is a payout destination owned by a customer. Each create includes one nested account (BANK_ACCOUNT, WALLET, or MOBILE_WALLET).

Create — bank account

curl -X POST "$BASE_URL/v1/beneficiaries" \
  -H "X-API-Key: $THIQWAVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "'"$CUSTOMER_ID"'",
    "type": "business",
    "full_name": "Singapore Exports Pte Ltd",
    "country": "SG",
    "account": {
      "kind": "BANK_ACCOUNT",
      "destination_asset": "SGD",
      "iban": "SG00BANK0000000001",
      "bank_name": "Example Bank Singapore",
      "bank_country": "SG",
      "routing": "EXBKSGSGXXX",
      "is_default": true
    }
  }'

Create — on-chain wallet

curl -X POST "$BASE_URL/v1/beneficiaries" \
  -H "X-API-Key: $THIQWAVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "'"$CUSTOMER_ID"'",
    "type": "business",
    "full_name": "Treasury Ops",
    "country": "AE",
    "account": {
      "kind": "WALLET",
      "destination_asset": "USDT",
      "address": "0x4444444444444444444444444444444444444444",
      "network": "base"
    }
  }'

Top-level	Required	Notes
customer_id	yes	owning customer UUID
type	yes	business | individual
full_name	yes	max 256
country	yes	ISO alpha-2
gov_id_ref	if individual	e.g. passport:SG:Z1234567
account.kind	yes	BANK_ACCOUNT | WALLET | MOBILE_WALLET

account required fields by kind: BANK_ACCOUNT → destination_asset, iban, bank_country; WALLET → destination_asset, address, network; MOBILE_WALLET → destination_asset, mobile_number, mobile_provider.

:::note Wallet networks base is used above only as an example. network accepts any network enabled for your corridor, and address must be in the address format of that network — validate it first with GET /v1/wallets/validate. :::

List / Get

curl "$BASE_URL/v1/beneficiaries?customer_id=$CUSTOMER_ID" -H "X-API-Key: $THIQWAVE_API_KEY"
curl "$BASE_URL/v1/beneficiaries/$BENEFICIARY_ID"                -H "X-API-Key: $THIQWAVE_API_KEY"

customer_id is required on list (beneficiaries are scoped to a sender).

Next steps

• Quotes · Reference