Market Data v1 (Archived)

Copy page

WebSocket API v1 Overview

Introduction

Using WebSockets provides several advantages:

• Receive notifications in real time
• Reduce the amount of data you have to transfer over the network
• Reduce latency introduced by polling interval

For example, to keep track of your orders, you might be requesting the Get Active Orders endpoint every five seconds. Using the private Order Events API, you would subscribe once and receive real time notifications of all order activity.

WebSocket Protocol Resources

• About HTML5 WebSocket
• RFC 6455 The WebSocket Protocol

---

Requests

Both public and private WebSocket API requests begin with a GET request that includes headers asking for an upgrade to the WebSocket protocol. The private API WebSocket request also includes the standard private API headers.

Public API Request Headers

Code
 
GET wss://api.gemini.com/v1/marketdata/BTCUSD
Connection: Upgrade
Upgrade: websocket
Sec-WebSocket-Key: uRovscZjNol/umbTt5uKmw==
Sec-WebSocket-Version: 13

Private API Request Headers

Code
 
GET wss://api.gemini.com/v1/order/events
Connection: Upgrade
Upgrade: websocket
Sec-WebSocket-Key: uRovscZjNol/umbTt5uKmw==
Sec-WebSocket-Version: 13
X-GEMINI-APIKEY: qOfnZJDZTTBsxdM3bVRP
X-GEMINI-PAYLOAD: eyJyZXF1ZXN0IjoiL3YxL29yZGVyL2V2ZW50cyIsIm5vbmNlIjoxNDc3OTYzMjQwNzQxMDgzMzA3fQ==
X-GEMINI-SIGNATURE: 88cd6f391d8f920a76a2060d613b519a8e8b4b3fb5bff089ea826d49ac73888bd479c0c2e2062ba60ba7afbe273132e3

---

Private API Invocation

Gemini uses API keys to allow access to private APIs. You can obtain these by logging on and creating a key in Settings/API. This will give you both an "API Key" that will serve as your user name, and an "API Secret" that you will use to sign messages.

All requests must contain a nonce, a number that will never be repeated and must increase between requests. This is to prevent an attacker who has captured a previous request from simply replaying that request. We recommend using a timestamp at millisecond or higher precision.

Payload

The payload of the requests will be a JSON object. Rather than being sent as the body of the POST request, it will be base-64 encoded and stored as a header in the request.

Headers

Header	Value
Content-Length	0
Content-Type	text/plain
X-GEMINI-APIKEY	Your Gemini API key
X-GEMINI-PAYLOAD	The base64-encoded JSON payload
X-GEMINI-SIGNATURE	hex(HMAC_SHA384(base64(payload), key=api_secret))
Cache-Control	no-cache

Example

Code
 
{
    "request": "/v1/order/events",
    "nonce": <nonce>
}

Base64 encode, then sign with HMAC-SHA384:

Code
 
import base64, hmac, hashlib, json, time

gemini_api_key = "mykey"
gemini_api_secret = "1234abcd".encode()

payload = {"request": "/v1/order/events", "nonce": time.time()}
encoded_payload = json.dumps(payload).encode()
b64 = base64.b64encode(encoded_payload)
signature = hmac.new(gemini_api_secret, b64, hashlib.sha384).hexdigest()

---

Roles

Gemini uses a role-based system for private API endpoints so that you can separate privileges for your API keys.

Endpoint	URI	Trader	Fund Manager	Auditor
Order Events	/v1/order/events	Yes	No	Yes

---

Responses

If successful, API requests will return an HTTP 101 Switching Protocols code in the response headers:

Code
 
HTTP/1.1 101 Switching Protocols
Connection: upgrade
Upgrade: websocket
Sec-WebSocket-Accept: wEV5o5orKGO27qATSTLczquY3EH=

Then the HTTP connection will be replaced by a WebSocket connection.

---

Data Types

Type	Description
string	A simple quoted string, following standard JSON rules.
decimal	A decimal value, encoded in a JSON string.
timestamp	The number of seconds since 1970-01-01 UTC. Use timestampms when available.
timestampms	The number of milliseconds since 1970-01-01 UTC. Transmitted as a JSON number.
integer	A whole number, transmitted as a JSON number.
boolean	A JSON boolean, the literal string true or false.
array	A JSON array.

Timestamps

The timestamp data type describes a date and time as a whole number in Unix Time format.

Timestamp format	Example	Supported request type
whole number (seconds)	1495127793	GET, POST
string (seconds)	"1495127793"	POST only
whole number (milliseconds)	1495127793000	GET, POST
string (milliseconds)	"1495127793000"	POST only

In responses, timestamp denotes seconds and timestampms denotes milliseconds since 1970-01-01 UTC.

Basis Points

Fees are calculated as a fraction of the notional value of each trade (price x amount) in basis points ("bps"), which represent 1/100th of a percent. For example, a fee of 25 bps means 0.25% of the denominated value.

---

Sequence Numbers

Events and heartbeats contain a socket_sequence number:

1. WebSocket connection is established
2. Optional subscription acknowledgement
3. First event with socket_sequence set to 0
4. Each subsequent message increases the sequence by one

If you see a gap in the sequence number, disconnect and reconnect.

---

Rate Limits

To prevent abuse, Gemini imposes rate limits on incoming requests.

For public WebSocket APIs, we recommend that you do not exceed 1 request per symbol per minute.

---

Error Codes

If a response is in error, the HTTP response code will reflect this, and a JSON body will be returned:

Code
 
{
    "result": "error",
    "reason": "BadNonce",
    "message": "Out-of-sequence nonce <1234> precedes previously used nonce <2345>"
}

HTTP Status Codes

HTTP Status	Meaning
200	Request was successful
30x	API entry point has moved, see Location header
400	Market not open, or the request was malformed
403	The API key is missing the role necessary to access this endpoint
404	Unknown API entry point or Order not found
406	Insufficient Funds
429	Rate Limiting was applied
500	The server encountered an error
502	Technical issues are preventing the request from being satisfied
503	The exchange is down for maintenance

Error Reasons

Reason	Meaning
ClientOrderIdTooLong	The Client Order ID must be under 100 characters
ConflictingOptions	New orders using a combination of order execution options are not supported
EndpointMismatch	The request was submitted to an endpoint different than the one in the payload
InsufficientFunds	The order was rejected because of insufficient funds
InvalidJson	The JSON provided is invalid
InvalidNonce	The nonce was not greater than the previously used nonce
InvalidOrderType	An unknown order type was provided
InvalidPrice	For new orders, the price was invalid
InvalidQuantity	A negative or otherwise invalid quantity was specified
InvalidSide	For new orders, an invalid side was specified
InvalidSignature	The signature did not match the expected signature
InvalidSymbol	An invalid symbol was specified
MarketNotOpen	The order was rejected because the market is not accepting new orders
MissingApikeyHeader	The X-GEMINI-APIKEY header was missing
MissingPayloadHeader	The X-GEMINI-PAYLOAD header was missing
MissingSignatureHeader	The X-GEMINI-SIGNATURE header was missing
MissingRole	The API key does not have the required role assigned
OrderNotFound	The order specified was not found
RateLimit	Requests were made too frequently
System	We are experiencing technical issues

---

Sandbox

Gemini's sandbox site is an instance of the Gemini Exchange that offers full exchange functionality using test funds.

Resource	URL
Website	https://exchange.sandbox.gemini.com
REST API	https://api.sandbox.gemini.com
WebSocket Feed	wss://api.sandbox.gemini.com
Documentation	https://docs.sandbox.gemini.com

Go to the sandbox site to register for a test account. Your account will automatically be credited with USD, BTC, ETH, BCH, LTC, OXT, LINK, BAT and DAI.

Two Factor Authentication: 2FA is enabled by default. To disable for automated testing, set a cookie or HTTP header named GEMINI-SANDBOX-2FA and enter 9999999 as the 2FA code.

---

Client Order ID

Client order ID is a client-supplied order identifier that Gemini will echo back in all subsequent messages about that order. Gemini strongly recommends supplying client_order_id when placing orders.

Your client order IDs are only visible to Gemini and you. They should be unique per trading session and must match: [:\-_\.#a-zA-Z0-9]{1,100}.

Characters	Description	ASCII Codes
A-Z	Uppercase letters	65-90
a-z	Lowercase letters	97-122
0-9	Digits	48-57
# - . : _	Special characters	35, 45, 46, 58, 95

---

Market Data v1

Market data is a public API that streams all the market data on a given symbol.

WebSocket Request

wss://api.gemini.com/v1/marketdata/:symbol

URL Parameters

Parameter	Required	Default	Description
heartbeat	No	false	Set to true to receive a heartbeat every 5 seconds
top_of_book	No	false	If true, receive top of book only (bids and offers)
bids	No	true	Include bids in change events
offers	No	true	Include asks in change events
trades	No	true	Include trade events

The semantics of entry type filtering:

• To be excluded from change events, an entry type must be explicitly flagged false
• If no filtering parameters are included, all entry types will appear

Response

Each frame contains a JSON message with the following format:

Field	Type	Description
type	string	heartbeat or update
socket_sequence	integer	Monotonic increasing sequence number

Messages of type update also include:

Field	Type	Description
eventId	integer	Monotonically increasing sequence number for changes
events	array	Order book changes or trade indications
timestamp	timestamp	Timestamp in seconds (use timestampms instead)
timestampms	timestampms	Timestamp in milliseconds

All elements of events share:

Field	Type	Description
type	string	Either trade or change

Change Event

Field	Type	Description
price	decimal	Price of this order book entry
side	string	bid or ask
reason	string	place, trade, cancel, or initial
remaining	decimal	Quantity remaining at this price level
delta	decimal	Quantity changed (may be negative)

To keep an up-to-date order book, watch for {"type": "change"} events and update the price level at price with the amount at remaining.

Trade Event

Field	Type	Description
price	decimal	Execution price
amount	decimal	Amount traded
makerSide	string	bid or ask

Examples

Code
 
import ssl
import websocket

def on_message(ws, message):
    print(message)

ws = websocket.WebSocketApp(
    "wss://api.gemini.com/v1/marketdata/BTCUSD",
    on_message=on_message)
ws.run_forever(sslopt={"cert_reqs": ssl.CERT_NONE})

Initial Response (top of book)

Code
 
{
  "type": "update",
  "eventId": 5375461993,
  "socket_sequence": 0,
  "events": [
    {
      "type": "change",
      "reason": "initial",
      "price": "3641.61",
      "delta": "0.83372051",
      "remaining": "0.83372051",
      "side": "bid"
    },
    {
      "type": "change",
      "reason": "initial",
      "price": "3641.62",
      "delta": "4.072",
      "remaining": "4.072",
      "side": "ask"
    }
  ]
}

When a trade occurs

Code
 
{
  "type": "update",
  "eventId": 5375547515,
  "timestamp": 1547760288,
  "timestampms": 1547760288001,
  "socket_sequence": 15,
  "events": [
    {
      "type": "trade",
      "tid": 5375547515,
      "price": "3632.54",
      "amount": "0.1362819142",
      "makerSide": "ask"
    }
  ]
}

Heartbeat

Code
 
{
  "type": "heartbeat",
  "socket_sequence": 30
}