Coinbase Derivatives: Predictions WebSocket Authentication

Every connection must authenticate before the gateway routes any command. Include the credential keys in your first command, which must be subscribe, unsubscribe, or list_subscriptions. Any other first command fails authentication. You do not need to send credentials on later commands. Authentication lasts for the life of the connection. If the connection drops, reconnect, authenticate again, and resubscribe.

Authentication

Keys are required (Y), optional (N), or conditionally required (C). Conditional keys are required based on the presence or value of other keys.

Key	Type	Req	Description
`key`	String	C	Your API key. Required on the first command.
`passphrase`	String	C	Your API passphrase. Must not be empty. Required on the first command.
`signature`	String	C	Exactly 44 characters of standard padded Base64 that decodes to 32 bytes. Required on the first command. See Signature.
`time`	String	C	Current Unix epoch time in seconds, as a base-10 integer string with no decimal point, whitespace, leading `+`, or leading zeros. Required on the first command.

Example authenticated first command, using the test values from Signature example:

{
  "id": 1,
  "cmd": "subscribe",
  "key": "fixed-api-key",
  "passphrase": "fixed-passphrase",
  "signature": "xGbr3oY2MKYu/HoFjzTX1i2jhltEx/jGFd//lF+49pw=",
  "time": "1717171717",
  "params": {
    "channels": ["ticker"],
    "ticker": "NFL-GAMEWINNER-26NOV28LARSF-LAR"
  }
}

The credential keys sit at the top level of the command object, next to id, cmd, and params. See Command keys.

Signature

Concatenate these strings without delimiters: time + key + "CPM_WEB_MARKETDATA" + passphrase. Use the exact time, key, and passphrase values you send.
Do not trim or Unicode-normalize the API key or passphrase.
Encode the concatenated text once as UTF-8.
Decode your signing secret with standard Base64.
Compute HMAC-SHA256 over the UTF-8 bytes, keyed with the decoded secret.
Encode the 32-byte result with standard padded Base64 and send it as signature.

The command’s id, cmd, and params are not signed. The signature authenticates the whole connection.

time must be within 30 seconds of the server’s clock, inclusive, in either direction: server_time - 30 to server_time + 30.

Signature example

These are test values only. The signing secret a2V5 is the Base64 encoding of the text key. Use it only to check your signing code, and never share your real secret.

Input or step	Value
`time`	`1717171717`
`key`	`fixed-api-key`
`passphrase`	`fixed-passphrase`
Signing secret	`a2V5` (Base64)
Prehash string	`1717171717fixed-api-keyCPM_WEB_MARKETDATAfixed-passphrase`
HMAC-SHA256 (hex)	`c466ebde863630a62efc7a058f34d7d62da3865b44c7f8c615dfff945fb8f69c`
`signature`	`xGbr3oY2MKYu/HoFjzTX1i2jhltEx/jGFd//lF+49pw=`

Example in Python:

import base64, hashlib, hmac

time, key, passphrase = "1717171717", "fixed-api-key", "fixed-passphrase"
secret = base64.b64decode("a2V5")
prehash = (time + key + "CPM_WEB_MARKETDATA" + passphrase).encode("utf-8")
signature = base64.b64encode(hmac.new(secret, prehash, hashlib.sha256).digest()).decode()
# signature == "xGbr3oY2MKYu/HoFjzTX1i2jhltEx/jGFd//lF+49pw="

Authorization

Authentication succeeds when all of the following are true:

The signature is valid for the API key and passphrase.
The API key exists.
The API key’s user is active and has the MARKET_DATA permission.
The user’s Firm or FCM is active.

If authentication fails, the server sends an error with code 7 and text Unable to authenticate, then closes the WebSocket with close code 3000 and reason Unauthorized User. Open a new connection with a fresh time and signature to retry. See Errors. Example authentication failure:

{
  "id": 1,
  "type": "error",
  "msg": {
    "code": 7,
    "msg": "Unable to authenticate"
  }
}

A newly created or rotated API key may take up to 5 seconds to become usable.

Commands sent while authentication is pending

You can send more commands before authentication completes. The server queues them and runs them in order after authentication succeeds. See Limits for the queue size and the authentication timeout.

REST API Overview

REST Endpoints

FIX

WebSocket

Coinbase Derivatives: Predictions WebSocket Authentication

Authentication

Signature

Signature example

Authorization

Commands sent while authentication is pending

​Authentication

​Signature

​Signature example

​Authorization

​Commands sent while authentication is pending

Authentication

Signature

Signature example

Authorization

Commands sent while authentication is pending