Start wallet login

POST /api/auth/message

Start the wallet login flow. Provide a wallet address and receive a one-time message to sign, its messageId, and its expiry (Unix seconds). Sign the message with the wallet (EIP-191 personal_sign) and exchange the signature for a JWT via POST /api/auth/verify. The message expires after 5 minutes and can be used once.

Request body (application/json)

{
  "address": "0xA7A833e6641D7901F30EaD6f27d4Ee2C9bb670a7"
}

Responses

Status	Description
200	The message to sign.
400	Invalid request. Plausible codes: USER_003 (the address does not parse as a valid wallet address).
500	Server error. Plausible codes: SYSTEM_001.

200 response

{
  "success": true,
  "data": {
    "message": "Sign in to Photon\nAddress: 0xa7a833e6641d7901f30ead6f27d4ee2c9bb670a7\nNonce: 3f9a1c7e2b8d4a6c9e0f2b4d6a8c0e2f\nExpires: 1753795500",
    "messageId": "68fa3450539a3c9d28bbca35",
    "expiry": 1753795500
  },
  "timestamp": "2026-07-29T12:34:56.789Z"
}

400 response

{
  "success": false,
  "error": {
    "code": "USER_003",
    "message": "Invalid user address",
    "category": "USER",
    "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"
}