Skip to main content

🧵 Create and Register a Valid Investor Account

Welcome to the complete guide for the "Create and Register a Valid Investor Account" workflow for the Token City Blockchain API.

This workflow enables you to create a custodian account for an investor, generate and register an on-chain identity, and add the necessary verifications, ensuring their proper integration into the investment platform.

🌟 Objective: Secure and automated onboarding of investors into the Token City ecosystem.

📚 OpenAPI Documentation​

✨ Workflow Summary​

This workflow automates the process of creating a valid investor on Token City and blockchain:

  1. 🔹 Create a custodian account in Venly / Onyze.
  2. 🔹 Create an on-chain identity.
  3. 🔹 Register that identity.
  4. 🔹 Add individual verifications (claims).

📋 Workflow Steps Table​

StepAPI OperationMethodParametersOutputsDescription
Add Custodian AccountPOST /accounts-accountDetailsaccountIdCreates the investor's account in Venly custodian
Create On-Chain IdentityPOST /on-chain-identity-accountIdonChainIdCreates an on-chain identity linked to the account
Register On-Chain IdentityPOST /on-chain-identity/{identityAddress}/register-identityAddress, accountAddress-Registers the newly created on-chain identity
Add Individual ClaimsPOST /on-chain-identity/{identityAddress}/claims-identityAddress, claimData-Adds verified claims to the identity profile

🎨 Workflow Visualizations​

🌊 Mermaid Sequence Diagram​

📝 Step-by-Step Implementation​

Step 1: Create Custodian Account​

Create a custodian account for the investor in the Venly/Onyze wallet system.

Endpoint: POST /accounts

Response:

{
  "id": "0x1234567890abcdef1234567890abcdef12345678",
  "passcode": "001234",
  "emergencyCode": "0sFDf422dhF"
}

The response includes the accountId, passcode and emergencyCode. The accountId parameter it's the blockchain address. The passcodeand emergencyCodeparameters are usedtosign transactions.

Step 2: Create On-Chain Identity​

Create an on-chain identity contract for the investor.

Endpoint: POST /on-chain-identity

Request Body:

{
  "accountId": "0x1234567890abcdef1234567890abcdef12345678"
}

Response:

{
  "result": {
    "identityContractAddress": "0xC593e77451cE7009209Ea4e7F62d64F2355D71ff",
    "identityContractId": "6585b5fb-8de8-452d-aa96-8e5de0f1ca09",
    "walletLinked": "0x123456A9571241e97cDb61E3FfD1937D885454dd"
  }
}

Wait for the transaction to be mined before proceeding to the next step.

Step 3: Register On-Chain Identity​

Register the newly created identity in the identity registry.

Endpoint: POST /on-chain-identity/{identityAddress}/register

Path Parameters:

  • identityAddress: The identity contract address from Step 2

Request Body:

{
  "walletAddress": "0x1234567890abcdef1234567890abcdef12345678",
  "countryCode": "724"
}

Request Parameters:

  • walletAddress: The wallet address from Step 1
  • country: ISO 3166-1 country code

Response:

{
  "id": "123e4567-e89b-12d3-a456-426614174000"
}

Step 4: Add Individual Claims​

Add verified claims (KYC/AML verifications) to the identity.

Endpoint: POST /on-chain-identity/{identityAddress}/claims

Path Parameters:

  • identityAddress: The identity contract address from Step 2

Request Body:

{
  "claimType": "KYC",
  "claimData": {
    "status": "ACCEPTED",
    "date": "07-03-2024"
  }
}

Common Claim Types:

  • 1: KYC/AML verification
  • 2: KYB verification

Response:

{
  "transactionId": "6585b5fb-8de8-452d-aa96-8e5de0f1ca09",
  "success": true,
  "claimId": "0x15564486549685416dfg6fd84gvd6f8g46df54AAA52DF",
  "message": "Transaction sent, check webhook for confirmation"
}

💡 Key Concepts​

What is an On-Chain Identity?​

An on-chain identity is a smart contract that:

  • Represents a user's identity on the blockchain
  • Stores verified claims (credentials) issued by trusted authorities
  • Enables compliant token transfers by proving investor eligibility
  • Is compatible with the ERC-3643 standard for tokenized securities

Identity Verification Flow​

  1. Account Creation: Custodian wallet is created for secure key management
  2. Identity Deployment: Smart contract identity is deployed and linked to the wallet
  3. Registration: Identity is registered in the token's identity registry
  4. Claims Addition: KYC/AML verifications are added as on-chain claims

Claim Types Explained​

Claims are verifiable on-chain credentials issued by trusted claim issuers:

  • KYC Claims: Verify the investor's identity
  • AML Claims: Confirm anti-money laundering checks passed

⚠️ Important Notes​

  1. PIN Code Security: Store the PIN code securely; it's required for account recovery
  2. Sequential Steps: Each step must complete before proceeding to the next
  3. Transaction Confirmation: Wait for transactions to be mined before continuing
  4. Claim Issuers: Only authorized claim issuers can add valid claims
  5. Identity Registry: The identity must be registered before token transfers are allowed
  6. Country Codes: Use ISO 3166-1 country code (e.g., "721","724")
  7. Gas Costs: Each on-chain operation requires gas fees

🔗 Related Endpoints​

🆘 Troubleshooting​

Identity Registration Failed​

If identity registration fails, check:

  • ✓ Identity contract was successfully deployed in Step 2
  • ✓ Account address matches the one from Step 1
  • ✓ Valid country code is provided (ISO 3166-1)
  • ✓ Identity is not already registered

Claim Addition Failed​

If adding claims fails:

  • ✓ Identity is registered in Step 3
  • ✓ Claim data is properly formatted
  • ✓ Claim type is supported by the token

Token Transfer are Failing​

If transfers are failing after setup:

  • ✓ All steps completed successfully
  • ✓ Required claims are added (minimum: KYC + Country)
  • ✓ Claims are not expired
  • ✓ Investor meets token's eligibility criteria
  • ✓ Receiving address also has valid identity (for compliant tokens)

📚 Additional Resources​

💼 Use Case Example​

Individual Retail Investor Onboarding​

An individual investor from Spain wants to purchase tokenized securities:

Step 1 - Account Creation:

Step 2 - Identity Creation: Identity contract deployed at: 0xabc...def

Step 3 - Registration:

{
  "walletAddress": "0x123...456",
  "countryCode": "724"
}

Step 4 - Add KYC Claim:

{
  "claimType": KYC,
  "claimData": {
    "status": "ACCEPTED",
    "date": "07-03-2025"
  }
}

Result: Investor can now receive and trade compliant security tokens that accept Spanish retail investors.