Onboarding process

This document explains what onboarding in Holders is, its goals, when it starts and ends, the main user steps, and how wallet connection and user token creation technically work.

What is onboarding

Onboarding in Holders represents a structured process of integrating a mobile wallet user with the functional capabilities of the Holders SDK. Within this process, the user creates a personal Holders profile, provides necessary consents for data processing, and performs the primary key action — account funding — to ensure full access to Holders functionality within the wallet.

Onboarding goals

• Explain the value of Holders

The user understands what Holders is, can evaluate the onboarding process, and form a correct opinion about the company.

• Guide through profile creation

The user flawlessly goes through the steps: creates a profile, confirms wallet connection, completes basic setup.

• Collect necessary consents and permissions

The user provides all required consents (for Holders and partners) so the service can operate fully and remain compliant.

• Lead to the first target action

The user performs the first key action based on Holders - creates and funds an account.

• Reduce churn and misunderstanding

Minimize cases where the user exits onboarding due to fear, misunderstanding, or perception of complexity, through simple explanations and clear steps.

• Filter out unsuitable users

Correctly stop onboarding if the user doesn’t meet critical conditions (residency, creditworthiness), and explain why and what can be done next (if relevant).

Onboarding start and end conditions

Onboarding start

Onboarding begins on the main page of the mobile wallet or application into which Holders is integrated, typically with the display of a banner or pop-up window offering account opening and card issuance. The banner is shown by default to all application users regardless of their residency.
The banner or window is displayed in the language selected as primary in the mobile application.

Onboarding completion

Onboarding is considered complete if the user successfully funds their account in the Holders system. In all other cases, onboarding is considered incomplete.

Onboarding flowchart

Main Stages

1. Wallet connection — performed automatically in the background using the Ton Connect protocol or adapter for the Solana blockchain.
2. User token creation — procedure for transmitting identification data to the Holders server-side system.
3. Profile creation — executed when the user confirms their mobile phone number. At this stage, a primary record is created in the Holders database.
4. KYC — user verification procedure through a partner service (Sumsub).
5. Account creation — smart contract deployment and issuance of the first card (card issuance is possible when residency requirements are met).
6. Account funding — transferring funds to the created account.

More about wallet connection

Tonhub uses a single cryptographic key (Ed25519) to work with both networks: TON and Solana. This is possible because both networks use the same signature algorithm.

TON Connection

Connection Process

1. Application manifest retrieval - Tonhub loads the TonConnect manifest from the Holders server ( /jsons/tonconnect-manifest.json), which contains the application name, URL, and icon.
2. User authentication - The user confirms the operation through biometry or PIN code to access the wallet’s secret key.
3. TON Proof creation - A cryptographic proof of wallet ownership is formed:
   • The wallet address is taken in workchain:hash format
   • The Holders domain is added (e.g., tonhub.holders.io)
   • Current timestamp is added
   • Payload is added (random string from server)
   • All this is hashed and signed with the wallet’s secret key
4. Server submission - A POST request is sent to /v2/user/wallet/connect with data:
   • Wallet address
   • stack: 'ton'
   • network: 'ton-mainnet' or 'ton-testnet'
   • wallet: 'tonhub'
   • TON Proof (timestamp, domain, signature, payload)
   • Public key
   • Wallet StateInit (for address verification)
5. Token retrieval - The Holders server verifies the signature and returns a User Token (JWT).

What the server verifies

• Signature validity (that it was made by the owner of the specified address)
• Public key correspondence to address through StateInit
• Timestamp relevance (protection against replay attacks)
• Domain correctness

Solana Connection

Key Feature

Tonhub uses the same Ed25519 key for Solana as for TON. This is possible because:

• TON and Solana use the same signature algorithm (Ed25519)
• The TON wallet’s public key is directly converted to a Solana address

Connection Process

1. Solana address retrieval - The TON wallet’s public key (32 bytes) is interpreted as a Solana PublicKey and converted to Base58 format.
2. Solana Proof creation - Formed similarly to TON Proof:
   • The Solana address is taken (public key in Base58)
   • Holders domain is added
   • Timestamp is added
   • Payload is added
   • Signed with the same secret key
   • Difference: signature is encoded in Base58 (not Base64 as for TON)
3. Server submission - Simultaneously with TON, Solana proof is sent:
   • Solana address (public key in Base58)
   • Solana Proof
   • stack: 'solana'
   • network: 'solana-mainnet' or 'solana-devnet'

Result

The Holders server links both accounts (TON and Solana) to one user and issues a unified User Token for access to both.

What is User token

User Token is a JWT (JSON Web Token) that is issued by the Holders server after successful authentication and serves as the user’s session identifier.

What is it used for

Function	Definition
API Authorization	Passed in each request to the Holders API in the request body ({ token: "..." })
Getting Profile	/v2/profile/get - user information
Account List	/v2/account/list - cards and crypto accounts
Account status	/account/state - KYC status, verification
OTP requests	/v2/user/otp/requests - one-time passwords for operations
WebSocket	Connection to wss://*/v2/updates for real-time updates

Where it’s stored

• Token is saved locally in the device’s secure storage (MMKV)
• Linked to a specific TON wallet address

When it’s deleted

1. 401 response from API - token expired or invalid
2. New invite code - when re-attempting registration by invitation
3. Migration - when updating token format (e.g., transition to TON+Solana)

After initial authentication and obtaining the User Token, the main interaction with Holders occurs through WebView with an embedded JavaScript Bridge.

Metrics and Analytics

The user onboarding process is covered by metrics on both the frontend and backend. Backend events are sent to Backoffice as well as to the Metabase service. Frontend events can be viewed and funnels can be built in the Mixpanel service.