Verify wallet login

POST /api/auth/verify

Complete the wallet login flow. Provide the messageId from POST /api/auth/message and the wallet's EIP-191 signature over the message. On success the account is created if it does not exist yet and a JWT is issued; send it as an Authorization Bearer header to endpoints that accept JWT authentication. Each message can be verified only once.

Request body (application/json)

{
  "messageId": "68fa3450539a3c9d28bbca35",
  "signature": "0x2f8e6a1c4b7d9e0f3a5c7e9b1d4f6a8c0e2b4d6f8a0c2e4b6d8f0a2c4e6b8d0f1a3c5e7b9d0f2a4c6e8b0d2f4a6c8e0b2d4f6a8c0e2b4d6f8a0c2e4b6d8f0a1b"
}

Responses

Status	Description
200	Signature valid; JWT issued.
401	Verification failed. Plausible codes: AUTH_006 (unknown or already-used messageId), AUTH_007 (message expired), AUTH_008 (the signature does not recover to the address that requested the message).
500	Server error. Plausible codes: SYSTEM_001.

200 response

{
  "success": true,
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiI2OGMyNzU4NDZhNmJhMWM5YTIxOThhOGMifQ.sflKxwRJSMeKKF2QT4fwpMeJf36POk6yJVadQssw5c",
    "userId": "68c275846a6ba1c9a2198a8c"
  },
  "timestamp": "2026-07-29T12:34:56.789Z"
}

401 response

{
  "success": false,
  "error": {
    "code": "AUTH_008",
    "message": "Invalid wallet signature",
    "category": "AUTH",
    "traceId": "6f2c1e0a-8b4d-4c1e-9f3a-2d5b7c8e9a01"
  },
  "timestamp": "2026-07-29T12:34:56.789Z"
}

500 response

{
  "success": false,
  "error": {
    "code": "SYSTEM_001",
    "message": "Database operation failed",
    "category": "SYSTEM",
    "traceId": "6f2c1e0a-8b4d-4c1e-9f3a-2d5b7c8e9a01"
  },
  "timestamp": "2026-07-29T12:34:56.789Z"
}