Skip to main content
useAuth wraps the SDK’s wallet-authorized session-key flow. login() generates a session key, prompts the wallet once, and (via the provider) persists the session; every subsequent request is signed automatically. There are no access or refresh tokens. See TypeScript authentication for the lower-level SDK model.

Authentication State

AuthenticationStatus
Current authentication state:
  • "unauthenticated" - Not logged in
  • "authenticating" - Login in progress
  • "authenticated" - Session active

Core Actions

() => Promise<AuthState>
Authenticate the user with a wallet signature, using the address and clientId from context. Returns an AuthState (with the session keypair). Takes no arguments — the wallet and clientId come from the provider.WebSocket channels are connected separately; login() does not open any connection. Public channels (OHLCV, Orderbook, Trades) don’t require authentication.
() => Promise<void>
Revoke the session on the server and clear local auth state.
() => Promise<AuthState>
Extend the current session’s expiry. The keypair is unchanged; returns the updated AuthState.

Session Actions

() => Promise<SessionRefreshResponse>
Lower-level refresh that returns just the new expiresAt. refreshAuth() wraps this and updates the stored AuthState.
() => Promise<void>
Revoke the current session on the server without clearing local React state (logout() does both).

Advanced Building Blocks

login / authenticate run these internally and manage the session keypair for you. Use them directly only for custom flows.
() => Promise<AuthState>
The programmatic equivalent of login() — generates the session key, prompts the wallet, verifies, and returns the AuthState.
(message: string) => Promise<string>
Ask the connected wallet to authorize a challenge message. Returns a hex signature — EIP-191 from an EOA, or an EIP-1271 contract signature from a smart-contract wallet such as a Safe. Submit it unchanged; do not assume the 65-byte EOA shape. Server-side EIP-1271 verification is deliberately narrow: it is offered only to a wallet holding a BuilderCodes payout bucket, on a deployment with the contract-wallet flag on and a chain RPC endpoint configured. An ordinary smart-contract trading account is NOT covered — it still takes the recovery path and cannot authenticate.
(address: string, sessionPublicKey: string) => Promise<ChallengeResponse>
Create a single-use challenge whose message embeds the given session public key. Returns nonce, message, and expiresAt.

Example: Login Button

Auth actions validate SDK availability, wallet connection, and required parameters before running, throwing a descriptive Error (e.g. "SDK not available", "Wallet not connected", "Client ID is required") when a precondition is missing.