How to get started with the Gemini API?

The Gemini API enables developers to securely access trading and market data via REST and WebSocket, using HMAC-SHA384 authentication for secure, real-time interactions.

Aug 05, 2025 at 12:35 pm

Understanding the Gemini API and Its Purpose

The Gemini API is a powerful interface provided by the cryptocurrency exchange Gemini, enabling developers to interact programmatically with trading, account, and market data. This API supports both REST and WebSocket protocols, allowing users to retrieve real-time market data, place trades, manage orders, and monitor account balances. Before diving into implementation, it's essential to understand that the API is designed for developers with experience in HTTP requests, JSON formatting, and authentication mechanisms like HMAC-SHA384. The primary use cases include algorithmic trading bots, portfolio tracking dashboards, and automated market analysis tools.

To ensure secure access, Gemini requires the use of API keys and secret keys, which are generated through the Gemini web portal. These credentials are used to sign each request, ensuring that only authorized users can execute actions on the exchange. The API supports both sandbox and production environments, enabling developers to test their integrations without risking real funds.

Creating a Gemini Account and Generating API Keys

Before using the Gemini API, you must have a registered account on the Gemini platform. Navigate to the official website and complete the registration process, including identity verification if required. Once logged in, access the Account Settings section and select API from the menu. Here, you’ll initiate the process of creating a new API key.

When generating a key, you will be prompted to configure several settings:

• Choose a name for your API key to help identify its purpose
• Select the trading permissions (e.g., view-only, place orders, cancel orders)
• Decide whether to enable withdrawals (not recommended for most use cases)
• Specify IP restrictions to enhance security by limiting access to specific IP addresses

After confirming your selections, Gemini will generate a public API key and a private secret key. The private key will only be shown once, so copy and store it securely in an encrypted environment. Losing this key requires generating a new one, which invalidates the previous pair.

Setting Up the Development Environment

To begin coding with the Gemini API, set up a local development environment with the necessary tools. Install a programming language that supports HTTP requests and cryptographic functions—Python is a popular choice due to its simplicity and rich library ecosystem. Use pip to install required packages:

• requests: for making HTTP calls
• hmac and hashlib: for generating request signatures
• json: for parsing API responses

Create a dedicated project folder and initialize a configuration file (e.g., config.py) to store your API keys securely. Never hardcode credentials in your main script. Instead, use environment variables or a secure configuration management system.

Example configuration setup:

import os
API_KEY = os.getenv("GEMINI_API_KEY")
API_SECRET = os.getenv("GEMINI_API_SECRET").encode()

Set these environment variables in your shell or use a .env file with a package like python-dotenv. This practice minimizes the risk of accidentally exposing sensitive data.

Authenticating Requests with HMAC-SHA384

Every authenticated request to the Gemini API must include a digital signature generated using HMAC-SHA384. This signature is created using your private secret key and a JSON payload containing the request details. The process involves several precise steps:

• Construct a JSON object with the following fields:

  • request: the API endpoint path (e.g., /v1/balances)
  • nonce: a unique, incrementing integer (typically current timestamp in milliseconds)
  • symbol (if applicable): the trading pair (e.g., "btcusd")

• Encode the JSON payload to ASCII

• Generate the HMAC-SHA384 hash using your secret key

• Encode the resulting signature in Base64 format

Include the following headers in your HTTP request:

• Content-Type: application/json
• Content-Length: length of the payload
• X-GEMINI-APIKEY: your public API key
• X-GEMINI-PAYLOAD: the Base64-encoded JSON payload
• X-GEMINI-SIGNATURE: the Base64-encoded HMAC signature

Failure to follow this exact format will result in authentication errors. Test your signature logic with a simple endpoint like /v1/balances to verify correctness.

Executing Your First API Request

Once authentication is configured, you can make your first API call. Below is an example using Python to retrieve account balances:

• Import required libraries:

  import requests
  import json
  import hmac
  import time

• Define endpoint and headers:

  url = "https://api.gemini.com/v1/balances"
  nonce = int(time.time() * 1000)
  payload = {"request": "/v1/balances", "nonce": nonce}
  encoded_payload = json.dumps(payload).encode()
  b64_payload = base64.b64encode(encoded_payload).decode()
  signature = hmac.new(API_SECRET, b64_payload.encode(), hashlib.sha384).hexdigest()

• Set headers and send request:

  headers = {
  'Content-Type': "text/plain",
  'Content-Length': "0",
  'X-GEMINI-APIKEY': API_KEY,
  'X-GEMINI-PAYLOAD': b64_payload,
  'X-GEMINI-SIGNATURE': signature
  }
  response = requests.post(url, headers=headers)
  print(response.json())

A successful response returns a JSON array listing all asset balances in your account. Inspect the HTTP status code and error messages to troubleshoot issues like invalid signatures or rate limiting.

Using the WebSocket Feed for Real-Time Data

For real-time market data, the Gemini API provides a WebSocket stream at wss://api.gemini.com/v1/marketdata/SYMBOL. Replace SYMBOL with the trading pair (e.g., btcusd). This feed delivers price updates, order book changes, and trade executions with minimal latency.

To connect:

• Use a WebSocket client library like websocket-client in Python
• Subscribe to the channel using a JSON message:

  {
    "type": "subscribe",
    "subscriptions": [{"name": "l2", "symbols": ["btcusd"]}]
  }

• Handle incoming messages in a callback function to process bid/ask updates

The WebSocket feed is ideal for building real-time dashboards or high-frequency trading strategies. Be mindful of connection timeouts and implement reconnection logic for reliability.

Frequently Asked Questions

How do I reset my Gemini API key if it’s compromised?

Log into your Gemini account, go to the API settings page, locate the compromised key, and click Revoke. Generate a new key pair immediately and update your application’s configuration. All previous keys are permanently invalidated upon revocation.

Can I use the Gemini API without trading permissions?

Yes. During key creation, select View Only under permissions. This allows balance checks and market data access without enabling order placement or withdrawals, enhancing security for monitoring applications.

What rate limits does the Gemini API enforce?

The API imposes rate limits based on request type. Public endpoints (e.g., price data) allow higher frequency, while private endpoints are limited to approximately 10 requests per second. Exceeding limits results in HTTP 429 responses. Implement delays or exponential backoff in your code to stay compliant.

Is the sandbox environment identical to production?

The sandbox mirrors production endpoints with the base URL https://api.sandbox.gemini.com. It uses test funds and simulated market data, allowing full testing of order placement, cancellation, and balance tracking without financial risk. Ensure your code can switch environments seamlessly.