Authentication
SIWE session auth and API-key management for public integrations
Diffusal supports two authentication paths: Dynamic.xyz for the trading app, and raw SIWE for programmatic integrations.
Trading App Authentication (Dynamic.xyz)
The Diffusal trading app at app.diffusal.xyz uses Dynamic.xyz for wallet connection and session management. This is the recommended path for traders.
- Click Connect Wallet in the trading app navigation
- Dynamic.xyz presents a wallet selection modal supporting MetaMask, Coinbase Wallet, and other EIP-1193 wallets
- Select your wallet and approve the connection
- Dynamic.xyz internally handles SIWE signing and issues a JWT
- The JWT authenticates all subsequent API calls from the app
For a step-by-step guide, see Setting Up Your Wallet.
For programmatic integrations (market makers, bots, API users), use the SIWE endpoints documented below.
API Integrator Authentication (SIWE)
Session Auth Endpoints
| Endpoint | Method | Description |
|---|---|---|
/api/auth/nonce | POST | Generate nonce for SIWE message |
/api/auth/verify | POST | Verify SIWE signature + create session |
/api/auth/session | GET | Get current authenticated session |
/api/auth/signout | POST | Sign out and delete session |
Session Flow
- Request SIWE nonce (
POST /api/auth/nonce) - Sign SIWE message with wallet
- Verify signature (
POST /api/auth/verify) - Receive session cookie + bearer token
- Access protected routes (
/api/account/*,/api/points/*,/api/mm/*,/api/portfolio/*,/api/strategies/*)
REST/Auth Notes
- Browser clients are cookie-first.
- Bearer tokens are supported for non-browser workflows.
- SIWE chain ID and domain should match your active environment.
API Keys
Scoped API keys support programmatic authenticated integrations alongside SIWE session auth.
Manage API keys through:
| Endpoint | Method | Description |
|---|---|---|
/api/keys | POST | Create a new scoped API key |
/api/keys | GET | List active API keys |
/api/keys/:keyId | DELETE | Revoke an API key |
/api/keys/:keyId/rotate | POST | Rotate an API key secret |
Scopes currently supported are read, trade, and withdraw.
API Key Authentication Headers
Authenticated requests require three headers:
| Header | Description |
|---|---|
X-API-Key | Your key ID (e.g. dfsl_abc123...) |
X-API-Timestamp | Current time in milliseconds since epoch |
X-API-Signature | HMAC-SHA256 of the timestamp using your secret |
The timestamp must be within 30 seconds of the server's current time. See Rate Limits for full details on API key auth, code examples, and tiered rate limits.
API Keys on Public Endpoints
API key headers can also be sent on unauthenticated public endpoints (e.g. /api/markets/*) to receive higher rate limits. Invalid or missing API key headers are silently ignored — the request falls back to IP-based limits.
Public Realtime Notes
The public WebSocket documentation covers the public stream surface only. Contributor-only realtime authentication and routing details are intentionally excluded from the public docs route.
Security Model
- Nonce-based replay protection
- Signed ownership proof via SIWE
- Session validation on protected REST endpoints
- Scoped API key authentication for supported programmatic integrations
- HMAC-SHA256 signature verification with 30-second timestamp window
- Additional non-public realtime authorization details are documented only in contributor references