Security & Recovery API

Security & Recovery API

Overview

Endpoints for wallet recovery operations and security validations. These endpoints help ensure wallet safety and provide recovery mechanisms when needed.

Recover Wallet

Restore access to a wallet using recovery methods.

POST api.bloclabs.com/v1/wallets/recover

Request

{
    "recovery_type": "SEED_PHRASE",  // SEED_PHRASE, MPC_SHARES, BACKUP_KEY
    "recovery_data": {
        "seed_phrase": "word1 word2 ... word12",  // For seed phrase recovery
        "passphrase": "optional_passphrase"       // Optional extra security
    },
    "new_device": {
        "device_id": "device_xyz789",
        "device_name": "iPhone 13 Pro",
        "os_version": "iOS 15.0",
        "app_version": "1.2.0"
    },
    "security_settings": {
        "enable_biometric": true,
        "enable_2fa": true
    }
}

Response

{
    "status": "success",
    "data": {
        "recovery_id": "recovery_abc123",
        "wallet_id": "wallet_xyz789",
        "address": "0x123...abc",
        "status": "RECOVERED",
        "recovery_method": "SEED_PHRASE",
        "timestamp": "2024-03-15T10:00:00Z",
        "security": {
            "biometric_enabled": true,
            "2fa_enabled": true,
            "device_registered": true
        }
    }
}

MPC Recovery

Recover an MPC wallet using distributed key shares.

POST api.bloclabs.com/v1/wallets/recover/mpc

Request

{
    "wallet_address": "0x123...abc",
    "key_shares": [
        "share_1_data",
        "share_2_data"
    ],
    "recovery_params": {
        "threshold": 2,
        "total_shares": 3
    },
    "new_device": {
        "device_id": "device_xyz789",
        "device_name": "iPhone 13 Pro",
        "os_version": "iOS 15.0"
    }
}

Response

{
    "status": "success",
    "data": {
        "recovery_id": "mpc_recovery_def456",
        "wallet_id": "wallet_xyz789",
        "status": "RECOVERED",
        "new_shares_generated": true,
        "security_level": "HIGH",
        "timestamp": "2024-03-15T10:00:00Z"
    }
}

Validate Address

Validate a blockchain address format and get additional information.

POST api.bloclabs.com/v1/wallets/validate-address

Request

{
    "address": "0x123...abc",
    "network": "ethereum",    // ethereum, polygon, binance
    "validation_type": "FULL" // BASIC, FULL
}

Response

{
    "status": "success",
    "data": {
        "address": "0x123...abc",
        "is_valid": true,
        "network": "ethereum",
        "address_type": "EOA", // EOA, CONTRACT
        "validation_details": {
            "checksum_valid": true,
            "format_valid": true,
            "network_compatible": true
        },
        "metadata": {
            "contract_type": null,     // For contract addresses
            "first_transaction": "2024-01-15T10:00:00Z",
            "last_transaction": "2024-03-15T10:00:00Z",
            "total_transactions": 150
        }
    }
}

Error Responses

Invalid Recovery Data

{
    "status": "error",
    "message": "Invalid recovery data provided",
    "code": "INVALID_RECOVERY_DATA",
    "data": {
        "reason": "Invalid seed phrase format",
        "expected_format": "12 or 24 words"
    }
}

Recovery Attempt Limit

{
    "status": "error",
    "message": "Too many recovery attempts",
    "code": "RECOVERY_ATTEMPT_LIMIT",
    "data": {
        "attempts_made": 3,
        "max_attempts": 3,
        "reset_after": "2024-03-15T11:00:00Z"
    }
}

Invalid Address

{
    "status": "error",
    "message": "Invalid blockchain address",
    "code": "INVALID_ADDRESS",
    "data": {
        "address": "0x123...abc",
        "network": "ethereum",
        "validation_errors": [
            "Invalid checksum",
            "Incorrect length"
        ]
    }
}

Security Recommendations

Recovery Best Practices

1. Store recovery phrases securely offline

2. Use multiple recovery methods when possible

3. Test recovery process periodically

4. Keep backup devices registered

5. Enable all security features after recovery

Address Validation Best Practices

1. Always validate addresses before transactions

2. Use FULL validation for large transfers

3. Check network compatibility

4. Verify contract addresses against known lists

5. Implement address whitelisting for frequent transfers

Notes

• Recovery operations require additional verification

• Address validation is network-specific

• MPC recovery requires minimum threshold of shares

• Keep recovery codes and backup devices secure

• Regular security audits recommended