Migrate User With Wallet (Single)

Migrates a single user that already has a wallet address. The wallet address is stored as-is (lower-cased), and a KYC token event is published unless kyc_sent=true.

Request

POST /v2/users/users/migrate/with-wallet

Headers

Name	Description
Authorization	Required. Bearer token for authentication
Content-Type	Required. Must be application/json

Request Body

Field	Type	Description
wallet_address	string	Required. The user's wallet address. Normalized to lower case.
email	string	Optional. Standard identifier. Required if external_id is absent.
external_id	string	Optional. Opaque identifier for KVKK-anonymized migration. Required if email is absent.
name	string	Optional. Dropped if absent (no empty record written).
surname	string	Optional. Dropped if absent.
kyc_sent	boolean	Optional, default false. When true, KYC token event is not published and the user is marked as already KYC-verified.

At least one of email or external_id must be present.

Example — Classic mode

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

Example — KVKK mode (external_id only)

curl --location '{{baseUrl}}/v2/users/users/migrate/with-wallet' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data-raw '{
    "external_id": "EXT-1042",
    "wallet_address": "0xAbCdEf0123456789ABCDEF0123456789ABCDEF01",
    "kyc_sent": true
  }'

Response

Status Code: 201 Created

{
  "id": "6913872755654191dede37da",
  "external_id": "EXT-1042",
  "name": "",
  "surname": "",
  "email": "",
  "address": "0xabcdef0123456789abcdef0123456789abcdef01",
  "identity_number": "",
  "kyc": {
    "is_verified": true,
    "token_sent": true,
    "token_sent_at": "2026-06-01T12:34:56Z",
    "token_tx_hash": null
  }
}

Response Fields

Field	Type	Description
id	string	Unique identifier for the user.
external_id	string | null	Supplied external identifier.
email	string	Supplied email (empty string if absent).
name / surname	string	Supplied personal info (empty string if absent).
address	string	Stored wallet address (lower-cased).
kyc	object | null	Populated when kyc_sent=true was supplied. null otherwise.

Failure Modes

HTTP	Reason	Meaning
400	missing_email_and_external_id	Neither identifier was supplied.
400	duplicate_email	A user with the same email already exists.
400	duplicate_external_id	A user with the same external_id already exists.
400	duplicate_wallet	A user with the same wallet address already exists.
401	—	Invalid or missing authentication token.
500	—	Internal Server Error.

For batched imports where individual failures should not abort the run, use the Bulk endpoint or CSV upload instead.