docs: clarify device auth compatibility

Author: gemcoder21

docs/DEVICE_AUTHENTICATION.md

@@ -2,68 +2,72 @@
 
 ## Overview
 
-All `/v2/devices/*` endpoints require authentication via Ed25519 request signing. The server supports two authentication methods: **Gem** (recommended) and **individual headers** (legacy).
+All `/v2/devices/*` endpoints require Ed25519 request signing. New clients should use the Gem `Authorization` header. Individual `x-device-*` headers remain supported for existing clients and should be treated as legacy compatibility.
 
-## Method 1: Gem Authorization Header (Recommended)
+## Gem Authorization Header
 
 ```
 Authorization: Gem base64(<device_id_hex>.<timestamp_ms>.<wallet_id>.<body_hash_hex>.<signature_hex>)
 ```
 
-The payload is always 5 dot-separated parts. After base64-decoding:
+The decoded payload is always 5 dot-separated parts:
 - `device_id_hex` - 64-character hex Ed25519 public key
 - `timestamp_ms` - Unix timestamp in milliseconds
-- `wallet_id` - Wallet identifier (empty string for non-wallet endpoints)
-- `body_hash_hex` - 64-character hex SHA256 hash of request body
+- `wallet_id` - wallet identifier, or an empty string for non-wallet endpoints
+- `body_hash_hex` - 64-character hex SHA256 hash of the request body
 - `signature_hex` - 128-character hex Ed25519 signature
 
-When `wallet_id` is empty, the payload contains `..` (two consecutive dots).
+When `wallet_id` is empty, the payload contains `..` between timestamp and body hash.
 
 **Signed message:**
+
 ```
 {timestamp}.{method}.{path}.{walletId}.{bodyHash}
 ```
 
-`walletId` is empty for non-wallet endpoints, producing `..` in the message:
+Examples:
 
 ```
 1706000000000.GET./v2/devices..e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
 1706000000000.GET./v2/devices/assets.multicoin_0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb.e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
 ```
 
-## Method 2: Individual Headers (Legacy)
+## Legacy Individual Headers
 
-**Required:**
-- `x-device-id`: Unique device identifier (64-character hex Ed25519 public key)
-- `x-device-signature`: Ed25519 signature (hex or base64)
-- `x-device-timestamp`: Unix timestamp in milliseconds
-- `x-device-body-hash`: SHA256 hash of request body (hex)
+The server still accepts individual headers for compatibility:
 
-**Optional (wallet-specific endpoints):**
-- `x-wallet-id`: Wallet identifier (format: `multicoin_{address}`)
+- `x-device-id`: 64-character hex Ed25519 public key
+- `x-device-signature`: Ed25519 signature, hex or base64
+- `x-device-timestamp`: Unix timestamp in milliseconds
+- `x-device-body-hash`: 64-character hex SHA256 hash of the request body
+- `x-wallet-id`: wallet identifier for wallet-scoped endpoints
 
 **Signed message:**
+
 ```
 v1.{timestamp}.{method}.{path}.{bodyHash}
 ```
 
-Note: `walletId` is **not** included in the legacy signed message.
+The legacy signed message does not include `walletId`; new clients should not add new dependencies on this format.
 
 ## Request Examples
 
-### Gem (wallet-scoped)
+### Gem Wallet-scoped Endpoint
+
 ```http
 GET /v2/devices/assets?from_timestamp=1234567890
 Authorization: Gem base64(abc123...def456.1706000000000.multicoin_0x742d...f0bEb.e3b0c44...b855.aabb11...)
 ```
 
-### Gem (no wallet)
+### Gem Non-wallet Endpoint
+
 ```http
 GET /v2/devices
 Authorization: Gem base64(abc123...def456.1706000000000..e3b0c44...b855.aabb11...)
 ```
 
-### Individual Headers (legacy)
+### Legacy Individual Headers
+
 ```http
 GET /v2/devices/assets?from_timestamp=1234567890
 x-device-id: abc123...def456
@@ -77,5 +81,5 @@ x-device-body-hash: e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852
 
 - Request signature verification: [`apps/api/src/devices/signature.rs`](../apps/api/src/devices/signature.rs)
 - Cryptographic verification: [`crates/gem_auth/src/device_signature.rs`](../crates/gem_auth/src/device_signature.rs)
-- Request guards: [`apps/api/src/devices/guard.rs`](../apps/api/src/devices/guard.rs)
+- Request guards: [`apps/api/src/devices/guard/`](../apps/api/src/devices/guard/)
 - Error handling: [`apps/api/src/devices/error.rs`](../apps/api/src/devices/error.rs)

docs/WALLET_AUTHENTICATION.md

@@ -29,9 +29,13 @@ Wallet authentication endpoints require proof of wallet ownership via blockchain
 }
 ```
 
-**Required Headers:**
+Wallet-authenticated requests are still device-authenticated requests. Use the Gem `Authorization` header for device authentication where possible; existing clients may still use the legacy individual headers documented in [Device Authentication](DEVICE_AUTHENTICATION.md).
+
+For the current `WalletSigned<T>` guard, include:
 - `x-device-body-hash`: SHA256 hash of request body (hex)
 
+This binds the wallet-signed JSON body to the request body read by the guard. Moving this check fully into the Gem `Authorization` payload should be done with the legacy-removal PR.
+
 ## Nonce Request
 
 **Endpoint:**
@@ -72,6 +76,7 @@ GET /v2/devices/auth/nonce
 ```
 POST https://api.gemwallet.com/v2/devices/rewards/referrals/create
 Content-Type: application/json
+Authorization: Gem base64(<device_id_hex>.<timestamp_ms>.<wallet_id>.<body_hash_hex>.<signature_hex>)
 x-device-body-hash: a1b2c3d4e5f6...
 
 {