Gemini REST API 详解

概述

Gemini 提供了一套功能强大的 REST API（Representational State Transfer Application Programming Interface），允许开发者以编程方式访问其交易平台，进行市场数据查询、下单（包括限价单、市价单等各种订单类型）、账户管理（如查询账户余额、交易历史等）等操作。这套 API 旨在提供高度灵活性和控制力，满足不同类型用户的需求，从个人交易者到机构投资者，都能利用 Gemini API 构建自定义的交易策略和应用程序。

Gemini REST API 使用标准的 HTTP 请求方法（如 GET、POST、PUT、DELETE）与服务器进行交互，数据交换格式通常为 JSON（JavaScript Object Notation），易于解析和处理。API 遵循 RESTful 设计原则，资源通过 URL 进行标识，操作通过 HTTP 方法进行定义，保证了接口的简洁性和易用性。

这篇文档旨在详细介绍 Gemini REST API 的各个方面，包括 API 认证方式（如 API 密钥管理）、请求参数说明、响应格式定义、错误代码解释、以及各种 API 端点的使用示例。通过阅读本文档，开发者可以更好地理解和使用 Gemini REST API，快速构建可靠、高效的交易应用程序，并充分利用 Gemini 提供的各种交易功能。

身份验证

在使用 Gemini REST API 之前，必须进行身份验证以确保交易安全。Gemini 使用 API 密钥对来实现身份验证，该密钥对包含一个公钥（API Key）和一个私钥（Secret Key）。公钥用于标识您的账户，私钥用于对请求进行签名，证明请求的真实性。

• 获取 API 密钥: 在 Gemini 账户的设置页面生成 API 密钥对。生成密钥对后，请务必将私钥妥善保管，切勿泄露给他人。私钥泄露可能导致您的账户被盗用。建议采取额外的安全措施，例如将私钥存储在硬件钱包或加密的密钥管理系统中。 Gemini 允许您创建多个 API 密钥，您可以根据不同的用途创建不同的密钥，并设置相应的权限，例如只允许进行交易或只允许查看账户信息，以提高安全性。
• 构造身份验证 Header: 每一个需要身份验证的 API 请求都需要包含以下 HTTP Header，用于告知 Gemini 服务器您的身份信息和请求的签名：
  • X-GEMINI-APIKEY : 您的 API 公钥。这是公开的，可以安全地包含在请求中。
  • X-GEMINI-PAYLOAD : 包含请求数据的 Base64 编码字符串。Payload 是一个 JSON 对象，包含了请求的 API 路径和一些必要的参数。
  • X-GEMINI-SIGNATURE : 使用您的私钥对 Payload 进行 HMAC SHA384 加密后的签名。该签名用于验证请求的完整性和真实性。

Payload 是一个 JSON 对象，至少需要包含以下两个字段：

*   `request`: 请求的 API 路径，例如 `/v1/order/new`，指定了您要调用的 API 接口。
*   `nonce`: 一个单调递增的随机数，用于防止重放攻击。Nonce 必须是唯一的，并且每次请求都必须递增。可以使用时间戳乘以 1000 来生成 Nonce，例如 `int(time.time() * 1000)`。

Python 示例代码片段，展示如何构造身份验证 Header。 这段代码演示了如何使用 Python 对 Gemini API 请求进行身份验证。请务必替换代码中的 `api_key` 和 `secret_key` 为您自己的 API 公钥和私钥。

import base64 import hashlib import hmac import import time

def generate_headers(request_path, payload, api_key, secret_key): """Generates Gemini API authentication headers.""" payload['request'] = request_path payload['nonce'] = int(time.time() * 1000) encoded_payload = base64.b64encode(.dumps(payload).encode('utf-8')) signature = hmac.new(secret_key.encode('utf-8'), encoded_payload, hashlib.sha384).hexdigest()

    headers = {
        'Content-Type': 'application/',
        'X-GEMINI-APIKEY': api_key,
        'X-GEMINI-PAYLOAD': encoded_payload.decode('utf-8'),
        'X-GEMINI-SIGNATURE': signature,
    }
    return headers

常用 API 接口

Gemini REST API 提供了全面的功能，允许开发者访问和管理其平台上的各种数据和交易操作。以下是一些常用的核心接口及其详细说明：

• /v1/pubticker/{symbol} : 获取指定交易对的实时行情数据，包括但不限于最新成交价、成交量、最高价、最低价和时间戳等信息。 {symbol} 占位符需要替换为具体的交易对代码，例如 btcusd 代表比特币/美元交易对。这个接口对于构建实时行情监控和交易策略至关重要。
• /v1/symbols : 获取Gemini平台上所有可交易的交易对列表及其详细信息，例如交易对的最小交易单位、价格精度等。这对于了解平台支持的交易标的和进行参数校验非常有用。返回的数据结构通常包含交易对名称、基础货币和报价货币等。
• /v1/order/new : 创建一个新的订单，即提交一个买入或卖出指令。该接口需要提供详细的订单参数，包括交易对（例如 btcusd ）、订单类型（市价单 market 或限价单 limit ）、买卖方向（ buy 或 sell ）、数量（交易的数字货币数量）和价格（仅限限价单）。成功创建订单后，会返回订单 ID，用于后续查询和管理。
• /v1/order/cancel : 取消一个已经提交但尚未完全成交的订单。取消订单需要提供目标订单的唯一标识符（订单 ID）。成功取消订单后，账户中的相应资金或数字货币将会被释放。此接口有助于用户灵活管理其未成交的订单。
• /v1/orders : 获取当前账户中所有未完成（未完全成交或未取消）的订单列表。此接口允许用户监控其挂单状态，包括订单的价格、数量、剩余数量和创建时间等。可以通过参数过滤特定交易对的未完成订单。
• /v1/order/status : 获取指定订单的详细状态信息。通过提供订单 ID，可以查询订单的当前状态，包括已成交数量、剩余数量、平均成交价格和订单状态（例如 open 、 closed 、 canceled ）。此接口是订单管理的关键组成部分。
• /v1/mytrades : 获取账户的历史成交记录。该接口允许用户查询其账户在特定时间段内的所有成交记录，包括成交价格、成交数量、交易费用和时间戳等信息。可以通过时间戳范围和交易对进行过滤，方便用户进行交易分析和税务计算。
• /v1/balances : 获取账户余额信息，包括各种数字货币和法币的可用余额、冻结余额和总余额。此接口是账户管理的基础，允许用户了解其资金状况并进行风险评估。返回数据通常包括币种代码和相应的余额信息。

订单类型

Gemini 交易所提供多种订单类型，满足不同交易者的需求和策略：

• 限价单 (Limit Order): 限价单允许交易者设定一个期望的买入或卖出价格。只有当市场价格达到或优于该指定价格时，该订单才会被执行。这意味着交易者可以控制成交价格，但不能保证订单一定成交。如果市场价格始终未达到设定的限价，订单将保持挂单状态，直到被取消。限价单适合对价格敏感，希望以特定价格成交的交易者。
• 市价单 (Market Order): 市价单是一种以当前市场最佳可用价格立即买入或卖出的订单。市价单的优势在于保证立即成交，交易者无需等待价格达到特定水平。然而，市价单的缺点是交易者无法控制成交价格，最终成交价格可能会因市场波动而与预期有所不同。市价单适合需要快速成交，对价格不太敏感的交易者。请注意，在市场波动剧烈时，市价单的滑点风险较高。
• 止损限价单 (Stop-Limit Order): 止损限价单结合了止损单和限价单的特性。它包含两个价格：止损价和限价。当市场价格达到或超过止损价时，一个限价单会被触发，该限价单的成交价格为预设的限价。止损价是触发订单的价格，而限价是触发后订单可以成交的最高（买入）或最低（卖出）价格。止损限价单常用于风险管理，例如限制潜在损失或锁定利润。然而，如果市场价格在触发限价单后迅速变化，导致无法在设定的限价或更好的价格成交，订单可能不会被执行。

速率限制

Gemini REST API 实施了速率限制机制，旨在保护系统资源，防止恶意滥用和过度请求，确保所有用户都能获得稳定可靠的服务。不同的 API 接口具有不同的速率限制策略，这些策略通常基于请求的复杂性、服务器负载和特定接口的预期使用模式而设计。

当客户端应用程序超过了预设的速率限制阈值，API 将返回一个 HTTP 429 Too Many Requests 错误。这个错误代码明确指示客户端在短时间内发送了过多的请求。为了避免触发速率限制，开发者需要仔细规划和管理其 API 请求的频率。这包括实施适当的重试机制（例如，使用指数退避算法），缓存响应数据以减少重复请求，以及优化应用程序的逻辑，尽可能减少不必要的 API 调用。

了解并遵守 Gemini API 的速率限制对于构建稳定且高效的应用程序至关重要。开发者应该查阅官方文档，详细了解每个 API 接口的速率限制规则，并据此调整其应用程序的行为。通过合理控制请求频率，开发者可以确保其应用程序能够持续访问 Gemini API，而不会因违反速率限制而被暂时或永久阻止。

错误处理

Gemini REST API 在发生错误时会返回相应的 HTTP 状态码以及 JSON 格式的详细错误信息，方便开发者进行问题排查和处理。 除了标准的 HTTP 状态码之外，Gemini 还会提供特定于 API 的错误代码，以便更精确地描述错误原因。

• 400 Bad Request : 请求参数错误。 这通常意味着请求中缺少必要的参数，或者参数的值无效。 例如，交易数量超过允许的范围，或者使用了不支持的货币对。API的响应会包含详细的错误描述，指明具体哪个参数出错，以及期望的格式或取值范围。开发者应该仔细检查请求参数，并根据错误描述进行修正。
• 401 Unauthorized : 身份验证失败。 这表明提供的 API 密钥无效、已过期或没有足够的权限访问请求的资源。 确保 API 密钥已正确配置，并且与正在访问的 API 端点所需的权限相匹配。如果使用了双重验证（2FA），还需要确保在请求中包含了正确的 2FA 代码。检查 API 密钥是否被禁用或撤销。
• 404 Not Found : 请求的资源不存在。 这表示请求的 URL 地址不正确，或者请求访问的资源已经被删除或移动。 检查 URL 是否拼写正确，并确认资源是否仍然存在。 对于特定于用户的资源，例如订单或交易历史，请确保使用正确的用户 ID 或账户信息。
• 429 Too Many Requests : 超过速率限制。 Gemini API 对每个 API 密钥都有速率限制，以防止滥用和维护系统稳定性。 如果超过了速率限制，API 将返回此错误。 开发者应该实施速率限制策略，例如使用指数退避算法，来避免超过限制。可以通过查看响应头中的 X-RateLimit-Remaining 和 X-RateLimit-Reset 字段来了解剩余的请求次数以及速率限制重置的时间。
• 500 Internal Server Error : 服务器内部错误。 这是一个通用的错误代码，表示服务器遇到了未知的错误，无法完成请求。 这可能由服务器端的代码错误、数据库连接问题或硬件故障引起。 开发者可以稍后重试请求，或者联系 Gemini 支持团队以获取更多信息。 如果频繁遇到此错误，应记录错误信息并及时报告给 Gemini。

开发者需要根据不同的错误信息进行相应的处理。 良好的错误处理机制应该包括：日志记录、错误重试（对于可重试的错误，例如 500 错误）以及向用户提供有用的错误信息。避免向用户暴露敏感信息，例如 API 密钥或内部服务器错误详情。 对于关键操作，例如资金转移，应该实现幂等性，以避免由于网络问题或服务器错误导致重复执行。

WebSocket API

除了 REST API， Gemini 还提供 WebSocket API，以便实时推送市场数据、订单簿更新和账户信息。WebSocket API 通过建立持久的双向通信连接，提供了比传统 REST API 更低的延迟和更高的效率，尤其适合需要快速响应市场变化和对实时性要求极高的金融科技应用、高频交易机器人和实时监控系统。

与 REST API 的请求-响应模式不同，WebSocket API 允许服务器主动向客户端推送数据，无需客户端频繁轮询。这种模式显著降低了网络开销和服务器负载，同时保证了数据的及时性。 Gemini 的 WebSocket API 通常提供多种订阅频道，例如：

• 市场数据频道： 提供实时交易价格、成交量和订单簿信息，支持不同级别的聚合和过滤，满足不同用户的需求。
• 订单簿频道： 提供实时的订单簿变动信息，包括新增、修改和删除的订单，帮助用户深入了解市场深度和流动性。
• 账户信息频道： 提供实时的账户余额、订单状态和成交记录，方便用户监控账户活动和风险。

开发者可以使用各种编程语言和 WebSocket 客户端库连接到 Gemini 的 WebSocket API，例如 JavaScript、Python、Java 等。通常需要进行身份验证，才能访问私有数据，例如账户信息。请务必参考 Gemini 官方文档，了解最新的 API 规范、认证方式和最佳实践，以确保安全可靠地使用 WebSocket API。

订单参数详解

在加密货币交易中，创建订单是执行交易的核心步骤。在创建订单时，必须指定一些关键参数，这些参数决定了订单的执行方式和最终结果。以下是对这些参数的详细说明，旨在帮助您更深入地理解并正确使用它们：

• symbol : 交易对，也称为交易代码，它定义了要交易的两种加密货币。例如， btcusd 表示比特币 (BTC) 和美元 (USD) 的交易对。交易所会根据您指定的交易对撮合买卖订单。交易对通常由两个部分组成：基础货币（base currency）和计价货币（quote currency）。
• amount : 订单数量，指您想要买入或卖出的基础货币的数量。数量以交易对的基础货币为单位。例如，在 btcusd 交易对中， amount 以 BTC 为单位，表示您要买入或卖出的比特币数量。这个数值必须符合交易所规定的最小交易数量限制。
• price : 订单价格，指您愿意买入或卖出基础货币的价格。价格以交易对的计价货币为单位。例如，在 btcusd 交易对中， price 以 USD 为单位，表示您愿意以多少美元的价格买入或卖出一个比特币。对于限价单， price 是必须指定的；对于市价单，则不需要指定 price 。
• side : 订单方向，决定了您是进行买入操作还是卖出操作。 buy 表示买入，即您希望购买基础货币； sell 表示卖出，即您希望出售基础货币。选择正确的 side 是确保您执行正确交易的关键。
• type : 订单类型，决定了订单的执行方式。常见的订单类型包括：
  • exchange limit (限价单): 以指定的价格或更好的价格执行订单。如果市场价格未达到指定价格，订单将不会立即成交，而是会挂在订单簿上等待成交。
  • exchange market (市价单): 以当前市场最佳价格立即执行订单。市价单通常会快速成交，但成交价格可能不如预期，因为它取决于市场深度和流动性。
  • exchange stop limit (止损限价单): 当市场价格达到预设的止损价格时，触发一个限价单。它结合了止损单和限价单的特性，可以帮助投资者在控制风险的同时，锁定一定的利润。
  • exchange stop market (止损市价单): 当市场价格达到预设的止损价格时，触发一个市价单。与止损限价单不同，止损市价单会以当时的市场价格立即成交，不保证成交价格。
• client_order_id (可选): 一个由客户端（您的交易应用程序或程序）生成的唯一 ID，用于标识订单。这个 ID 方便您在自己的系统中跟踪和管理订单。交易所通常会返回该 ID，方便您进行订单状态查询。
• options (可选): 一个字符串数组，用于指定订单的附加选项，以实现更高级的订单控制。常用的选项包括：
  • maker-or-cancel (Post Only): 这是一种限价单的变体。如果订单不能立即成交（意味着它会立即成为taker，从订单簿中吃单），则立即取消该订单。这种订单类型可以确保您始终作为 maker（挂单者），从而享受更低的交易费用。
  • immediate-or-cancel (IOC): 如果订单不能立即完全成交，则立即取消未成交的部分。这意味着订单会尽可能地立即成交，但不会挂在订单簿上等待完全成交。
  • fill-or-kill (FOK): 如果订单不能立即完全成交，则整个订单立即取消。这种订单类型确保您要么完全成交，要么不成交，避免部分成交的情况。

使用示例 (Python)

以下是一个使用 Python 创建限价买单的示例代码，展示了如何通过 API 与加密货币交易所进行交互。请注意，实际代码需要根据交易所的具体 API 文档进行调整，并妥善保管您的 API 密钥。

import requests

import

import hmac

import hashlib

# 替换为您的API密钥和密钥
api_key = 'YOUR_API_KEY'
secret_key = 'YOUR_SECRET_KEY'

# 交易所API的基础URL
base_url = 'YOUR_EXCHANGE_API_URL'

# 定义交易对和数量
symbol = 'BTCUSDT'
quantity = 0.01
price = 30000 # 限价

def create_order(symbol, side, type, quantity, price):
"""创建订单的函数"""
endpoint = '/api/v3/order' # 替换为正确的API端点
timestamp = int(time.time() * 1000)

params = {
'symbol': symbol,
'side': side,
'type': type,
'quantity': quantity,
'price': price,
'timeInForce': 'GTC', # Good Till Cancelled
'timestamp': timestamp
}

query_string = '&'.join([f"{k}={v}" for k, v in params.items()])
signature = hmac.new(secret_key.encode('utf-8'), query_string.encode('utf-8'), hashlib.sha256).hexdigest()
params['signature'] = signature

headers = {
'X-MBX-APIKEY': api_key
}

url = base_url + endpoint
response = requests.post(url, headers=headers, params=params)
response.raise_for_status() # 检查是否有HTTP错误
return response.()

try:
order = create_order(symbol, 'BUY', 'LIMIT', quantity, price)
print("Order created successfully:", order)
except requests.exceptions.RequestException as e:
print(f"An error occurred: {e}")
except Exception as e:
print(f"An unexpected error occurred: {e}")


请注意：

• YOUR_API_KEY 和 YOUR_SECRET_KEY 需要替换为您在交易所获得的实际API密钥。 千万不要将您的私钥泄露给任何人。
• YOUR_EXCHANGE_API_URL 需要替换为交易所API的根URL。每个交易所的URL都有所不同。
• `symbol`指定要交易的货币对，例如'BTCUSDT'，表示比特币兑换美元。
• 此示例使用限价单（LIMIT），这意味着只有当市场价格达到或低于设定的价格（`price`）时，订单才会成交。
• `timeInForce`设置为'GTC'（Good Till Cancelled），表示订单将一直有效，直到被完全执行或取消。其他选项包括'IOC'（Immediate Or Cancel）和'FOK'（Fill Or Kill）。
• 为了安全起见，请务必妥善处理API密钥，并采取额外的安全措施，如启用双因素认证。
• 实际交易涉及风险，请根据自己的风险承受能力进行投资决策。
• 此示例代码仅为演示目的，需要根据具体的交易所API文档进行调整。
• 在生产环境中使用前，请务必在测试环境（Testnet）进行充分测试。
• 错误处理代码(try...except) 确保程序能够处理API调用期间可能发生的异常，例如网络问题或无效的API密钥。
• API调用需要签名，以验证请求的真实性。签名过程通常涉及使用您的密钥对请求参数进行哈希处理。 此处使用 hmac 和 hashlib 进行签名。

替换为你的 Gemini API 密钥和私钥

在使用 Gemini API 之前，务必将以下占位符替换为你实际的 API 密钥和私钥。请妥善保管你的私钥，切勿泄露给他人。API 密钥用于标识你的身份，私钥用于对请求进行签名，确保交易的安全性。

API_KEY = "YOUR_API_KEY"
SECRET_KEY = "YOUR_SECRET_KEY"

new_order(symbol, amount, price, side) 函数用于创建新的限价订单。此函数接收交易对代码（symbol）、数量（amount）、价格（price）和买卖方向（side）作为参数。

symbol ：指定交易对，例如 'btcusd' 代表比特币/美元交易对。
amount ：指定要交易的数量，以字符串形式表示。
price ：指定限价订单的价格，也以字符串形式表示。
side ：指定交易方向，可以是 'buy' (买入) 或 'sell' (卖出)。

def new_order(symbol, amount, price, side):
    """Creates a new limit order."""
    request_path = '/v1/order/new'
    payload = {
        'symbol': symbol,
        'amount': str(amount),
        'price': str(price),
        'side': side,
        'type': 'exchange limit'
    }

request_path 定义了 API 请求的路径。
payload 包含了订单的所有必要信息，以字典形式组织。订单类型设置为 'exchange limit'，表示这是一个在交易所挂单的限价订单。

    headers = generate_headers(request_path, payload, API_KEY, SECRET_KEY)

    try:
        response = requests.post('https://api.gemini.com' + request_path, headers=headers, =payload)
        response.raise_for_status()  # Raise HTTPError for bad responses (4xx or 5xx)
        return response.()
    except requests.exceptions.RequestException as e:
        print(f"Request failed: {e}")
        return None

generate_headers 函数 (未在此处定义，需要单独实现) 负责生成包含身份验证信息的 HTTP 请求头。这些头部信息用于验证请求的合法性。
requests.post 函数向 Gemini API 发送 POST 请求。请注意， =payload 参数用于将 payload 数据以 JSON 格式发送。 response.raise_for_status() 检查 HTTP 响应状态码。如果状态码表示错误 (4xx 或 5xx)，则会引发 HTTPError 异常。
如果请求成功， response.() 将返回 JSON 格式的响应数据，其中包含订单的详细信息。
如果在请求过程中发生任何异常，例如网络连接错误，则会捕获该异常并打印错误信息。

以下代码展示了如何调用 new_order 函数创建一个 BTCUSD 的限价买单，数量为 0.001，价格为 25000。

if __name__ == '__main__':
    # 创建一个 BTCUSD 的限价买单
    order_response = new_order(symbol='btcusd', amount=0.001, price=25000, side='buy')

    if order_response:
        print("Order created successfully:")
        print(.dumps(order_response, indent=4))
    else:
        print("Order creation failed.")

如果订单创建成功，将打印订单的详细信息 (使用 .dumps 格式化输出，使其更易于阅读)。如果订单创建失败，将打印错误信息。

最佳实践

• 安全: 务必将 API 密钥视为最高机密，采取一切必要措施妥善保管，例如使用环境变量存储，避免直接硬编码在程序中，并定期轮换密钥，以防止潜在的泄露风险，保障账户安全。
• 错误处理: API 调用可能会因为各种原因失败，因此必须全面且细致地处理 API 返回的各种错误信息，包括但不限于网络连接错误、身份验证失败、请求参数错误等。针对不同类型的错误，制定相应的处理策略，例如重试机制、降级方案或友好的错误提示，确保程序的健壮性和用户体验。
• 速率限制: 交易所或其他 API 提供商通常会设置速率限制，以防止滥用和保障系统稳定。因此，需要合理控制 API 请求的频率，可以通过设置请求队列、使用令牌桶算法或漏桶算法等方式来平滑请求流量。同时，需要监控 API 的速率限制状态，并在达到限制时采取适当的措施，例如暂停请求或指数退避重试，避免触发速率限制导致服务中断。
• 数据验证: 虽然 API 提供商会尽力保证数据的准确性，但仍然有可能出现错误或异常数据。为了确保程序的正确性，必须对 API 返回的数据进行严格的验证，包括但不限于数据类型检查、范围检查、格式检查等。对于无效或异常的数据，需要采取适当的处理措施，例如丢弃数据、记录日志或进行数据修复，避免错误的数据影响程序的逻辑。
• 使用 WebSocket API: 对于需要实时数据的应用程序，例如实时交易、行情监控等，强烈建议使用 WebSocket API。WebSocket 是一种持久化的双向通信协议，可以实时推送数据，避免了传统 HTTP API 的轮询开销，降低延迟，提高效率。在使用 WebSocket API 时，需要注意连接管理、心跳机制、消息重连等问题，确保连接的稳定性和数据的可靠性。
• 监控: 持续监控 API 请求的各项指标，例如成功率、延迟、请求量等，是保障应用程序稳定运行的关键。通过监控，可以及时发现和解决潜在的问题，例如 API 服务故障、网络连接问题、性能瓶颈等。可以使用各种监控工具和平台，例如 Prometheus、Grafana、Datadog 等，来收集和分析监控数据，并设置告警规则，以便在出现问题时及时通知相关人员进行处理。