Connection

Open Coinbase OAuth, check connection state, and revalidate the stored token.

When to use

Use these methods for the login step and whenever you need to know if Coinbase is still authorized.

Methods

Method	Returns	Purpose
ready()	Promise<void>	Wait until the module finished restoring any stored token
isConnected()	boolean	Whether an OAuth token is present
isInitializing()	boolean	true while the module is still initializing
isPopupOpen()	boolean	Whether the login popup is open
connect()	Promise<boolean>	Open OAuth popup; true when connected
disconnect()	void	Clear token, pending withdrawal, and cooldown
ensureSession()	Promise<boolean>	Validate / refresh the token; false if expired

Example

await client.coinbase.ready();

if (!client.coinbase.isConnected()) {
  const connected = await client.coinbase.connect();
  if (!connected) {
    // User closed the popup or auth failed — show retry
  }
}

const stillValid = await client.coinbase.ensureSession();
if (!stillValid) {
  await client.coinbase.connect();
}

// Later
client.coinbase.disconnect();

Listen for popup / session side effects:

client.coinbase.onPopupOpenChanged(({ isOpen }) => {
  // disable UI while popup is open if you want
});

client.coinbase.onSessionExpired(() => {
  // send user back to the Connect step
});

Errors

Code	When	What to do
OAUTH_POPUP_BLOCKED	Browser blocked the popup	Ask to allow popups, retry connect()
OAUTH_POPUP_CLOSED	User closed popup early	Offer retry
COINBASE_SESSION_EXPIRED	Token no longer valid on a later call	Call connect() again
CLIENT_DESTROYED	Client already destroyed	Create a new client

ensureSession() returns false (and emits coinbase:sessionExpired) instead of throwing when the token is invalid. When the local token timestamp is still within tokenExpiryMs, it returns true without calling session-status. Otherwise it hits the API; on success it emits coinbase:sessionEnsured and refreshes the local token timestamp (including when X-Refreshed-Token is returned). Transient errors fail open (true) without updating the stored timestamp, so the next call retries refresh ASAP. Concurrent callers share one in-flight request.

Balance and network fetches call ensureSession() before using the JWT, so they do not race ahead of connection validation and fail with COINBASE_NOT_CONNECTED while session-status is still refreshing.

API calls that need a JWT throw COINBASE_NOT_CONNECTED / COINBASE_SESSION_EXPIRED.

See Errors for the full flow guide.