Registering and Linking a Verified 1st Party Wallet

Overview

Verifying wallet ownership enables:

• Higher transaction limits for withdrawals to your customer's verified wallet
• Reduced compliance friction for future transactions
• Streamlined withdrawal process to trusted destinations

Prerequisites

• Existing blockchain account (see Creating a Blockchain Account)
• Self-hosted wallet (MetaMask, Phantom, etc.)

Process Overview

The verification process involves three main steps:

1. Register the counterparty - Add the wallet address to the system
2. Create ownership challenge - Generate a cryptographic challenge
3. Complete verification - Sign and submit the challenge response

Step 1: Register the Counterparty

First, register the wallet address as a counterparty:

POST /counterparties
Authorization: Bearer {your-api-key}
Content-Type: application/json

{
  "address": "9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM",
  "network": "solana"
}

Request Parameters

Example Response

{
  "type": "counterparty",
  "id": "CPT_01BX5ZZKBKACTAV9WEVGEMMVS1",
  "network": "solana",
  "address": "9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM"
}

Save the counterparty ID for the next steps.

Step 2: Create Ownership Challenge

Generate a cryptographic challenge that your customer will need to sign:

POST /blockchain-accounts/{blockchain-account-id}/1P-counterparty-ownership-challenges
Authorization: Bearer {your-api-key}
Content-Type: application/json

{
  "counterpartyId": "CPT_01BX5ZZKBKACTAV9WEVGEMMVS1"
}

Example Response

{
  "id": "CHG_01BX5ZZKBKACTAV9WEVGEMMVS1",
  "challenge": "Please sign this message to verify ownership: 0x1234567890abcdef..."
}

Step 3: Sign the Challenge

Present the challenge to the customer for signature:

For Solana Wallets (Phantom, Solflare, etc.)

// Example using Phantom wallet
const message = 'Please sign this message to verify ownership: 0x1234567890abcdef...';
const encodedMessage = new TextEncoder().encode(message);
const signature = await window.solana.signMessage(encodedMessage, 'utf8');

For Ethereum Wallets (MetaMask, etc.)

// Example using MetaMask
const message = 'Please sign this message to verify ownership: 0x1234567890abcdef...';
const signature = await ethereum.request({
  method: 'personal_sign',
  params: [message, accounts[0]],
});

Step 4: Submit the Signed Challenge

Complete the verification by submitting the signature:

POST /blockchain-accounts/{blockchain-account-id}/1P-counterparty-ownership-claims
Authorization: Bearer {your-api-key}
Content-Type: application/json

{
  "challengeId": "CHG_01BX5ZZKBKACTAV9WEVGEMMVS1",
  "completedChallenge": "signature_data_here",
  "counterpartyId": "CPT_01BX5ZZKBKACTAV9WEVGEMMVS1"
}

If the completed challenge passes, the response will return an ownership claim. Save this claim id for the next step.

Request Parameters

Example Response

{
  "id": "CLM_01BX5ZZKBKACTAV9WEVGEMMVS1"
}

Step 5: Add Counterparty to Your Blockchain Account

Link the counterparty to the blockchain account:

POST /blockchain-accounts/{blockchain-account-id}/counterparties
Authorization: Bearer {your-api-key}
Content-Type: application/json

{
  "address": "9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM",
  "network": "solana",
  "ownershipClaimId": "CLM_01BX5ZZKBKACTAV9WEVGEMMVS1"
}

Request Parameters

Step 6: Verify Success

Check that the wallet is now verified by listing the account's counterparties:

GET /blockchain-accounts/{blockchain-account-id}/counterparties
Authorization: Bearer {your-api-key}

Example Response

{
  "data": [
    {
      "type": "VerifiedCounterparty1P",
      "id": "CPT_01BX5ZZKBKACTAV9WEVGEMMVS1",
      "address": "9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM"
    }
  ],
  "pagination": {
    "total": 1,
    "page": 1,
    "limit": 20
  }
}

Benefits of Verification

Once verified, the wallet becomes a VerifiedCounterparty1P, which provides:

• Higher transaction limits for withdrawals
• Faster processing due to reduced compliance checks

Troubleshooting

Challenge Expired

If your challenge expires, create a new one:

POST /blockchain-accounts/{id}/1P-counterparty-ownership-challenges

Invalid Signature

Common causes:

• Wrong message format
• Incorrect wallet address
• Network mismatch
• Expired challenge

Wallet Not Connecting

Ensure:

• Wallet extension is installed and unlocked
• Website permissions are granted
• Correct network is selected

Re-verification

You may need to ask the customer to re-verify if:

• Security policies require periodic re-verification
• Suspicious activity is detected
• Compliance requirements change

API Reference

• Register Counterparty: POST /counterparties
• Link Counterparty: POST /blockchain-accounts/{id}/counterparties
• Create Challenge: POST /blockchain-accounts/{id}/1P-counterparty-ownership-challenges
• Submit Proof: POST /blockchain-accounts/{id}/1P-counterparty-ownership-claims
• List Verified: GET /blockchain-accounts/{id}/counterparties