Create Crypto Beneficiary

Creates a new crypto beneficiary (address book entry) for a customer — a saved wallet address that crypto withdrawals can be sent to. Send the currency, blockchain network, wallet address, and recipient details; the same nickname/accountType/addressType rules as fiat beneficiaries apply.

Prerequisites

An existing customerId for the customer this beneficiary belongs to.

The X-Idempotency-Key header must be sent — reusing the same key returns the original result instead of creating a duplicate.

⚠️ Required Fields

Field	Type	Description	Constraints
`customerId`	`string (uuid)`	The customer this beneficiary belongs to	-
`nickname`	`string`	A short label for this beneficiary (e.g. "Binance USDT Wallet")	Min: 1 · Max: 100
`currency`	`string`	Crypto currency code (e.g. `BTC`, `ETH`, `USDT`)	Min: 1
`network`	`string`	Blockchain network (e.g. `ERC20`, `TRC20`, `BTC`)	Min: 1
`walletAddress`	`string`	Wallet address or account number	Min: 1
`accountType`	`string`	`individual` or `business`	Pattern: `^(individual
`addressType`	`string`	`1st Party` (customer's own wallet) or `3rd Party` (someone else's wallet)	Pattern: `^(1st Party

Optional Fields

Field	Type	Description	Constraints
`beneficiaryId`	`string (uuid)`	Ignored on create; only used by the update endpoint	Nullable
`walletSource`	`string`	Wallet source (e.g. `Binance`, `Coinbase`, `Other`)	Nullable
`otherWallet`	`string`	Other wallet name when `walletSource` is `Other`	Nullable
`recipient.firstName`	`string`	Recipient first name	Nullable
`recipient.middleName`	`string`	Recipient middle name	Nullable
`recipient.lastName`	`string`	Recipient last name	Nullable
`recipient.businessName`	`string`	Required when `accountType` is `business`	Nullable
`recipient.email`	`string`	Recipient email address	Nullable
`recipient.phoneCode`	`string`	International dialling code, e.g. `+44`, `+1`	Nullable
`recipient.phoneNumber`	`string`	Phone number without country code	Nullable
`address.street`	`string`	Street name	Nullable
`address.line1`	`string`	Address line 1	Nullable
`address.city`	`string`	City	Nullable
`address.state`	`string`	State / region	Nullable
`address.postalCode`	`string`	Postal code	Nullable
`address.country`	`string`	ISO 3166-1 alpha-2 country code (e.g. `GB`, `US`)	Nullable

📤 Response Fields

Field	Type	Description
`data.id`	`string (uuid)`	Unique ID of the created crypto beneficiary
`data.customerId`	`string (uuid)`	The customer this beneficiary belongs to
`data.nickname`	`string`	Label for this beneficiary
`data.currency`	`string`	Crypto currency code
`data.network`	`string`	Blockchain network
`data.walletAddress`	`string`	Wallet address
`data.walletSource`	`string`	Wallet source
`data.accountType`	`string`	`individual` or `business`
`data.addressType`	`string`	`1st Party` or `3rd Party`
`data.recipient`	`object`	Recipient details
`data.address`	`object`	Beneficiary address
`data.status`	`string`	Beneficiary status (e.g. `active`)
`data.createdAt`	`string (date-time)`	Creation timestamp (UTC)
`requestId`	`string`	Unique ID of this request
`timestamp`	`string (date-time)`	Server timestamp of the response (UTC)

curl --location '/api/v1/beneficiary/crypto/create' \ --header 'X-Idempotency-Key: 6f1a9c0e-2b7d-4c31-9f8a-1d5e7c3b0a42' \ --header 'X-API-Key;' \ --header 'X-Signature;' \ --header 'X-Timestamp;' \ --header 'X-Nonce;' \ --header 'X-Body-Hash;' \ --header 'Content-Type: application/json' \ --data-raw '{ "success": true, "data": { "id": "c7e91b2d-4f6a-4830-9d5e-8a1f3c7b2e94", "customerId": "ed2baa83-a988-4b4a-93ee-fad379500bbd", "nickname": "Binance USDT Wallet", "currency": "USDT", "network": "TRC20", "walletAddress": "TQrY8bkbpXKPt2LZbU8jqYt8YXqxBxdK7m", "walletSource": "Binance", "accountType": "individual", "addressType": "1st Party", "recipient": { "firstName": "Rahul", "lastName": "Sharma", "email": "rahul.sharma@example.com", "phoneCode": "+91", "phoneNumber": "9810012345" }, "address": { "line1": "B-42 Green Park", "city": "New Delhi", "state": "Delhi", "postalCode": "110016", "country": "IN" }, "status": "active", "createdAt": "2026-08-12T10:30:12Z" }, "requestId": "a5d38e1c9f274b60b8e2d4f17a93c586", "timestamp": "2026-08-12T10:30:12.664018Z" }'

{ "data": { "payeeId": "6cf0dac7-5b6d-45ba-a766-b4616c7b81d7", "status": "CREATED", "message": "Crypto beneficiary created successfully." }, "requestId": "5e84329770224f8ca00bd9240c18d51c", "timestamp": "2026-08-25T13:16:56.3958376Z" }

Request

Responses