Copy page

WebSocket API

Authentication

The WebSocket API accepts either an HMAC-signed API key or an OAuth 2.0 bearer token on the connection upgrade. Pick whichever fits your app.

Generate an API Key

API keys for our WebSocket API have special requirements:

1. Navigate to API Settings
2. Click "Create API key"
3. Scope: Select the account you want to trade with
4. Settings:
   • ✅ Enable "Uses a time-based nonce"
   • ✅ Enable "Trading"
5. Save your API key and secret securely

---

Create an Authenticated Connection

Pass the following headers when establishing the websocket connection,

Header	Value
X-GEMINI-APIKEY	Your Gemini API key (session key)
X-GEMINI-NONCE	Current epoch timestamp in seconds
X-GEMINI-SIGNATURE	hex(HMAC_SHA384(base64(nonce), key=api_secret))
X-GEMINI-PAYLOAD	base64(nonce)

:::info Browser WebSocket Clients The standard browser WebSocket constructor (new WebSocket(url)) does not allow setting custom HTTP headers during the upgrade handshake. For browser-based applications, connect via backend proxy services or use query-string session authentication where supported. Node.js (ws), Python, Go, and native clients can supply standard HTTP headers during the handshake. :::

Signature Generation Step-by-Step

Code
# Create a nonce from the current epoch time in seconds
nonce = current_timestamp_in_seconds

# Our payload will be the base64 encoded nonce for simplicity
payload = base64_encode(nonce.toString)

# Generate a signature using the hmac_sha384 algorithm
signature = hmac_sha384(payload, api_secret)

# Convert the signature to hex so it can be passed in the headers
hexSignature = hex(signature)

---

Alternative: OAuth 2.0 Bearer Token

If your application uses OAuth 2.0 to access the Gemini API, you can authenticate the WebSocket connection with the same access token instead of provisioning an API key.

Pass the access token in the Authorization header on the WebSocket upgrade request:

Header	Value
Authorization	Bearer <access_token>

When using OAuth, you do not send the X-GEMINI-APIKEY, X-GEMINI-NONCE, X-GEMINI-PAYLOAD, or X-GEMINI-SIGNATURE headers.