Registering Users

Before You Start

Read the following guides before proceeding:

Guide	Why
Overview	Understand External Authorization model
Authentication	How to obtain access tokens

Onboarding Flow Comparison

Standard Flow

1. Deploy Smart Wallet (on-chain)
2. Install executor + policy modules (on-chain)
3. Register in Accounts contract (on-chain)
4. Wait for wallet webhook
5. Register user via API
6. Complete KYC

External Authorization Flow

1. Register user via API
2. Complete KYC

No blockchain interaction required during onboarding.

User Registration

Register users via the standard API endpoint. The EOA address serves as the user identifier only — no wallet is deployed.

POST /api/v2/user

Request

{
  "wallet_address": "0x1234567890abcdef1234567890abcdef12345678",
  "email": "[email protected]",
  "country": "GB"
}

Field	Type	Required	Description
`wallet_address`	string	Yes	User's EOA address (0x-prefixed, 40 hex chars)
`email`	string	Yes	User's email address
`country`	string	Yes	ISO 3166-1 alpha-2 country code

The wallet_address is used solely as an identifier. No wallet deployment or on-chain registration occurs.

const response = await fetch(`${baseUrl}/api/v2/user`, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'X-User-Address': userEoaAddress,
    'X-Chain-Id': chainId,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    wallet_address: userEoaAddress,
    email: '[email protected]',
    country: 'GB'
  })
});
const user = await response.json();

response = requests.post(
    f"{base_url}/api/v2/user",
    headers={
        "Authorization": f"Bearer {access_token}",
        "X-User-Address": user_eoa_address,
        "X-Chain-Id": chain_id,
        "Content-Type": "application/json"
    },
    json={
        "wallet_address": user_eoa_address,
        "email": "[email protected]",
        "country": "GB"
    }
)
user = response.json()

body, _ := json.Marshal(map[string]string{
    "wallet_address": userEoaAddress,
    "email":          "[email protected]",
    "country":        "GB",
})
req, _ := http.NewRequest("POST", baseURL+"/api/v2/user", bytes.NewBuffer(body))
req.Header.Set("Authorization", "Bearer "+accessToken)
req.Header.Set("X-User-Address", userEoaAddress)
req.Header.Set("X-Chain-Id", chainId)
req.Header.Set("Content-Type", "application/json")

resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

var user UserResponse
json.NewDecoder(resp.Body).Decode(&user)

KYC Verification

After registration, complete KYC using any of the supported flows. The KYC process is identical to standard integration.

See KYC for available verification flows.

What's Different

Aspect	Standard	External Authorization
Wallet webhook	Received after on-chain registration	Not applicable
User wallet address	Smart Wallet (AA) address	EOA address used as identifier
Balance initialization	Per-user on-chain balance	No balance in Wirex (partner-managed)