Signing Operations API

Overview

Endpoints for creating secure signing sessions and signing blockchain messages or transactions. These operations ensure secure transaction authorization and message authentication.

Create Signing Session

Initialize a secure session for transaction or message signing.

POST api.bloclabs.com/v1/wallets/{wallet_id}/sign

Request

{
    "type": "TRANSACTION",      // TRANSACTION, MESSAGE
    "expiry_minutes": 15,       // Optional: Session expiry (default: 15)
    "biometric_required": true, // Optional: Require biometric auth
    "metadata": {              // Optional: Additional session data
        "app_name": "Trading App",
        "source": "mobile"
    }
}

Response

{
    "status": "success",
    "data": {
        "session_id": "sign_session_xyz789",
        "expires_at": "2024-03-15T10:15:00Z",
        "status": "PENDING",
        "verification_code": "123456",  // For 2FA verification
        "qr_code": "data:image/png;base64,...",  // For QR scanning
        "security_level": "HIGH"
    }
}

Sign Message

Sign a message using wallet's private key.

POST api.bloclabs.com/v1/wallets/{wallet_id}/sign-message

Request

{
    "message": "Welcome to BlocLabs! Click to sign in.",
    "session_id": "sign_session_xyz789",
    "format": "TEXT",          // TEXT, HEX
    "verification_code": "123456"  // If 2FA is enabled
}

Response

{
    "status": "success",
    "data": {
        "signature": "0x1234...5678",
        "signed_by": "0x123...abc",
        "signed_at": "2024-03-15T10:01:00Z",
        "signature_type": "EIP191",
        "verification": {
            "message": "Welcome to BlocLabs! Click to sign in.",
            "address": "0x123...abc",
            "valid": true
        }
    }
}

Sign Transaction

Sign a transaction without broadcasting it.

POST api.bloclabs.com/v1/wallets/{wallet_id}/sign-transaction

Request

{
    "session_id": "sign_session_xyz789",
    "transaction": {
        "to": "0x789...def",
        "value": "1.5",
        "asset": "ETH",
        "gas_limit": "21000",
        "max_fee_per_gas": "50",
        "max_priority_fee": "2",
        "nonce": 5,
        "data": "0x..."  // Optional: Contract interaction data
    },
    "verification_code": "123456"  // If 2FA is enabled
}

Response

{
    "status": "success",
    "data": {
        "signed_transaction": "0x...",
        "transaction_hash": "0xabc...123",
        "signed_by": "0x123...abc",
        "signed_at": "2024-03-15T10:01:00Z",
        "expiry": "2024-03-15T10:16:00Z",
        "chain_id": 1
    }
}

Verify Signature

Verify a signed message or transaction.

POST api.bloclabs.com/v1/wallets/verify-signature

Request

{
    "signature": "0x1234...5678",
    "message": "Welcome to BlocLabs! Click to sign in.",
    "address": "0x123...abc",
    "format": "TEXT"
}

Response

{
    "status": "success",
    "data": {
        "valid": true,
        "signer": "0x123...abc",
        "signature_type": "EIP191",
        "signed_at": "2024-03-15T10:01:00Z"
    }
}

Error Responses

Session Expired

{
    "status": "error",
    "message": "Signing session expired",
    "code": "SESSION_EXPIRED",
    "data": {
        "expired_at": "2024-03-15T10:15:00Z"
    }
}

Invalid Verification Code

{
    "status": "error",
    "message": "Invalid verification code",
    "code": "INVALID_VERIFICATION",
    "data": {
        "attempts_remaining": 2
    }
}

Unauthorized Signing

{
    "status": "error",
    "message": "Unauthorized signing attempt",
    "code": "UNAUTHORIZED_SIGNING",
    "data": {
        "required_auth": "BIOMETRIC"
    }
}

Notes

• Signing sessions expire after 15 minutes by default

• Always verify the message/transaction before signing

• Use appropriate security levels based on transaction value

• Keep verification codes confidential

• Consider implementing transaction value limits