Migrate User With Wallet (Single)

Creates one user together with a wallet holding an address the user already has. The address is trimmed, lower-cased and recorded as a self-custody wallet (custody: false) on the chain named by chain_id, labelled with the user's email (or external_id). Unless kyc_sent is true, the platform then sends its KYC token(s) to that address on every network of the chain, asynchronously. See the overview for the identity, KYC and duplicate rules.

Required permission: user:create

Request

POST /v2/users/migrate/with-wallet

Headers

Name	Description
Authorization	Required. Bearer <access_token>
Content-Type	Required. application/json

Body

Field	Type	Required	Description
wallet_address	string	Yes	The user's existing address. Stored lower-cased
chain_id	string	Yes	Chain (chains id) the address lives on
email	string	No	Email. Required when external_id is absent; must be a valid email when given
external_id	string	No	Opaque identifier for KVKK-anonymized migration. Required when email is absent
name	string	No	First name; not stored when empty
surname	string	No	Last name; not stored when empty
kyc_sent	boolean	No	Default false. true means KYC was already done: nothing is sent and the wallet is recorded as KYC-verified on every network of the chain

Example

curl --request POST \
  --url '{{baseUrl}}/v2/users/migrate/with-wallet' \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "email": "john@example.com",
    "name": "John",
    "surname": "Doe",
    "wallet_address": "0xAbCdEf0123456789ABCDEF0123456789ABCDEF01",
    "chain_id": "6740e0a10000000000000101",
    "kyc_sent": false
  }'

KVKK mode (identifier only):

curl --request POST \
  --url '{{baseUrl}}/v2/users/migrate/with-wallet' \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "external_id": "EXT-1042",
    "wallet_address": "0xAbCdEf0123456789ABCDEF0123456789ABCDEF01",
    "chain_id": "6740e0a10000000000000101",
    "kyc_sent": true
  }'

Response

Status Code: 201 Created

{
  "id": "6913872755654191dede37da",
  "external_id": "EXT-1042",
  "name": "",
  "surname": "",
  "email": "",
  "identity_number": "",
  "status": 0,
  "created_at": "2026-08-21T09:14:02.511Z",
  "kyc": null
}

The created user, in the shape of Get User by ID. It carries no address; the imported wallet is in List User Wallets.

Errors

Status	Code	Description
400	10015	Validation failed (wallet_address or chain_id missing, malformed email) — see details
400	10015	Row skipped; message is the reason: missing_email_and_external_id, duplicate_email, duplicate_external_id, duplicate_wallet or invalid_chain
400	10016	chain_id is not a valid id

For imports where one bad row must not stop the rest, use Bulk or CSV. See Errors for the error format and common codes.