Authentication

Examples

• JavaScript / TypeScript

Connection

Connect to the WebSocket server:

wss://api.staging.rise.trade/ws

Authentication

Authenticate after opening the WebSocket connection and before subscribing to private channels. The WebSocket service supports two auth flows:

Version 2: Server-Issued Nonce

┌──────────────────────────────────────────────────────────┐
│              EIP712 v2 Auth Flow (recommended)           │
│                                                          │
│  Client                                  Server          │
│    │                                       │             │
│    │  GET /v1/auth/nonce                   │             │
│    ├─────────────────────────────────────▶│             │
│    │  { nonce: "deadbeef..." }             │             │
│    │◀─────────────────────────────────────┤             │
│    │                                       │             │
│    │  auth(account, signer, message,       │             │
│    │       nonce: "deadbeef...", sig)      │             │
│    ├─────────────────────────────────────▶│             │
│    │                                  ┌────┴────┐        │
│    │                                  │ Consume │        │
│    │                                  │ nonce,  │        │
│    │                                  │ Verify  │        │
│    │                                  │ RegV2   │        │
│    │                                  │ + chain │        │
│    │                                  └────┬────┘        │
│    │  auth_response(success)               │             │
│    │◀─────────────────────────────────────┤             │
│    │                                       │             │
│                                                          │
└──────────────────────────────────────────────────────────┘

Use v2 for new EIP-712 WebSocket clients.

1. Fetch a one-time nonce from GET /v1/auth/nonce.
2. Sign EIP-712 typed data with primary type RegisterV2.
3. Send auth_v2 with the signed payload.

The nonce returned by GET /v1/auth/nonce is a 32-byte lowercase hex string. It expires after 5 minutes and can only be used once.

{
  "data": {
    "nonce": "deadbeefcafebabe0123456789abcdef0123456789abcdef0123456789abcdef"
  },
  "request_id": "6f0ee654-a5ae-4767-bffd-2203dd6f33e4"
}

Auth Request

{
  "method": "auth_v2",
  "params": {
    "account": "0x1234...abcd",
    "signer": "0x5678...efgh",
    "message": "WebSocket Authentication",
    "nonce": "deadbeefcafebabe0123456789abcdef0123456789abcdef0123456789abcdef",
    "signature": "0xabcdef..."
  }
}

Parameters

• account (string, required): User's main Ethereum account address
• signer (string, required): Authorized session key address (must be registered on-chain)
• message (string, required): Human-readable message that was signed
• nonce (string, required): Server-issued nonce from GET /v1/auth/nonce
• signature (string, required): EIP712 signature in hex format with 0x prefix

EIP712 Typed Data Structure

Use the EIP-712 domain returned by GET /v1/auth/eip712-domain.

{
  "domain": {
    "name": "<from GET /v1/auth/eip712-domain>",
    "version": "<from GET /v1/auth/eip712-domain>",
    "chainId": "<from GET /v1/auth/eip712-domain>",
    "verifyingContract": "<from GET /v1/auth/eip712-domain>"
  },
  "primaryType": "RegisterV2",
  "types": {
    "EIP712Domain": [
      {"name": "name", "type": "string"},
      {"name": "version", "type": "string"},
      {"name": "chainId", "type": "uint256"},
      {"name": "verifyingContract", "type": "address"}
    ],
    "RegisterV2": [
      {"name": "signer", "type": "address"},
      {"name": "message", "type": "string"},
      {"name": "nonce", "type": "uint256"}
    ]
  },
  "message": {
    "signer": "0x5678...efgh",
    "message": "WebSocket Authentication",
    "nonce": "0xdeadbeefcafebabe0123456789abcdef0123456789abcdef0123456789abcdef"
  }
}

The WebSocket request may send the v2 nonce with or without a 0x prefix. The server normalizes it before verification.

Version 1: Legacy Timestamp Nonce

The v1 flow is kept for backward compatibility. New clients should use v2.

{
  "method": "auth",
  "params": {
    "account": "0x1234...abcd",
    "signer": "0x5678...efgh",
    "message": "WebSocket Authentication",
    "nonce": 1703123456,
    "signature": "0xabcdef..."
  }
}

For v1, sign EIP-712 primary type Register(address signer, string message, uint64 nonce). The nonce is a Unix timestamp in seconds and must be within 60 seconds of server time.

Authentication Response

Success:

{
  "method": "auth_v2",
  "status": "success",
  "message": "Authentication successful",
  "data": {
    "account": "0x1234...abcd",
    "signer": "0x5678...efgh"
  }
}

Error:

{
  "method": "auth_v2",
  "status": "error",
  "message": "authentication failed: session key not active (status: NotExist)",
  "data": {}
}

Verification Steps

For EIP-712 auth, the server performs the following checks:

1. Nonce validation: v2 consumes the server-issued nonce; v1 checks the timestamp window
2. Signature verification: Recovers signer address from EIP712 signature
3. Address matching: Recovered address must match provided signer address
4. On-chain validation: Calls authContract.GetSessionKeyStatus(account, signer)
5. Status check: Session key status must be 1 (Active)
   • 0 = NotExist (signer not registered)
   • 1 = Active (authorized)
   • 2 = Revoked (was active but revoked)