# Register user Source: https://docs.settlemint.com/docs/developers/developer-guides/user-management/register-user Register a user's wallet and OnchainID in the identity registry via API for compliance tracking and token eligibility. Registering a user links a wallet address, OnchainID identity, and jurisdiction in the identity registry. DALP uses that registry entry when it evaluates regulated asset mints and transfers. Registration does not make the user eligible for every asset by itself. Eligibility still depends on the asset's required claim topics, trusted issuers, country rules, and transfer restrictions. Use this guide to register identities from an integration or automation script. For the portal workflow, see [Register user](/docs/operators/user-guides/user-management/register-user). ## Prerequisites [#prerequisites] * Platform API base URL, such as `https://your-platform.example.com`. * API key with permission to register identities. * A user wallet with an existing OnchainID identity. See [Create users](/docs/developers/developer-guides/user-management/create-users). * A confirmed jurisdiction for the user. The API accepts ISO 3166-1 alpha-2 country codes, such as `BE`, `DE`, or `US`. * Wallet verification when you authenticate with a browser session. API key authentication does not require a `walletVerification` body. ## What registration does [#what-registration-does] Registration queues an on-chain `system.identity-register` transaction against the active identity registry. The API accepts the country as an ISO alpha-2 code and encodes the numeric country value for the on-chain registry call. | State | What it means | Asset eligibility | | --------------------- | ---------------------------------------------------------------------------------------------------------- | --------------------------------------------------- | | Pending registration | The wallet has an OnchainID identity, but the registry does not yet mark it as registered. | Blocked for regulated asset transactions. | | Registered | The registry can resolve the wallet to an OnchainID identity and country. | Depends on the asset's claims and compliance rules. | | Verified for an asset | The registered identity has the claim topics required by that asset from trusted issuers for those topics. | Eligible when the other compliance modules pass. | ## Register a user [#register-a-user] ### Find the wallet to register [#find-the-wallet-to-register] If you are registering a specific user, read the user record and capture the wallet address. ```bash curl "https://your-platform.example.com/api/user/search?query=user@example.com" \ -H "X-Api-Key: YOUR_API_KEY" ``` Example response: ```json [ { "id": "usr_abc123", "name": "John Doe", "wallet": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb", "role": "member" } ] ``` Use `wallet` from the selected result. If you omit `wallet` from the registration request, DALP uses the authenticated or selected effective wallet for the request. ### Choose the jurisdiction [#choose-the-jurisdiction] Send the user's legal residence or incorporation country as an ISO 3166-1 alpha-2 code. The country value can be used by compliance modules, but registration does not create a legal determination or verification result. Keep the supporting evidence in your operating workflow. ### Queue the registration transaction [#queue-the-registration-transaction] Use the queued identity registration endpoint for new integrations. `Prefer: respond-async` returns immediately after DALP accepts the transaction. ```bash curl -X POST "https://your-platform.example.com/api/v2/system/identity-registrations" \ -H "X-Api-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -H "Prefer: respond-async" \ -d '{ "wallet": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb", "country": "BE" }' ``` Example async response: ```json { "transactionId": "txreq_123", "status": "QUEUED", "statusUrl": "/api/v2/transaction-requests/txreq_123" } ``` Without `Prefer: respond-async`, the route waits for the configured confirmation window. If the transaction confirms in that window, DALP returns the registered identity in the standard mutation envelope. ### Read the identity by wallet [#read-the-identity-by-wallet] After the transaction confirms and the indexer catches up, read the identity by wallet. Use the identity read endpoint, not user search, because user search does not return registration state. ```bash curl "https://your-platform.example.com/api/v2/system/wallets/0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb/identity" \ -H "X-Api-Key: YOUR_API_KEY" ``` A registered response includes the identity address, account wallet, registration state, country, and claims returned by the identity read endpoint. ```json { "data": { "id": "0x8e5F72f6E5b3B4D1234567890AbCdEf1234567890", "account": { "id": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb", "contractName": null }, "isContract": false, "hasIdentity": true, "registered": { "isRegistered": true, "country": "BE" }, "claims": [] }, "links": { "self": "/v2/system/wallets/0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb/identity" } } ``` Treat the registration as complete when `data.registered.isRegistered` is `true` and `data.registered.country` matches the alpha-2 country code you submitted. ## Request body [#request-body] | Field | Type | Required | Description | | -------------------- | ------ | ------------ | ----------------------------------------------------------------------------------------------- | | `wallet` | string | No | Wallet address to register. Omit it to register the authenticated or selected effective wallet. | | `country` | string | Yes | ISO 3166-1 alpha-2 country code, such as `BE`, `DE`, or `US`. | | `walletVerification` | object | Session only | Wallet verification payload for session-authenticated requests. API key requests can omit it. | ### Wallet verification object [#wallet-verification-object] | Field | Type | Description | | ------------------------ | ------ | ---------------------------------------------------------------- | | `secretVerificationCode` | string | PIN, secret code, or TOTP value for the signing user. | | `verificationType` | string | `PINCODE` by default, or `SECRET_CODES` / `OTP` when configured. | ## CLI equivalent [#cli-equivalent] The CLI `identities` command calls the same identity APIs and is useful for scripts that already run through a DALP CLI profile. ```bash dalp identities register \ --wallet 0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb \ --country BE dalp identities read-by-wallet 0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb ``` Send the same alpha-2 country code that you would send to the API. ## Compliance boundaries [#compliance-boundaries] * Registration is required before a wallet can pass regulated asset eligibility checks. * Registration stores the wallet-to-OnchainID relationship and country in the identity registry. * KYC, KYB, AML, sanctions, accreditation, and document review happen off-chain before a trusted issuer issues claims. * Asset eligibility still depends on required claim topics, issuer trust, country rules, and transfer restrictions. * Keep legal residence, incorporation, approval, and evidence records in your own operating workflow. * If a registered wallet is lost or compromised, use the identity recovery workflow. A normal user profile edit does not replace the registry binding. ## Troubleshooting [#troubleshooting] | Issue | What to check | | --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `401 Unauthorized` | Confirm the API key is valid, active, and sent in `X-Api-Key`. | | `403 USER_NOT_AUTHORIZED` | Confirm the caller has permission to register identities in the current system. | | No identity found | Create the user's OnchainID identity before registration. See [Create users](/docs/developers/developer-guides/user-management/create-users). | | `409 Conflict` or already registered response | The wallet already has an active registry entry. Continue with claim issuance or read the identity by wallet to confirm state. | | Invalid country code | Send an ISO 3166-1 alpha-2 country code, such as `BE`, `DE`, or `US`. Do not send the numeric on-chain value. | | Registration remains pending | Poll the returned `statusUrl`, wait for transaction confirmation and indexing, then read the identity by wallet again. | | Read-back does not show registration | Use `/api/v2/system/wallets/{wallet}/identity`. User search returns account data, not full identity registration state. | | Registered user still cannot receive an asset | Check the asset's required claim topics, trusted issuer configuration, country rules, and transfer restrictions. Registration alone is not enough for every asset. | ## Related guides [#related-guides] * [Create users](/docs/developers/developer-guides/user-management/create-users) explains how to create users with wallets and OnchainID identities. * [Transaction tracking](/docs/developers/developer-guides/operations/transaction-tracking) explains how to follow queued blockchain operations. * [Verify KYC](/docs/developers/developer-guides/compliance/verify-kyc) explains how to issue claims after review. * [Claims and identity](/docs/architects/architecture/concepts/claims-and-identity) explains how wallet registration, OnchainID claims, and trusted issuers work together. * [Identity and compliance](/docs/compliance-security/security/identity-compliance) covers the identity checks used by compliance modules. * [Register user](/docs/operators/user-guides/user-management/register-user) covers the portal workflow.