Beneficiaries

A beneficiary is a payout destination owned by a participant. 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 '{
    "participant_id": "'"$PARTICIPANT_ID"'",
    "type": "business",
    "full_name": "Mumbai Exports Pvt Ltd",
    "country": "IN",
    "account": {
      "kind": "BANK_ACCOUNT",
      "destination_asset": "INR",
      "iban": "IN00BANK0000000001",
      "bank_name": "HDFC Bank",
      "bank_country": "IN",
      "routing": "HDFC0001234",
      "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 '{
    "participant_id": "'"$PARTICIPANT_ID"'",
    "type": "business",
    "full_name": "Treasury Ops",
    "country": "AE",
    "account": {
      "kind": "WALLET",
      "destination_asset": "USDT",
      "address": "0x4444444444444444444444444444444444444444",
      "network": "base"
    }
  }'

Top-level	Required	Notes
participant_id	yes	owning participant UUID
type	yes	business | individual
full_name	yes	max 256
country	yes	ISO alpha-2
gov_id_ref	if individual	e.g. passport:IN: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.

List / Get

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

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

Next steps

• Quotes · Reference