Gemini Authentication: API Key & Signature Methods (2026)

Authentication overview

Gemini employs a robust authentication mechanism for its API to ensure the security and integrity of user accounts and transactions. Access to Gemini's REST and WebSocket APIs requires authentication using a combination of API keys, API secrets, and cryptographic signatures for each request. This process verifies the identity of the client making the request and ensures that the request has not been tampered with during transmission.

The authentication scheme is built on principles similar to HMAC (Hash-based Message Authentication Code) to provide data integrity and sender authentication. API keys identify the account, while API secrets are used to sign requests, proving the request's authenticity without transmitting the secret itself. This approach aligns with industry best practices for securing API interactions, particularly in financial services where data sensitivity is high.

Developers interacting with the Gemini API must understand how to generate these credentials, apply them correctly to API requests, and implement security best practices to protect their API access. The authentication process is critical for all trading, account management, and data retrieval operations via the API.

Supported authentication methods

Gemini primarily supports API Key and Secret authentication combined with request signing for its REST and WebSocket APIs. This method is standard for secure interactions with cryptocurrency exchanges, providing both identification and verification for each API call.

API Key and Secret with Request Signature

• API Key: A unique identifier for your application or user account. It is included in the request headers.
• API Secret: A private key used to sign the request payload. The API secret is never sent directly over the network.
• Request Signature: A cryptographic hash generated using the API secret and specific components of the API request (e.g., nonce, request URL, payload). This signature is included in the request headers and verified by the Gemini server.

This method ensures that only authorized parties with access to the API secret can generate valid signatures for requests. The signature prevents unauthorized modification of API requests in transit and verifies the sender's identity.

The table below summarizes the authentication method used by Gemini:

Getting your credentials

To interact with the Gemini API, you need to generate an API key and an API secret from your Gemini account. These credentials serve as your unique identifier and cryptographic key for signing requests.

Steps to Generate API Credentials:

1. Log in to your Gemini Account: Access your account on the Gemini website.
2. Navigate to API Settings: Go to the "Account Settings" or "API Settings" section, typically found under your profile or security options.
3. Create a New API Key: Look for an option to "Create New API Key" or "Generate API Key."
4. Configure Permissions: When creating an API key, you will be prompted to set permissions. It is a critical security step to grant only the necessary permissions (e.g., auditor, trader, fund manager) to your API key. For instance, if your application only needs to read market data, do not grant trading permissions. You can define specific IP addresses that are allowed to use the API key for enhanced security, as detailed in the Gemini API documentation.
5. Retrieve API Key and Secret: After creation, Gemini will display your API key and API secret. The API secret is often shown only once. Make sure to copy and store it securely immediately. If you lose your API secret, you may need to revoke the key and generate a new one.
6. Store Securely: Store your API key and secret in a secure location. Avoid hardcoding them directly into your application code. Use environment variables, a secrets management service, or a secure configuration file.

Authenticated request example

Authenticated requests to the Gemini API require specific HTTP headers: X-GEMINI-APIKEY, X-GEMINI-PAYLOAD, and X-GEMINI-SIGNATURE. The payload header contains a base64-encoded JSON string, and the signature header contains the HMAC-SHA384 signature of this payload, generated using your API secret.

Here's a conceptual example using Python to make a trading API call, demonstrating the process of generating the payload and signature:

import http.client
import hashlib
import hmac
import base64
import json
import time

api_key = "YOUR_API_KEY"
api_secret = "YOUR_API_SECRET".encode('ascii') # API secret must be bytes

# Define the request payload
request_url = "/v1/order/new"
nonce = int(time.time() * 1000) # Unique nonce for each request
request_body = {
    "request": request_url,
    "nonce": nonce,
    "symbol": "btcusd",
    "amount": "0.001",
    "price": "30000",
    "side": "buy",
    "type": "exchange limit"
}

# JSON encode and base64 encode the payload
json_payload = json.dumps(request_body)
b64_payload = base64.b64encode(json_payload.encode('ascii'))

# Create the signature
signature = hmac.new(api_secret, b64_payload, hashlib.sha384).hexdigest()

# Set up HTTP connection (using http.client for demonstration)
conn = http.client.HTTPSConnection("api.gemini.com")
headers = {
    "Content-Type": "text/plain",
    "Content-Length": "0",
    "X-GEMINI-APIKEY": api_key,
    "X-GEMINI-PAYLOAD": b64_payload.decode('ascii'),
    "X-GEMINI-SIGNATURE": signature,
    "Cache-Control": "no-cache"
}

# Make the request
conn.request("POST", request_url, headers=headers)
response = conn.getresponse()
print(response.status, response.reason)
print(response.read().decode('utf-8'))

conn.close()

This example illustrates how to construct the necessary headers and payload for an authenticated request to the Gemini REST API. The nonce is a critical component for preventing replay attacks, ensuring each request is unique. Developers should consult the Gemini REST API reference for specific endpoint details and required parameters.

Security best practices

Securing your API credentials and interactions with the Gemini API is paramount due to the financial nature of the platform. Adhering to these best practices reduces the risk of unauthorized access and potential financial loss:

1. Least Privilege Principle

• When generating API keys, always assign the minimum necessary permissions. If an application only needs to read account balances, do not grant it trading or withdrawal permissions.
• Regularly review API key permissions and revoke any unnecessary access.

2. Secure Storage of API Secrets

• Avoid Hardcoding: Never embed API keys or secrets directly into your source code.
• Environment Variables: Use environment variables to store credentials, especially in development and staging environments.
• Secrets Management: For production environments, utilize dedicated secrets management services (e.g., AWS Secrets Manager, Google Cloud Secret Manager, Azure Key Vault) or secure configuration files.
• Access Control: Ensure that only authorized personnel and systems have access to API secrets.

3. IP Whitelisting

• Gemini allows you to whitelist specific IP addresses that can use an API key. Restrict API key usage to a predefined set of trusted IP addresses to prevent unauthorized access from other locations, as described in the Gemini API documentation.

4. Nonce Management

• Ensure that the nonce (number used once) parameter in your requests is unique and strictly increasing for each authenticated request. This prevents replay attacks where an attacker might re-submit past valid requests.

5. Secure Communication (HTTPS/TLS)

• Always use HTTPS for all API communications. Gemini's API endpoints are served over TLS, ensuring that your requests and responses are encrypted in transit. Verify TLS certificates to prevent man-in-the-middle attacks.

6. Regular Key Rotation

• Periodically rotate your API keys and secrets. This practice limits the window of exposure if a key is compromised. Define a rotation schedule (e.g., every 90 days).

7. Error Handling and Logging

• Implement robust error handling for API calls, especially for authentication failures. Avoid logging API secrets or sensitive request payloads.
• Monitor API access logs for unusual activity, such as a high volume of failed authentication attempts or requests from unexpected IP addresses.

8. Protect Your Development Environment

• Ensure that your development machines and build environments are secure. Use strong passwords, two-factor authentication, and keep software updated to prevent malware or unauthorized access that could compromise your credentials.