Verifying a wallet through the API ensures that investors’ digital assets are securely linked and compliant with both regulatory and internal requirements. As an API integrator, you’ll orchestrate a sequence of API calls to handle investor creation, account setup, wallet verification, and retrieval.

📘

Prerequisites:

To complete this use case, you will need to authenticate your request(s). You can generate your token by following these steps:

• Make sure to leverage an existing account from the correct role, e.g. Agent, Owner, Investor, etc.
• If this use case requires you to leverage an Agent account, make sure your 2FA is disabled via the Servicing portal.
• Navigate to the "Getting API access" page to generate the required JWT, thanks to your credentials.
• Add the JWT to the header of your request.

 Wallet Verification Flow

 Step 1: Import and qualify investors

Register one or more investors for a given token in the servicing system. It replaces the manual CSV upload and allows programmatic investor onboarding. Investors created here are automatically whitelisted for the specified tokenId.

Please make sure that the investor’s wallet will be qualified following this guide.

Note: Ensure the same email is later used when creating the investor’s account.

Step 2: Create an Account

This endpoint creates an investor account using the same email address from Step 1. The account allows to create an account on Tokeny’s side for the investor, allowing you to call Investor endpoints, including proceeding to the wallet verification.

POST https://api.tokeny.com/servicing/api/accounts

Note: Account creation must be completed before wallet verification.

 Step 3: Retrieve the investor's information

This endpoint is necessary to retrieve the ssoId that will be used in the next step.

GET https://api.tokeny.com/onchainid/v1/api/identity

Response example:

{  
  "identityId": "string",  
  "ssoId": "string",  
  "onchainIdAddress": "string",  
  "status": "string",  
  "onchainIdAddresses": [  
    {  
      "address": "string",  
      "status": "NOT_DEPLOYED",  
      "network": "string"  
    }  
  ]  
}

 Step 4: Create & Verify Wallet

This endpoint registers and verifies an investor’s wallet address. Verification typically involves signing a Proof of Ownership message to confirm control over the wallet.

As Tokeny, we need to add link between the ONCHAINID and the wallet in order to have the wallet verified.

POST https://api.tokeny.com/onchainid/v1/api/wallets

Notes:

• A verified wallet ensures that only the rightful wallet owner can transact.
• If a wallet address was imported in Step 1, ensure it matches the verified address.

Request body example:

{  
  "ssoId": "string",  
  "walletAddress": "string",  
  "provider": "string",
	"signature": "string"
}

Field details:

• ssoId — Investor's unique ssoId.
• provider — Add USER_MANAGED as investor’s wallet provider.
• walletAddress (mandatory) — The wallet address of the investor performing the transaction.
• signature — The signed transactionData proving the investor’s control of the provided wallet address. Please send the transactionData of the following signed message with the investor wallet: “Proof of ownership: I hereby declare I am the owner of the wallet: ${walletAddress}". Refer to the guide based on the specific sign and broadcast solution your API integration requires by visiting the following link: Blockchain signature flow.

Response example:

{  
  "identityId": "string",  
  "walletAddress": "string",  
  "provider": "string",  
  "externalReference": "string",  
  "signature": "string",  
  "source": "string",  
  "verified": true
}

 Step 5: Get Investor’s Wallets

This endpoint retrieves all wallets associated with a specific investor, identified by their identity ID. It is typically used to confirm wallet linkage or display wallet information in an application.

GET https://api.tokeny.com/onchainid/v1/api/wallets

Query parameters example:

GET https://api.tokeny.com/onchainid/v1/api/wallets?identityId=abcd-1234

Response example:

[  
  {  
    "walletAddress": "0xabc123...",  
    "status": "verified",  
    "createdAt": "2025-08-10T14:32:00Z"  
  },  
  {  
    "walletAddress": "0xdef456...",  
    "status": "pending",  
    "createdAt": "2025-08-11T09:15:00Z"  
  }  
]

Notes:

• Only wallets linked to the provided identityId will be returned.
• Response may include multiple wallet entries if the investor has more than one.