Gemini API现货交易指南：轻松对接，玩转数字货币！

时间： 分类：动态 阅读：35

Gemini 现货交易 API 接口使用

概述

Gemini 提供了一套功能强大的 REST API，旨在为开发者提供无缝接入其数字资产交易平台的途径。通过这套 API，开发者能够执行现货交易、实时查询市场数据、高效管理账户资产，并构建自定义的交易策略和自动化交易机器人。本文将深入探讨如何有效利用 Gemini 的现货交易 API 接口，内容涵盖身份验证机制、常用 API 接口的调用方法、以及应对潜在错误的处理策略。还将详细介绍请求的构造方式，例如添加时间戳和签名，确保交易请求的安全性。

身份验证

使用 Gemini API 接口，进行身份验证是首要步骤。Gemini 采用 API 密钥（API Key）和密钥（Secret Key）相结合的方式来验证用户的身份。API 密钥的作用在于唯一标识您的应用程序，类似于应用程序的用户名。而密钥则用于对 API 请求进行数字签名，验证请求的来源和完整性，防止篡改和伪造，从而确保请求的安全性。在进行身份验证时，请务必妥善保管您的 Secret Key，避免泄露，因为任何持有您 Secret Key 的人都可以代表您的应用程序发起请求。

获取 Gemini API Key 和 Secret Key：

  1. 登录您的 Gemini 账户。请确保您已完成账户注册和身份验证，并开启双重验证以提高安全性。
  2. 导航至 API 设置页面。您通常可以在账户设置或安全设置的相关页面中找到 API 相关的选项。具体路径可能因 Gemini 平台更新而有所调整。
  3. 创建新的 API Key，并仔细设置相应的权限。权限设置至关重要，它决定了该 API Key 能够执行的操作。
    • 交易权限： 允许您通过 API 进行买卖操作。请谨慎授予此权限，并仅在需要时启用。
    • 余额查询权限： 允许您查询账户余额。这是一个相对安全的权限，可以用于监控账户状态。
    • 其他权限： 根据您的需求，Gemini 可能会提供其他更细粒度的权限控制，例如充提币权限、历史数据查询权限等。请仔细阅读每个权限的说明，并根据实际情况进行选择。
    请务必遵循最小权限原则，仅授予 API Key 执行必要操作的最小权限，以降低安全风险。为每个需要不同权限的应用或脚本创建单独的 API Key，可以进一步隔离风险。
  4. 保存 API Key 和 Secret Key。 请务必妥善保管 Secret Key，切勿将其泄露给任何人。Secret Key 是访问您 Gemini 账户的密钥，一旦泄露，他人可能会利用您的账户进行非法操作。
    • 存储安全： 将 Secret Key 存储在安全的地方，例如使用密码管理器进行加密存储。
    • 避免明文存储： 切勿将 Secret Key 以明文形式存储在代码、配置文件或任何公共可访问的地方。
    • 定期更换： 定期更换 API Key 和 Secret Key，可以降低因密钥泄露带来的风险。
    • 监控使用情况： 密切监控 API Key 的使用情况，如有异常活动，立即禁用该 API Key 并更换新的密钥。

生成 Payload 和签名：

为了确保 API 请求的安全性与完整性，所有请求都必须经过严格的签名验证。签名过程是验证请求来源以及防止数据篡改的关键措施。以下是详细的签名生成步骤：

  1. 构建 Payload：

    Payload 实际上是一个包含了所有必要请求信息的 JSON 对象。这个对象是 API 请求的核心，它精确地定义了请求的行为。Payload 中通常会包含以下关键字段：

    • 请求路径 (Request Path): 明确指定了 API 接口的访问地址，例如 /api/v1/orders 。
    • 时间戳 (Timestamp): 记录请求发起的确切时间，通常以 Unix 时间戳（秒或毫秒）表示。时间戳用于防止重放攻击，确保请求的时效性。
    • 请求参数 (Request Parameters): 包含了 API 请求所需的各种参数，例如订单 ID、数量、价格等。这些参数以键值对的形式存在。
    • 其他元数据 (Other Metadata): 根据 API 的具体要求，Payload 还可以包含其他必要的信息，例如 API 版本号、客户端 ID 等。

  2. Base64 编码 Payload：

    构建好 JSON 格式的 Payload 后，需要将其转换为 Base64 编码的字符串。Base64 编码是一种常用的将二进制数据转换为 ASCII 字符串的编码方式，目的是为了方便数据在网络上传输，并避免特殊字符造成的干扰。 确保使用的 Base64 编码方案与 API 文档中规定的方案一致，避免出现编码错误。

  3. HMAC-SHA384 签名：

    使用保密的 Secret Key 对 Base64 编码后的 Payload 字符串进行 HMAC-SHA384 签名。HMAC-SHA384 是一种哈希消息认证码算法，它结合了哈希函数 SHA384 和一个密钥，能够有效地验证数据的完整性和来源。 Secret Key 必须妥善保管，绝对不能泄露给任何第三方，它是保障 API 安全的关键。 签名算法必须严格按照 API 文档中的要求进行，包括字符编码、大小写等细节。

  4. 添加签名到请求头：

    将生成的 HMAC-SHA384 签名结果添加到 HTTP 请求头中。通常，签名会被放在一个自定义的请求头字段中，例如 X-API-Signature 。 API 服务器会从请求头中提取签名，并使用相同的 Secret Key 和算法重新计算 Payload 的签名，然后与请求头中的签名进行比对。如果两个签名一致，则认为请求是有效的，否则请求会被拒绝。 请求头的字段名称和格式必须与 API 文档中规定的格式一致。

请求头：

在向 Gemini 交易平台或其他加密货币相关 API 发送请求时，准确设置请求头至关重要。请求头包含身份验证信息和数据格式描述，确保服务器能够正确理解和处理您的请求。以下详细说明了所需的请求头字段：

  • X-GEMINI-APIKEY : 这是您在 Gemini 平台上注册账户后获得的唯一 API 密钥。此密钥用于标识您的身份，并授权您访问受保护的 API 端点。请务必妥善保管您的 API 密钥，避免泄露给他人，否则可能导致您的账户被滥用。该 API 密钥通常与特定的权限集相关联，例如交易、查询余额或访问市场数据。
  • X-GEMINI-PAYLOAD : 这是经过 Base64 编码后的 JSON 格式的负载数据。负载数据包含了您请求的具体参数，例如交易类型、交易数量、价格等。在发送请求之前，需要将这些参数组合成 JSON 对象，然后使用 Base64 算法进行编码。Base64 编码将二进制数据转换为文本格式，以便在 HTTP 请求头中传输。确保编码后的字符串符合 Base64 规范，避免出现字符缺失或损坏。
  • X-GEMINI-SIGNATURE : 这是使用 HMAC-SHA384 算法生成的签名。签名用于验证请求的完整性和真实性，防止请求在传输过程中被篡改。生成签名需要使用您的私钥对 Payload 进行加密。HMAC-SHA384 是一种安全的哈希算法，它结合了哈希函数和密钥，能够有效防止中间人攻击。请仔细阅读 Gemini 平台的 API 文档，了解如何正确生成签名，并确保您的代码实现了正确的签名逻辑。
  • Content-Type : 此字段指定了请求体的媒体类型。对于使用 POST 方法发送的请求，通常需要将其设置为 application/ 。这告诉服务器您正在发送 JSON 格式的数据。正确的 Content-Type 值能够帮助服务器正确解析请求体，并将其转换为服务器端可处理的数据结构。 如果您发送的是其他类型的数据（例如表单数据），则需要相应地更改 Content-Type 值。

示例 (Python):

使用 Python 与加密货币交易所 Gemini 的 API 交互需要几个关键步骤，包括生成签名、构造请求头和处理响应。以下代码片段展示了如何使用 hashlib 、 hmac 、 base64 、 time 和 requests 库来实现这些步骤。

import hashlib import hmac import base64 import time import requests import # 显式导入 库

定义 API 密钥、密钥以及 API 的基本 URL。请务必将 YOUR_API_KEY 和 YOUR_SECRET_KEY 替换为您从 Gemini 获取的真实凭据。 API_URL 指向 Gemini API 的根端点。

API_KEY = "YOUR_API_KEY" SECRET_KEY = "YOUR_SECRET_KEY" API_URL = "https://api.gemini.com"

generate_signature 函数负责创建请求的数字签名。它接受一个 payload (字典)，将其序列化为 JSON 字符串，然后进行 Base64 编码。使用您的密钥和 SHA384 算法对此编码后的 payload 进行哈希处理，生成签名。此签名用于验证请求的真实性和完整性。

def generate_signature(payload): encoded_payload = base64.b64encode(.dumps(payload).encode('utf-8')) signature = hmac.new(SECRET_KEY.encode('utf-8'), encoded_payload, hashlib.sha384).hexdigest() return encoded_payload, signature

send_request 函数是发送 API 请求的核心。它接受一个端点 (endpoint) 和一个可选的 payload。该函数构建完整的 URL，生成一个 nonce (时间戳)，并将其添加到 payload 中。然后，调用 generate_signature 函数来创建签名。构造包含 API 密钥、编码后的 payload 和签名的 HTTP 头部，并使用 requests 库发送 POST 请求。

def send_request(endpoint, payload=None): url = API_URL + endpoint nonce = int(time.time() * 1000) # 使用毫秒级时间戳作为 nonce if payload is None: payload = {} payload['request'] = endpoint payload['nonce'] = nonce encoded_payload, signature = generate_signature(payload) 

headers = {
    'Content-Type': 'application/',  # 明确指定 JSON 内容类型
    'X-GEMINI-APIKEY': API_KEY,
    'X-GEMINI-PAYLOAD': encoded_payload.decode('utf-8'),
    'X-GEMINI-SIGNATURE': signature,
}

try:
    response = requests.post(url, headers=headers, data=.dumps(payload))
    response.raise_for_status()  # 为错误的响应（4xx 或 5xx）引发 HTTPError
    return response.() # 返回 JSON 格式的响应
except requests.exceptions.RequestException as e:
    print(f"请求失败: {e}")
    return None

常用 API 接口

获取账户信息

  • 接口: /v1/balances
  • 方法: POST
  • 权限: Balance

该接口用于查询指定账户的余额信息，涵盖可用余额、冻结余额以及其他相关账户状态。通过此接口，用户可以实时掌握其账户资产的分布情况，为交易决策提供数据支撑。

详细说明：

  • 可用余额： 指账户中可以立即用于交易或提现的资产数量。
  • 冻结余额： 指账户中暂时无法使用的资产数量，通常由于挂单、抵押或其他原因被锁定。
  • 权限说明： 调用此接口需要 Balance 权限，表明用户需要授权才能访问账户余额信息，确保数据安全。
  • 请求方式： 必须使用 POST 方法发送请求。请求体中通常包含账户标识等参数，用于指定要查询的账户。
  • 响应数据： 接口返回的数据通常为 JSON 格式，包含账户余额的详细信息，例如不同币种的可用余额和冻结余额。

注意事项：

  • 请确保在调用接口前已获得相应的授权。
  • 请妥善保管您的API密钥和访问权限，防止泄露。
  • 注意接口的调用频率限制，避免频繁调用导致服务不可用。

示例 Payload:

在加密货币API交互中，Payload是承载请求数据的关键组成部分。以下示例展示了一个典型的请求Payload结构，用于获取用户账户余额信息： 

{
  "request": "/v1/balances",
  "nonce": 1678886400000
}

字段详解：

  • request : 此字段指定了需要调用的API端点。在本例中， "/v1/balances" 表示请求获取用户账户余额的API接口。 准确的API endpoint路径对于服务器正确处理请求至关重要。
  • nonce : 这是一个一次性使用的随机数，用于防止重放攻击。 1678886400000 表示一个Unix时间戳（毫秒级）。 每次API调用时，nonce都应该是唯一的，以确保请求的安全性。 许多加密货币交易所和API服务提供商强烈建议使用Nonce，甚至强制使用，以保证交易的安全性。

重要提示：

  • 实际使用时，Payload可能包含更多字段，具体取决于API的需求。 例如，某些API可能需要身份验证信息（如API密钥、签名等）作为Payload的一部分。
  • 请务必参考具体的API文档，了解每个字段的含义、数据类型和取值范围。 不正确的Payload格式或无效的参数值可能导致API调用失败。
  • 为了安全起见，始终使用HTTPS协议发送Payload，以防止数据在传输过程中被窃取。

示例响应:

以下JSON格式示例展示了账户中持有的加密货币和法币余额，以及可用余额的详细信息。 


[
  {
    "currency": "BTC",
    "amount": "1.23456789",
    "available":  "1.23456789"
  },
  {
    "currency": "USD",
    "amount": "1000.00",
    "available": "1000.00"
  }
]

currency : 代表币种的字符串。在此示例中，"BTC" 代表比特币，"USD" 代表美元。 更普遍的，这个字段遵循ISO 4217货币代码标准或者加密货币的符号。

amount : 账户中持有的该币种的总余额。 它可以是已锁定、正在交易或者可自由支配的总额。

available : 账户中可以立即使用的该币种的余额。 这个余额通常小于或等于总余额（amount），因为它排除了被冻结或用于其他目的的资金。 例如，在交易过程中被锁定的资金将不会包含在 "available" 余额中。

请注意，实际返回的JSON数据可能包含更多字段，具体取决于API的设计和功能。

下单

  • 接口: /v1/order/new
  • 方法: POST
  • 权限: Trade

该接口用于创建新的交易订单。 通过此端点，用户可以提交买入或卖出指定加密货币的请求，触发交易操作。 请求需包含必要的订单参数，例如交易对、订单类型（市价单或限价单）、数量和价格（如果适用）。成功提交订单后，系统将根据市场情况和订单类型执行交易。

示例 Payload:

以下是一个用于创建交易订单的示例 JSON Payload，用于演示如何构造API请求。请注意，实际使用时需要替换为您的API密钥和签名。 

{
  "request": "/v1/order/new",
  "nonce": 1678886400000,
  "client_order_id": "my_order_123",
  "symbol": "BTCUSD",
  "amount": "0.01",
  "price": "20000.00",
  "side": "buy",
  "type": "exchange limit"
}

字段说明：

  • request : API请求的路径，这里表示创建新订单的接口。
  • nonce : 一个单调递增的数值，用于防止重放攻击。通常为Unix时间戳的毫秒数。必须确保每次请求的nonce值都比上一次大。
  • client_order_id : 客户端自定义的订单ID，用于方便用户追踪订单状态。这个ID应该是唯一的，并且由客户端生成。
  • symbol : 交易对代码，例如 "BTCUSD" 表示比特币兑美元。交易所会支持多种交易对。
  • amount : 交易数量，例如 "0.01" 表示0.01个比特币。注意精度问题，不同交易所对精度的要求不同。
  • price : 交易价格，例如 "20000.00" 表示每个比特币20000美元。这只在限价单中需要设置。
  • side : 交易方向，"buy" 表示买入，"sell" 表示卖出。
  • type : 订单类型，"exchange limit" 表示交易所限价单。 其他类型包括 "exchange market" (交易所市价单)。

重要提示：

  • 请务必确保您的API密钥和私钥的安全。
  • 在实际使用中，您需要根据交易所的API文档进行调整。
  • 错误的Payload会导致订单创建失败，请仔细检查每个字段的值。
  • nonce 必须是唯一的且递增的，使用时间戳可以有效避免重复。
  • 不同的交易所对 amount 和 price 的精度要求不同，请根据实际情况调整。

参数说明:

  • client_order_id : 客户端自定义订单 ID，用于在交易所内唯一标识您的订单。建议使用 UUID 等方式生成，方便您进行订单跟踪和管理。交易所通常会返回此 ID，您可以通过此 ID 查询订单状态。
  • symbol : 交易对，指定您希望交易的资产对。例如，"BTCUSD" 表示比特币兑美元，"ETHBTC" 表示以太坊兑比特币。确保您输入的交易对符合交易所支持的格式，且大小写正确。
  • amount : 交易数量，表示您希望买入或卖出的资产数量。数量的单位取决于交易对，例如，在 BTCUSD 交易对中， amount 指的是比特币的数量。请注意交易所对最小交易数量的限制。
  • price : 交易价格，仅在限价单 ( exchange limit ) 中有效。表示您愿意买入或卖出的价格。买入时，只有价格低于或等于此价格，订单才会被执行。卖出时，只有价格高于或等于此价格，订单才会被执行。
  • side : 交易方向，指定您是想买入还是卖出。"buy" 表示买入，"sell" 表示卖出。这是交易指令的核心参数，必须正确设置。
  • type : 订单类型，指定订单的执行方式。例如，"exchange limit" 表示限价单，只有达到指定价格才会成交；"exchange market" 表示市价单，会立即以当前市场最优价格成交。其他常见的订单类型还包括止损限价单等，具体取决于交易所的支持。

示例响应:

以下 JSON 格式的数据展示了一个加密货币交易订单的示例响应，其中包含了关于订单的详细信息，可以帮助开发者理解订单的状态和执行情况。

{ "order id": "1234567890", 该字段是交易所为该订单分配的唯一标识符，用于在交易所系统中跟踪和管理订单。每个订单ID都是独一无二的，便于追踪订单状态。
"client order id": "my order_123", 客户端订单ID，允许用户自定义订单标识符，方便用户在自己的系统内管理和匹配订单，提高订单管理的效率。
"symbol": "BTCUSD", 交易对，表示交易的加密货币对，这里是比特币兑美元。该字段定义了交易的基础货币和计价货币。
"amount": "0.01", 订单数量，表示希望交易的加密货币数量，单位为基础货币。例如，这里表示要购买0.01个比特币。
"price": "20000.00", 订单价格，表示希望交易的价格，单位为计价货币。这是一个限价单，意味着只有当市场价格达到或低于此价格时，订单才会被执行。
"side": "buy", 交易方向，表示是买入还是卖出。这里是 "buy"，表示要购买指定的加密货币。
"type": "exchange limit", 订单类型，表示订单的类型。 "exchange limit" 表示这是一个交易所限价单，只有在达到指定价格时才会成交。
"timestamp": "1678886400", 订单创建时间戳，表示订单创建的Unix时间戳，单位为秒。
"timestampms": 1678886400000, 订单创建时间戳，与上一个字段相同，但单位为毫秒，提供更高精度的时间信息。
"is live": true, 订单状态，表示订单是否处于活动状态。 "true" 表示订单当前有效，尚未完全成交或被取消。
"is cancelled": false, 订单取消状态，表示订单是否已被取消。 "false" 表示订单当前未被取消。
"is hidden": false, 订单隐藏状态，表示订单是否对市场可见（仅适用于某些高级订单类型，如冰山订单）。 "false" 表示订单在市场上可见。
"avg execution price": null, 平均成交价格，表示订单的平均成交价格。由于订单尚未成交或完全成交，所以这里显示为 "null"。
"executed_amount": "0.00" 已成交数量，表示订单已成交的加密货币数量。由于订单尚未成交，所以这里显示为 "0.00"。 }

取消订单

  • 接口: /v1/order/cancel
  • 方法: POST
  • 权限: Trade

该接口允许用户取消其先前提交的交易订单。 使用此接口，您可以撤销尚未完全成交的挂单。 需要注意的是，只有在订单状态允许取消的情况下，取消操作才会成功执行。 部分已成交的订单，或者已进入结算流程的订单，可能无法取消。

为成功取消订单，用户必须拥有 Trade 权限。 此权限通常与账户的交易功能相关联，需要确保API密钥或访问令牌具有执行交易操作的授权。 未经授权的请求将会被拒绝，并返回相应的错误代码。

示例 Payload:

以下 JSON Payload 展示了一个取消订单请求的示例，用于与加密货币交易所或交易平台 API 进行交互。该 Payload 包含了发起取消订单请求所需的关键信息。 

{
  "request": "/v1/order/cancel",
  "nonce": 1678886400000,
  "order_id": "1234567890"
}

字段解释：

  • request: 指定 API 端点，指示这是一个取消订单的请求。在这个例子中， /v1/order/cancel 是一个假设的 API 路径，实际路径取决于交易所的具体 API 文档。
  • nonce: 一个时间戳，用于确保每个请求的唯一性，防止重放攻击。这是一个自 Unix 纪元（1970 年 1 月 1 日 00:00:00 UTC）以来的毫秒数。服务端通常会验证 nonce 值，确保它大于上一个已处理的 nonce 值，并且在一定的时间窗口内。
  • order_id: 需要取消的订单的唯一标识符。这是一个由交易所生成的字符串，用于追踪特定的交易订单。必须替换成你要取消的订单的实际 ID。

重要提示：

  • 以上 Payload 仅为示例，实际使用的 Payload 结构和字段可能因交易所 API 的不同而有所差异。请务必参考目标交易所的官方 API 文档。
  • 除了上述字段，有些交易所的 API 可能还需要额外的参数，例如 API 密钥、签名信息等，以进行身份验证和授权。
  • 在发送请求之前，务必使用正确的 API 密钥对 Payload 进行签名，以确保请求的安全性。签名算法和方法也需要参考交易所的 API 文档。
  • nonce 值的生成需要确保每次请求的唯一性，可以使用时间戳或递增的序列号。时间戳必须是单调递增的，避免出现时间戳回退导致请求被拒绝。
  • order_id 必须是有效的、存在于交易所订单簿中的订单 ID。取消不存在的订单可能会导致错误。

参数说明:

  • order_id : 要取消的订单 ID。此参数为字符串类型，代表您希望撤销的订单的唯一标识符。请确保提供正确的订单 ID，否则取消操作可能无法成功。订单 ID 通常在您创建订单时生成，并在订单确认信息或订单历史记录中显示。

示例响应:

以下JSON格式的数据结构展示了一个订单的详细信息，用于在加密货币交易所中追踪和管理订单状态：

{ "order_id": "1234567890",

订单ID，交易所生成的唯一标识符，用于追踪特定订单。通常是一个字符串，方便系统处理和存储。

"client_order_id": "my_order_123",

客户端订单ID，由用户或交易平台自定义的订单标识符，允许用户更方便地在自己的系统中追踪和管理订单。它与交易所的订单ID关联，方便查找。

"symbol": "BTCUSD",

交易对，表示订单交易的两种资产。例如，"BTCUSD" 表示比特币 (BTC) 和美元 (USD) 之间的交易。

"amount": "0.01",

订单数量，表示用户想要买入或卖出的加密货币数量。在这个例子中，用户想买入0.01个BTC。

"price": "20000.00",

订单价格，用户愿意为此数量的加密货币支付的价格。这是一个限价单，表示用户只愿意以20000.00美元的价格购买一个比特币的一部分（0.01个BTC）。

"side": "buy",

订单方向，指定订单是买入还是卖出。 "buy" 表示买入订单， "sell" 表示卖出订单。

"type": "exchange limit",

订单类型，描述订单执行的方式和条件。 "exchange limit" 表示限价单，只有当市场价格达到或优于指定价格时才会执行。其他类型包括市价单、止损单等。

"timestamp": "1678886400",

订单创建时间戳，表示订单创建时的 Unix 时间戳，以秒为单位。例如，1678886400代表自1970年1月1日以来经过的秒数。

"timestampms": 1678886400000,

订单创建时间戳，与上面的 "timestamp" 相同，但精度更高，以毫秒为单位。 1678886400000 代表自1970年1月1日以来经过的毫秒数。

"is_live": false,

订单活跃状态，指示订单当前是否在交易所的订单簿中活跃。 "false" 表示订单已完成、取消或过期。

"is_cancelled": true,

订单取消状态，指示订单是否已被用户或系统取消。"true" 表示订单已被取消，不再有效。

"is_hidden": false,

订单隐藏状态，指示订单是否对其他交易者可见。 "false" 表示订单在公开订单簿中可见。 这通常用于大额订单，以减少市场影响。

"avg_execution_price": null,

平均执行价格，表示订单的实际成交均价。如果订单尚未完全成交或未成交，则此值为 null。如果订单分多次成交，则此值为所有成交价格的加权平均值。

"executed_amount": "0.00" }

已执行数量，表示订单已成交的加密货币数量。 "0.00" 表示订单尚未成交或已完全取消。

查询订单状态

  • 接口: /v1/order/status
  • 方法: POST
  • 权限: Order Status - 调用此接口需要具备 "Order Status" 权限，以确保只有授权用户才能访问订单状态信息。

该接口用于查询指定订单的状态信息。通过此接口，您可以检索订单的详细状态，例如：已创建、已支付、处理中、已发货、已完成、已取消或失败等。 订单状态对于跟踪交易流程和解决潜在问题至关重要。

调用此接口时，通常需要提供订单ID作为请求参数。服务器将根据订单ID检索并返回相应的状态信息。返回的数据结构可能包含订单创建时间、支付时间、更新时间、当前状态、物流信息(如果适用)等详细字段。请参考API文档中关于请求参数和响应数据的详细说明。

示例 Payload:

以下是一个用于查询订单状态的示例 JSON Payload，它遵循特定的API接口规范，并包含了必要的参数以确保请求的有效性和安全性。 

{
  "request": "/v1/order/status",
  "nonce":  1678886400000,
  "order_id": "1234567890"
}

字段解释：

  • request : API请求的路径，指定了需要调用的API端点。 在此示例中， "/v1/order/status" 表示查询订单状态的API接口。 正确的请求路径是服务器正确处理请求的关键。
  • nonce : 一个时间戳，以毫秒为单位表示。 用于防止重放攻击，确保每个请求的唯一性。 服务器会验证 nonce 是否在可接受的时间范围内。如果 nonce 值过旧，服务器可能会拒绝该请求。
  • order_id : 需要查询的订单的唯一标识符。 订单ID用于在数据库或订单管理系统中查找特定的订单信息。 务必确保 order_id 的准确性，以便获取正确的订单状态。

重要提示：

  • 实际的API请求可能需要其他参数，例如签名( signature )，用于验证请求的完整性和身份。
  • 请务必参考具体的API文档，以了解所有必需的参数和正确的格式。
  • 为了安全起见，请勿在客户端代码中硬编码敏感信息，例如API密钥。 建议使用安全的方式存储和管理这些信息。

参数说明:

  • order_id : 要查询的订单 ID。这是一个字符串类型的参数，用于唯一标识要查询的特定订单。订单ID通常由交易平台或订单系统生成，并用于追踪和检索订单的详细信息。请确保提供的 order_id 是有效的，并且与您要查询的订单完全匹配，否则将无法正确检索到订单信息。

示例响应:

以下 JSON 格式的数据结构展示了一个订单执行成功的示例，详细说明了订单的关键属性。

{
"order_id": "1234567890",
// 平台生成的唯一订单标识符。
"client_order_id": "my_order_123",
// 客户端自定义订单标识符，便于订单管理和追踪。
"symbol": "BTCUSD",
// 交易对，表示交易的资产对。这里表示比特币 (BTC) 兑美元 (USD)。
"amount": "0.01",
// 订单数量，表示交易的资产数量。这里表示 0.01 BTC。
"price": "20000.00",
// 订单价格，表示交易的资产价格。这里表示 20000.00 美元。
"side": "buy",
// 订单方向，表示买入或卖出。这里表示买入。
"type": "exchange limit",
// 订单类型，表示订单的执行方式。这里表示交易所限价单。
"timestamp": "1678886400",
// 订单创建时间戳，表示订单创建的 Unix 时间戳（秒）。
"timestampms": 1678886400000,
// 订单创建时间戳，表示订单创建的 Unix 时间戳（毫秒）。
"is_live": false,
// 订单是否活跃，表示订单是否在交易中。false 表示已完成或已取消。
"is_cancelled": false,
// 订单是否已取消，表示订单是否被用户或系统取消。
"is_hidden": false,
// 订单是否隐藏，通常用于策略订单，不直接暴露给市场。
"avg_execution_price": "20000.00",
// 平均成交价格，表示订单的平均成交价格。
"executed_amount": "0.01"
// 已成交数量，表示订单已成交的资产数量。
}

获取所有未成交订单

  • 接口: /v1/orders
  • 方法: POST
  • 权限: Order Status

该接口用于查询所有未成交的订单。通过此接口，用户可以检索其在交易所或平台上的挂单状态，即尚未完全成交或部分成交的订单。这对于监控市场活动、调整交易策略以及管理未决订单至关重要。

接口说明：

  • 用途： 检索用户账户中所有未成交的限价单、市价单等各种类型的订单。
  • 请求方式： 使用 POST 方法提交请求。
  • 权限要求： 需要拥有 Order Status 权限才能访问此接口。这通常需要用户完成身份验证和授权，以确保只有授权用户才能查看其订单信息。

注意事项：

  • 返回的数据可能包含大量的订单信息，建议在客户端进行分页处理，以提高性能。
  • 订单状态可能包括“已挂单”、“部分成交”等多种状态，具体取决于交易所或平台的实现。
  • 请务必妥善保管您的API密钥和访问凭证，防止泄露，避免未经授权的访问。

示例 Payload:

在加密货币交易中，Payload 是指包含要执行的具体指令和数据的消息体。以下是一个用于创建订单的示例 Payload，它以 JSON 格式呈现，常用于与交易平台 API 进行交互： 

{
  "request": "/v1/orders",
  "nonce": 1678886400000
}

字段说明：

  • request : 指定 API 端点，表明请求的具体功能。 在此示例中， "/v1/orders" 表示请求在交易所创建一个新的订单。 不同的端点用于不同的操作，例如查询账户余额、获取市场数据或取消订单。
  • nonce : 一个唯一的数字，用于防止重放攻击。 nonce 必须是单调递增的，即每次请求都应使用一个比上次使用的值更大的 nonce 。 通常，使用 Unix 时间戳（毫秒级）是一个常见的做法。 在此示例中， 1678886400000 代表一个 Unix 时间戳。 交易所会验证 nonce 值，如果检测到重复或无效的值，则会拒绝请求。

安全提示：

  • 实际应用中，Payload 还需要包含其他必要的参数，例如交易对 (symbol)、订单类型 (order type)、价格 (price) 和数量 (quantity) 等。
  • 为了保证安全性，Payload 通常需要使用私钥进行签名。 签名可以确保请求的完整性和真实性，防止数据被篡改或伪造。
  • 注意保护好自己的私钥，切勿泄露给他人。 私钥泄露会导致资金损失。

示例响应:

接口将返回一个JSON数组，其中包含了当前账户所有未成交订单的详细信息。数组中的每个元素代表一个未成交订单，包含了诸如订单ID、交易对、订单类型（限价单、市价单等）、委托价格、委托数量、已成交数量、订单状态（等待成交、部分成交等）、下单时间等关键字段。开发者可以通过解析此数组，获取用户账户中所有未完成交易的实时状态，并根据这些信息进行相应的策略调整或风险控制。

获取Ticker 信息

  • 接口: /v1/pubticker/{symbol}
  • 方法: GET
  • 权限: 不需要身份验证

该接口用于查询指定交易对的实时Ticker信息，提供了关键的市场数据指标。Ticker信息包含了交易对在最近一段时间内的价格变动和交易活动概要，有助于用户快速了解市场动态。

详细说明：

  • 接口说明: /v1/pubticker/{symbol} API端点用于获取特定交易对的Ticker数据。 {symbol} 部分需要替换为具体的交易对代码，例如 BTCUSD 代表比特币对美元。
  • 请求方法: 使用 GET 方法发送HTTP请求。
  • 权限要求: 此接口为公开接口，无需提供API密钥或进行身份验证即可访问。

返回数据包含以下关键信息：

  • 最高价 (High): 指定时间段内交易对达到的最高价格。
  • 最低价 (Low): 指定时间段内交易对达到的最低价格。
  • 最新成交价 (Last): 最新的成交价格。
  • 成交量 (Volume): 指定时间段内交易对的总成交量，通常以基础货币计价。
  • 卖一价 (Ask): 当前市场上最优的卖出价格。
  • 买一价 (Bid): 当前市场上最优的买入价格。
  • 时间戳 (Timestamp): 数据更新的时间戳，通常为Unix时间戳。

使用场景：

  • 价格监控: 实时监控交易对的价格波动，用于快速捕捉市场机会。
  • 量化分析: 作为量化交易策略的输入数据，用于分析市场趋势和预测价格走势。
  • 数据展示: 在交易平台或数据网站上展示实时市场数据。

示例 请求:

GET https://api.gemini.com/v1/pubticker/BTCUSD

此请求使用 HTTP GET 方法从 Gemini 交易所的公共 API 获取关于比特币 (BTC) 兑换美元 (USD) 的最新交易信息。 /v1/pubticker/BTCUSD 是 API 的端点，专门提供指定交易对（此处为 BTCUSD）的ticker 信息。

Ticker 信息通常包括以下关键数据点：

  • last: 上一笔成交的价格。
  • bid: 当前最高的买单价格。
  • ask: 当前最低的卖单价格。
  • volume: 过去 24 小时的成交量（以基础货币 BTC 计）。
  • high: 过去 24 小时的最高成交价。
  • low: 过去 24 小时的最低成交价。
  • timestamp: 数据更新的时间戳（通常是 Unix 时间戳）。

通过访问此端点，开发者和交易者可以实时监控 BTCUSD 的价格变动，并将其应用于自动化交易策略、市场分析或简单的数据展示。

请注意，Gemini API 可能有速率限制和身份验证要求，具体取决于您要访问的端点和服务。 公共 ticker 端点通常不需要 API 密钥，但其他需要访问用户账户信息的端点则需要。

示例响应:

以下JSON格式的数据展示了加密货币交易平台返回的市场信息，用于了解特定加密货币的实时价格和交易量。 

{
  "ask": "27000.00",
  "bid": "26999.99",
  "last": "26999.99",
  "volume": {
    "BTC": "100.00",
    "USD": "2700000.00"
  },
  "timestamp": 1678886400
}

字段解释：

  • ask (卖价): 当前市场上最高的卖单价格，即您购买该加密货币的最低价格。例如， "ask": "27000.00" 表示您可以以 27000.00 美元的价格购买一个比特币。
  • bid (买价): 当前市场上最高的买单价格，即您出售该加密货币的最高价格。例如， "bid": "26999.99" 表示您可以以 26999.99 美元的价格出售一个比特币。
  • last (最新成交价): 最近一笔交易的成交价格。例如， "last": "26999.99" 表示最近一次比特币交易的价格为 26999.99 美元。
  • volume (交易量): 指定时间段内的交易量，通常以24小时为周期。
    • BTC: 以比特币为单位的交易量。例如， "BTC": "100.00" 表示在过去 24 小时内交易了 100 个比特币。
    • USD: 以美元为单位的交易量。例如， "USD": "2700000.00" 表示在过去 24 小时内交易了价值 2700000 美元的比特币。
  • timestamp (时间戳): 指示数据更新的时间，通常以 Unix 时间戳表示，即自 1970 年 1 月 1 日午夜（UTC/GMT 的午夜）以来的秒数。例如， "timestamp": 1678886400 表示时间戳为 1678886400。可以使用在线工具将此时间戳转换为可读的日期和时间。

注意事项：

  • 这些数据是动态的，会随市场波动而实时变化。
  • 不同交易平台的价格可能略有差异。
  • 交易量是评估市场活跃度的重要指标。

错误处理

Gemini API 接口使用标准的 HTTP 状态码，并配合 JSON 格式的详细错误信息，以便开发者能够准确诊断和处理在与 API 交互过程中遇到的问题。

  • HTTP 状态码: HTTP 状态码是网络通信中的标准响应代码，用于指示请求的结果。 200 状态码表示请求已成功处理。 4xx 范围的状态码指示客户端错误，意味着请求本身存在问题，例如缺少必要的参数、参数格式错误或身份验证失败。 5xx 范围的状态码指示服务器端错误，表明服务器在尝试处理请求时遇到了意外情况。 具体错误码及其含义可以参考标准的 HTTP 协议文档。
  • 错误信息 (JSON 格式): 当发生错误时，Gemini API 会返回一个 JSON 对象，其中包含详细的错误信息。 该 JSON 对象至少包含两个关键字段： result 和 message 。 result 字段的值固定为 "error"， 用于明确标识这是一个错误响应。 message 字段则包含更具体的、人类可读的错误描述，例如 "Insufficient funds" (资金不足) 或 "Invalid API key" (无效的 API 密钥)。 开发者应仔细解析 message 字段的内容，以便了解错误的具体原因并采取相应的纠正措施。 API 返回的 JSON 对象可能包含其他与错误相关的补充信息，建议查阅 API 文档以获取更详细的错误信息结构。

示例错误响应:

以下是一个 API 调用失败的 JSON 响应示例，展示了在加密货币 API 交互中可能出现的错误情况： 


{
  "result": "error",
  "message":  "Invalid API Key."
}

上述 JSON 结构表明 API 请求未成功， "result" 字段被设置为 "error" ，并且 "message" 字段提供了关于错误的详细描述，这里是 "Invalid API Key."。在实际应用中，API 可能会返回更具体的错误信息，例如："API Key is missing"，"API Key is expired" 等。

在开发与加密货币相关的应用程序时，对 API 响应进行适当的错误处理至关重要。这包括检查 HTTP 状态码以及解析响应体中的错误信息。通常，除了检查 "result" 字段，还需要关注 HTTP 状态码。例如，400 状态码通常表示客户端请求错误，而 500 状态码表示服务器内部错误。

针对 "Invalid API Key." 错误，开发者应该采取以下步骤进行处理：

  • 检查 API Key 的正确性： 确保使用的 API Key 与服务提供商提供的完全一致。API Key 区分大小写，并且可能包含特殊字符。
  • 验证 API Key 是否已激活： 某些 API Key 需要在使用前激活。请检查 API 提供商的文档，确认 API Key 是否处于激活状态。
  • 检查 API Key 的权限： 某些 API Key 可能仅具有有限的访问权限。请确保 API Key 拥有执行所需操作的权限。例如，如果需要访问交易历史记录，API Key 必须具有相应的读取权限。
  • 处理 API Key 过期情况： API Key 可能具有有效期。如果 API Key 已过期，则需要向服务提供商申请新的 API Key。
  • 实施重试机制： 对于间歇性错误（例如网络问题），可以实施自动重试机制，但需要注意避免过度请求 API，以免触发限流策略。
  • 记录错误日志： 将 API 错误信息记录到日志中，以便进行调试和故障排除。

通过对 API 响应进行全面的检查和处理，可以提高应用程序的稳定性和可靠性，并为用户提供更好的体验。应该参考 API 提供商的文档，了解所有可能的错误代码和相应的处理方法。

速率限制

Gemini API 接口实施速率限制，旨在维护系统稳定性和公平性。当请求频率超过预设的限制时，API 将返回 HTTP 429 状态码，指示“请求过多”。为避免触发速率限制并确保应用程序的平稳运行，开发者应谨慎管理 API 请求的发送频率。具体的速率限制策略，包括不同端点的限制和时间窗口，详尽地记录在 Gemini 官方文档中。通常情况下，已认证（authenticated）的请求相较于未认证请求，可能拥有更高的速率限制，但滥用仍可能导致限制。

对于使用 API Key 进行身份验证的请求，严格遵守速率限制至关重要。若违反速率限制，服务器将返回错误，影响应用程序功能。一种优雅的处理方式是实现指数退避算法。该算法在每次收到 429 错误时，都会逐步增加请求重试的等待时间，有效避免了对服务器的进一步过载，同时增加了请求最终成功的可能性。退避时间通常以指数级别增长，例如 2 的幂次方，直至达到预设的最大重试次数或最大等待时间。这确保了在速率限制解除后，应用程序能够平稳恢复正常运行，而不会立即再次触发限制。除了指数退避，还可以考虑使用令牌桶算法或其他流量整形技术，进一步优化 API 请求的发送策略。

安全性建议

  • 保护 Secret Key： Secret Key（私钥）是访问和控制您账户的最高权限凭证，务必将其视为如同银行密码一样重要。绝对不要以任何方式与任何人分享您的 Secret Key，包括平台客服人员。将其安全地存储在离线环境中，例如物理媒介或硬件钱包中，可以有效防止未经授权的访问。定期审查和更新您的 Secret Key 存储策略，确保其始终处于最高安全级别。使用强密码生成器创建复杂的 Secret Key，并避免使用容易猜测的词语或个人信息。
  • 使用 HTTPS： 所有 API 请求必须通过 HTTPS（Hypertext Transfer Protocol Secure）协议进行，HTTPS 通过 SSL/TLS 加密数据传输，有效防止数据在传输过程中被窃取或篡改。确保您的代码或应用程序强制使用 HTTPS 连接，并检查服务器是否配置了有效的 SSL/TLS 证书。避免使用 HTTP 协议进行 API 调用，因为它不提供任何加密保护，容易受到中间人攻击。
  • 验证服务器证书： 为了防止中间人攻击，在发送 API 请求时，不仅要使用 HTTPS，还要验证服务器提供的 SSL/TLS 证书的有效性。这包括检查证书是否由受信任的证书颁发机构（CA）签名，以及证书的域名是否与您要访问的服务器域名一致。许多编程语言和库都提供了验证服务器证书的功能，务必启用这些功能以确保安全。
  • 设置 API Key 权限： 在创建 API Key 时，遵循最小权限原则，仅授予 API Key 执行特定任务所需的最低权限。例如，如果 API Key 只需要读取市场数据，则不要授予其交易或提款权限。精细化的权限控制可以最大程度地降低 API Key 泄露或被恶意利用造成的损失。定期审查 API Key 的权限设置，并根据实际需求进行调整。
  • 定期更新 API Key： 定期更换 API Key 是一种有效的安全措施，即使 API Key 在不知情的情况下泄露，也可以通过更换 API Key 来阻止潜在的恶意活动。建议至少每 3-6 个月更换一次 API Key，或者在怀疑 API Key 泄露时立即更换。在更换 API Key 后，确保及时更新所有使用该 API Key 的应用程序或脚本。
  • 监控 API 使用情况： 密切监控 API 的使用情况，包括请求频率、请求来源 IP 地址、请求类型等。通过监控 API 使用情况，可以及时发现异常行为，例如突然出现大量请求、来自未知 IP 地址的请求、或超出 API Key 权限范围的请求。建立一套完善的 API 监控系统，并设置告警机制，以便在发现异常情况时及时采取措施。

相关推荐：