当前位置：首页 > 焦点 > 正文

Gemini交易所REST API深度解析：交易与数据全攻略

焦点
时间：2025-02-27
访问：79

本文详细介绍了Gemini交易所REST API的关键功能，包括市场数据（Ticker、OrderBook）和交易接口，并提供了实际示例，帮助开发者更好地理解和使用Gemini API。

Gemini交易所REST API文档解读：交易、市场数据与账户管理

Gemini交易所的REST API提供了一套全面的接口，允许开发者通过编程方式访问交易所的各种功能，包括获取市场数据、执行交易、管理账户等。本文将深入探讨Gemini API的关键功能，并结合实际场景进行解读。

市场数据

Gemini API提供了一系列全面的市场数据接口，旨在为开发者提供便捷的途径来获取实时和历史的加密货币交易信息。这些接口允许用户访问包括但不限于以下数据：

实时价格： 获取特定交易对的最新成交价格，为用户提供即时的市场动态。
交易量： 监控交易对在特定时间段内的交易活动，了解市场流动性。
订单簿： 查询当前买单和卖单的价格和数量分布，深入了解市场深度和潜在的价格支撑或阻力位。
历史交易数据： 访问特定交易对的历史成交记录，用于回溯测试交易策略和进行市场趋势分析。数据粒度可以从分钟级别到日级别不等，满足不同分析需求。
蜡烛图数据： 以OHLC（开盘价、最高价、最低价、收盘价）格式获取历史价格数据，用于技术分析和识别价格形态。

开发者可以利用这些数据构建自动交易机器人、开发行情分析工具、进行量化研究以及创建个性化的加密货币信息展示平台。 Gemini API的数据接口经过精心设计，确保数据的高可用性和低延迟，从而满足对实时性和准确性有较高要求的应用场景。使用API时，请务必遵守Gemini的使用条款和数据访问频率限制，以确保稳定可靠的服务。

Ticker数据

通过 /v1/ticker/:symbol 端点，可以获取特定交易对（例如BTCUSD、ETHUSDT等）的实时市场数据。此端点提供对市场状态的快照，包括最新价格、交易量及其他关键指标。该端点允许开发者监控交易对的表现，并构建基于实时数据的交易策略和分析工具。响应数据以JSON格式返回，包含以下关键字段，确保数据的精确性和及时性：

ask : 当前最佳卖价。代表市场上愿意出售该资产的最低价格。这对于理解市场供应情况至关重要。
bid : 当前最佳买价。代表市场上愿意购买该资产的最高价格。这对于理解市场需求情况至关重要。
last : 最新成交价。代表该交易对的最近一次成交价格。这是市场活动的一个关键指标，反映了最新的市场共识价格。
volume : 24小时成交量。代表过去24小时内该交易对的交易总量，通常以标价货币单位计。成交量是衡量市场活跃度和流动性的重要指标。较高的成交量通常表示更强的市场兴趣和更容易执行交易。
timestamp : 数据更新的时间戳，通常以Unix时间戳格式表示，精确到毫秒或微秒级别。
open : 24小时前的开盘价。
high : 24小时内的最高价。
low : 24小时内的最低价。
vwap : 24小时内的成交量加权平均价，能更准确地反映平均交易成本。
change : 与24小时前相比的价格变化，可以是绝对值或百分比。

示例：获取BTC/USD交易对的实时行情数据

使用HTTP GET方法请求 /v1/ticker/BTCUSD 接口，可以获取BTC/USD（比特币/美元）交易对的实时行情数据。

请求方法： GET

请求路径： /v1/ticker/BTCUSD

请求参数： 无需额外请求参数。

返回数据： 返回的JSON数据将包含BTC/USD交易对的关键市场信息，例如：

last： 最新成交价。
bid： 最高买入价。
ask： 最低卖出价。
volume： 24小时成交量。
timestamp： 数据更新时间戳。

示例响应（JSON）：


{
  "last": 29500.50,
  "bid": 29490.00,
  "ask": 29510.00,
  "volume": 1500.75,
  "timestamp": 1678886400
}

注意： 实际返回的数据字段可能会因交易所或API提供商而异，请参考具体的API文档。

响应示例 (简化)

此响应示例展示了交易所API返回的Ticker数据，Ticker数据是加密货币交易中非常重要的实时信息，用于反映特定交易对（例如BTC/USD）的当前市场状况。

{ "ask": "65000.00", "bid": "64999.99", "last": "64999.98", "volume": { "BTC": "1000.00", "USD": "65000000.00" } }

字段解释:

ask (卖价): 指当前市场上最高的卖单价格。这是你立即购买该加密货币的最佳价格。在这个例子中，以65000.00美元可以买入一个BTC。
bid (买价): 指当前市场上最高的买单价格。这是你立即卖出该加密货币的最佳价格。在这个例子中，以64999.99美元可以卖出一个BTC。
last (最新成交价): 指最近一次成交的价格。这是市场共识的一个体现。在这个例子中，最近一次成交价格是64999.98美元。
volume (交易量): 指在特定时间段内交易的加密货币数量。通常以两种形式显示：
- BTC: 以BTC计价的交易量，表示交易了1000个BTC。
- USD: 以USD计价的交易量，表示交易了价值65000000美元的BTC。

开发者可以利用Ticker数据构建实时的价格监控系统、算法交易策略，或进行市场分析。例如，通过监控Ask和Bid价格的变动，可以判断市场的供需关系。高频交易者也依赖Ticker数据来快速执行交易策略。交易量也是一个关键指标，可以反映市场的活跃程度和流动性。

Order Book (订单簿)

/v1/book/:symbol 端点允许开发者访问特定交易对的实时订单簿数据，它是加密货币交易所的核心组成部分。订单簿集中展示了市场中所有未成交的买单（买入报价）和卖单（卖出报价）信息，并按照价格进行排序，从而清晰反映出当前市场的供需状况和流动性深度。通过分析订单簿，交易者可以评估市场的买卖压力、支撑位和阻力位，并制定相应的交易策略。

返回的数据结构通常包含 bids (买单) 和 asks (卖单) 两个数组，分别代表市场上所有挂出的买入和卖出订单。 bids 数组包含了所有买入订单的信息，按照价格从高到低排列（最高买价在最前面）。 asks 数组则包含了所有卖出订单的信息，按照价格从低到高排列（最低卖价在最前面）。

每个订单条目通常包含以下关键信息：价格 ( price ) 和数量 ( amount )。 price 代表该订单的委托价格，即交易者愿意买入或卖出加密货币的价格。 amount 代表该订单的委托数量，即交易者愿意买入或卖出的加密货币数量。通过观察订单簿中的价格和数量分布，交易者可以判断市场的供需关系，并预测价格的潜在波动方向。例如，如果 bids 数组中存在大量较高价格的买单，可能意味着市场存在较强的买入意愿，价格可能上涨；反之，如果 asks 数组中存在大量较低价格的卖单，可能意味着市场存在较强的卖出意愿，价格可能下跌。订单簿的深度也是一个重要的指标，深度越深，意味着市场的流动性越好，订单更容易成交，价格波动也相对稳定。

示例：获取BTCUSD的订单簿数据

使用GET方法请求 /v1/book/BTCUSD 接口，可以获取当前BTCUSD交易对的订单簿（Order Book）数据。

订单簿数据是市场深度的重要指标，它包含了买单（Bid）和卖单（Ask）的价格和数量信息，反映了市场参与者对该交易对的供需情况。

该接口返回的数据通常会包含以下关键字段：

timestamp ：订单簿数据生成的时间戳，用于追踪数据的时效性。
bids ：买单数组，按照价格从高到低排序。每个买单包含价格（price）和数量（amount）两个字段。
asks ：卖单数组，按照价格从低到高排序。每个卖单包含价格（price）和数量（amount）两个字段。

通过分析订单簿数据，用户可以了解市场的买卖压力、支撑位和阻力位，从而制定更明智的交易策略。例如，观察买单数量集中的价格区域可以识别潜在的支撑位，而卖单数量集中的价格区域可能预示着阻力位。

请注意，订单簿数据是动态变化的，需要定期刷新才能获取最新的市场信息。不同的交易所或数据提供商可能会采用不同的数据格式，需要根据具体情况进行解析和处理。

响应示例 (简化)

以下JSON示例展示了一个简化的订单簿快照，包含了买单（bids）和卖单（asks）的信息。每个订单都包含价格（price）和数量（amount）两个关键属性，用于描述交易意愿。

{ "bids": [ { "price": "64999.99", "amount": "1.00" }, { "price": "64999.98", "amount": "0.50" } ], "asks": [ { "price": "65000.00", "amount": "1.20" }, { "price": "65000.01", "amount": "0.80" } ] }

Bids (买单): 代表市场中买家希望以特定价格购买加密货币的订单。这些订单按照价格从高到低排序，意味着价格最高的买单将首先被执行。数量（amount）表示该买单的加密货币数量。

Asks (卖单): 代表市场中卖家希望以特定价格出售加密货币的订单。这些订单按照价格从低到高排序，意味着价格最低的卖单将首先被执行。数量（amount）表示该卖单的加密货币数量。

通过分析订单簿数据，开发者和交易者可以深入了解市场深度。订单簿数据可以揭示不同价格水平的买卖压力，从而识别潜在的支撑位和阻力位。例如，大量买单聚集的价格点可能构成支撑位，而大量卖单聚集的价格点可能构成阻力位。

基于订单簿数据，可以制定更有效的交易策略，例如：

限价单策略： 根据订单簿的当前价格，设置限价买单或卖单，以期望在更有利的价格成交。
套利策略： 监控不同交易所的订单簿，寻找价格差异，执行跨交易所套利。
高频交易策略： 利用订单簿数据的实时性，快速响应市场变化，进行高频交易。

成交记录

/v1/trades/:symbol 接口用于获取指定交易对的历史成交数据。通过此接口，开发者可以追踪市场动态，分析交易趋势，并进行量化策略的回测。 :symbol 参数代表交易对，例如 BTCUSDT ，表示比特币兑换泰达币的交易对。

开发者可以使用可选参数 limit_trades 来限制返回的成交记录数量。默认情况下，接口会返回一定数量的最新成交记录，但通过设置 limit_trades ，可以灵活控制返回数据的量级，从而优化数据传输效率和服务器资源消耗。例如，设置 limit_trades=100 将只返回最新的100条成交记录。

每个成交记录包含以下关键信息：成交价格 ( price )、成交数量 ( amount ) 和成交时间戳 ( timestamp )。 price 代表该笔交易的成交价格，以计价货币（例如USDT）表示。 amount 代表该笔交易的成交数量，以基础货币（例如BTC）表示。 timestamp 是一个 Unix 时间戳，表示该笔交易发生的具体时间，精确到毫秒级别。通过这些信息，开发者可以构建高精度的市场分析模型，并进行实时的风险管理。

示例：获取BTCUSD的最近100笔成交记录

使用GET方法调用 /v1/trades/BTCUSD 接口，并添加 limit_trades=100 参数，可以获取BTCUSD交易对最近的100笔成交记录。该接口返回的数据包含每笔交易的成交价格、成交数量、成交时间和交易方向等信息。详细参数说明：

URL: /v1/trades/BTCUSD
Method: GET
参数: limit_trades - 用于指定返回的成交记录数量，最大值为1000。如果省略此参数，则返回默认数量。
返回值: JSON格式的成交记录列表，每条记录包含以下字段：
- trade_id : 交易ID，唯一标识每笔成交。
- price : 成交价格，以美元计价。
- quantity : 成交数量，以BTC计价。
- timestamp : 成交时间戳，Unix时间戳格式，精确到毫秒。
- side : 交易方向， buy 表示买入， sell 表示卖出。

示例:

        
        GET /v1/trades/BTCUSD?limit_trades=100

响应示例:

        
        [
            {
                "trade_id": "1234567890",
                "price": 65000.00,
                "quantity": 0.01,
                "timestamp": 1678886400000,
                "side": "buy"
            },
            {
                "trade_id": "9876543210",
                "price": 64999.99,
                "quantity": 0.02,
                "timestamp": 1678886399000,
                "side": "sell"
            },
            // ... more trades
        ]

注意：API调用频率受限，请参考API文档中的限流策略。确保正确处理API返回的错误代码，例如429表示请求过于频繁。

响应示例 (简化)

[ { "timestamp": 1678886400, "price": "64999.97", "amount": "0.10", "type": "buy" }, { "timestamp": 1678886399, "price": "64999.98", "amount": "0.20", "type": "sell" } ]

上述 JSON 格式示例展示了历史成交记录的简化数据结构。 timestamp 字段代表成交发生的时间戳，通常以 Unix 时间表示，精确到秒甚至毫秒。 price 字段指示成交时的价格，单位通常是标价货币，例如美元。 amount 字段表示成交的数量，单位通常是基础货币，例如比特币。 type 字段区分买单（"buy"）和卖单（"sell"）。

更详细的成交记录可能包含额外的字段，例如：成交ID（用于唯一标识每笔成交）、委托单ID（关联到相应的买入或卖出委托单）、手续费信息（包括手续费金额和币种）以及做市商标记（指示成交是否由做市商发起）。实际返回的数据结构取决于交易所或数据提供商的具体实现。

历史成交记录对于加密货币交易者和研究者至关重要。它们可以用于回测各种交易策略，评估其在历史市场条件下的表现，帮助优化参数和风险管理。技术分析师利用成交数据分析市场趋势，识别支撑位和阻力位，并预测价格走势。成交数据也是计算各种交易指标的基础，例如成交量加权平均价格（VWAP）和深度加权平均价格（DWAP），这些指标可以更准确地反映市场流动性和价格压力。

K线数据 (Candles)

/v2/candles/:symbol/:timeframe 接口提供特定加密货币交易对在指定时间周期内的K线数据，也常被称为蜡烛图数据。K线图是技术分析中常用的工具，用于展示一段时间内的开盘价、收盘价、最高价和最低价，从而帮助交易者识别趋势和潜在的交易机会。

:symbol 参数代表加密货币交易对，例如 BTCUSDT (比特币/泰达币)。确保使用交易所支持的有效交易对代码。

:timeframe 参数至关重要，它定义了每根K线所代表的时间周期。常见的时间周期包括：

1m : 1 分钟K线，每根K线代表 1 分钟内的价格波动。适用于超短线交易。
5m : 5 分钟K线，每根K线代表 5 分钟内的价格波动。适用于短线交易。
15m : 15 分钟K线，每根K线代表 15 分钟内的价格波动。适用于日内交易。
30m : 30 分钟K线，每根K线代表 30 分钟内的价格波动。适用于日内交易。
1h : 1 小时K线，每根K线代表 1 小时内的价格波动。适用于中短线交易。
4h : 4 小时K线，每根K线代表 4 小时内的价格波动。适用于中线交易。
1d : 1 天K线，每根K线代表 1 天内的价格波动。适用于长线交易。
1w : 1 周K线，每根K线代表 1 周内的价格波动。适用于长线交易。
1M : 1 月K线，每根K线代表 1 个月内的价格波动。适用于长线投资。

选择合适的 timeframe 取决于您的交易策略和时间范围。更短的时间周期提供更细粒度的价格信息，但可能包含更多的噪音。更长的时间周期提供更清晰的趋势，但可能错过短期交易机会。

除了基本的开盘价、收盘价、最高价和最低价，许多API还提供以下与K线相关的数据：

Volume (交易量) : 在该时间周期内交易的加密货币数量。交易量是衡量市场活跃度的重要指标。
Quote Volume (计价货币交易量) : 在该时间周期内交易的计价货币数量。例如，如果交易对是 BTCUSDT，计价货币就是 USDT。
Number of Trades (交易笔数) : 在该时间周期内发生的交易次数。
Taker Buy Base Asset Volume (主动买入的基础资产交易量) : 主动买入造成的交易量。
Taker Buy Quote Asset Volume (主动买入的计价资产交易量) : 主动买入造成的计价资产交易量。

通过分析 K 线图以及相关的交易量等指标，交易者可以更好地了解市场情绪，从而做出更明智的投资决策。

示例：获取BTC/USD交易对的1小时K线数据

请求方法： GET

请求路径： /v2/candles/BTCUSD/1h

说明： 此API端点用于检索指定交易对（在本例中为BTCUSD，即比特币兑美元）的1小时K线（OHLCV）数据。 K线数据是金融市场分析中的常用工具，它提供了特定时间段内资产的价格变动信息。

参数解释：

BTCUSD : 这是交易对的标识符，表示比特币与美元的交易。不同的交易所可能使用不同的符号表示相同的交易对。
1h : 这表示K线的时间周期为1小时。除了1小时（ 1h ）之外，还可能有其他时间周期，如1分钟（ 1m ）、5分钟（ 5m ）、15分钟（ 15m ）、30分钟（ 30m ）、4小时（ 4h ）、1天（ 1d ）、1周（ 1w ）、1月（ 1M ）等。具体支持的时间周期取决于交易所的API文档。

响应数据（示例）：


[
  {
    "timestamp": 1678886400,
    "open": 27000.00,
    "high": 27200.00,
    "low": 26900.00,
    "close": 27100.00,
    "volume": 50.50
  },
  {
    "timestamp": 1678890000,
    "open": 27100.00,
    "high": 27300.00,
    "low": 27050.00,
    "close": 27250.00,
    "volume": 40.75
  }
]

响应数据解释：

timestamp : K线开始的时间戳（Unix时间）。
open : 该时间周期内的开盘价。
high : 该时间周期内的最高价。
low : 该时间周期内的最低价。
close : 该时间周期内的收盘价。
volume : 该时间周期内的交易量。

注意事项：

API请求通常需要身份验证，具体取决于交易所的要求。
需要查阅交易所的API文档，以了解请求频率限制和其他相关规定。
返回的数据格式（如JSON）和字段名称可能因交易所而异。
时间戳通常以Unix时间（秒或毫秒）表示。

响应示例 (简化)

[ [ 1678886400000, // 时间戳 (毫秒): 代表K线开始的时间，以Unix时间戳格式表示，精确到毫秒。 "64000.00", // 开盘价: 该时间段内第一笔交易的价格。 "65000.00", // 最高价: 该时间段内达到的最高价格。 "63000.00", // 最低价: 该时间段内达到的最低价格。 "64500.00", // 收盘价: 该时间段内最后一笔交易的价格。 "10.00" // 成交量: 该时间段内的交易总量，通常以标的资产的数量单位表示。 ] ]

K线图数据是加密货币技术分析的基石，通过可视化价格走势，帮助交易者识别潜在的价格模式、趋势反转信号以及支撑阻力位。这些数据点 (开盘价、最高价、最低价和收盘价) 共同构成了一根K线，不同的K线组合形成各种图表形态，如头肩顶、双底、三角形等，为预测未来价格走势提供参考。成交量则反映了市场参与程度，成交量放大通常意味着趋势的加强或反转的可能性增加。

交易

Gemini API 提供了一套强大的接口，允许开发者通过编程方式无缝地下单、取消订单以及全面管理其数字资产交易。它极大地简化了与 Gemini 交易所的交互，避免了手动操作的繁琐。

通过精心设计的 API 端点，开发者可以精确地指定交易参数，例如交易对（如 BTC/USD）、交易类型（买入或卖出）、价格、数量以及其他高级订单选项（如限价单、市价单、止损单等）。这种细粒度的控制为自动化交易策略的实现提供了坚实的基础。

API 还提供了强大的订单管理功能。开发者能够实时查询订单状态，监控已成交订单的详细信息，并根据市场情况迅速取消未成交的订单。这种高效的订单管理能力对于快速响应市场变化、优化交易策略至关重要。

利用 Gemini API 进行交易，需要对 API 的认证机制、速率限制以及错误处理有深入的理解。开发者应仔细阅读官方文档，确保其应用程序能够安全、可靠地与 Gemini 交易所进行交互。同时，考虑到安全性，需要妥善保管 API 密钥，并采取必要的安全措施，以防止未经授权的访问。

该 API 的强大功能使其成为量化交易者、算法交易者以及希望构建自己的交易平台的开发者的理想选择。通过自动化交易流程，开发者可以提高交易效率，降低人为错误的风险，并更好地抓住市场机遇。

新建订单

通过 /v1/order/new 端点，用户可以提交创建新订单的请求。此操作为需要身份验证的 POST 请求，必须在请求头中包含有效的 API 密钥和签名，以确保交易的安全性和真实性。创建订单时，以下参数是必不可少的：

symbol : 指定进行交易的货币对，例如 BTCUSD 代表比特币兑美元的交易对。需要注意的是，提供的交易对必须是交易所支持的有效交易对。
amount : 指示交易的数量，即买入或卖出的标的资产数量。数量的单位取决于交易对的基础货币，且必须符合交易所规定的最小交易数量限制。
price : 设定交易的价格。此参数仅在创建限价单时有效。用户设定的价格决定了订单的执行价格，只有当市场价格达到或超过该价格时，订单才会被执行。对于市价单，此参数将被忽略。
side : 指定交易方向， buy 代表买入， sell 代表卖出。买入表示用户希望以指定价格或市场价格购买指定数量的标的资产，卖出则表示用户希望以指定价格或市场价格出售持有的标的资产。
type : 定义订单类型。 exchange limit 表示限价单， exchange market 表示市价单。限价单允许用户以指定的价格或更好的价格成交，而市价单则会以当前市场最优价格立即成交。用户应根据自身交易策略和市场情况选择合适的订单类型。

示例：创建一个BTCUSD的限价买单

API端点: POST /v1/order/new

该端点用于在交易平台上创建一个新的限价买单，以指定的价格购买一定数量的BTCUSD交易对。

请求方法: POST

请求参数 (JSON格式):

symbol (String, 必选): 交易对，例如 "BTCUSD"。
side (String, 必选): 订单方向，"BUY" 表示买入，"SELL" 表示卖出。在本例中为 "BUY"。
type (String, 必选): 订单类型，"LIMIT" 表示限价单，"MARKET" 表示市价单。在本例中为 "LIMIT"。
quantity (Number, 必选): 购买的BTC数量。
price (Number, 必选): 期望的买入价格 (限价)。
timeInForce (String, 可选): 订单有效期规则，常见的有 "GTC" (Good-Til-Cancelled, 持续有效直到取消), "IOC" (Immediate-Or-Cancel, 立即成交或取消), "FOK" (Fill-Or-Kill, 全部成交或取消)。默认为 "GTC"。
clientOrderId (String, 可选): 客户端自定义的订单ID，方便跟踪订单状态。

请求示例 (JSON):


{
  "symbol": "BTCUSD",
  "side": "BUY",
  "type": "LIMIT",
  "quantity": 0.01,
  "price": 30000.00,
  "timeInForce": "GTC",
  "clientOrderId": "my_unique_order_id"
}

响应示例 (成功):


{
  "orderId": 123456789,
  "clientOrderId": "my_unique_order_id",
  "status": "NEW",
  "symbol": "BTCUSD",
  "side": "BUY",
  "type": "LIMIT",
  "quantity": 0.01,
  "price": 30000.00,
  "timestamp": 1678886400000
}

注意事项:

请确保API Key具有下单权限。
price 和 quantity 的精度应符合交易所的规定。
订单提交后，可以通过订单ID ( orderId ) 或客户端订单ID ( clientOrderId ) 查询订单状态。
不同的交易所可能有不同的参数要求，请仔细阅读交易所的API文档。

请求体 (JSON)

用于提交交易请求的JSON格式数据，包含以下字段：

{
   "symbol": "BTCUSD",
   "amount": "0.01",
   "price": "64500.00",
   "side": "buy",
   "type": "exchange limit",
   "client_order_id": "my_unique_order_id"
}

字段说明：

symbol : 交易的交易对，例如 "BTCUSD" 表示比特币/美元。该字段必须符合交易所支持的交易对格式。
amount : 交易的数量，例如 "0.01" 表示0.01个比特币。该数值必须符合交易所规定的最小交易单位。
price : 交易的价格，例如 "64500.00" 表示价格为64500美元。对于市价单，该字段可以省略或设置为null，取决于交易所的API规范。
side : 交易方向，可以是 "buy" (买入) 或 "sell" (卖出)。
type : 订单类型，例如 "exchange limit" 表示限价单。常见的订单类型还包括 "market" (市价单), "stop limit" (止损限价单), "stop market" (止损市价单) 等。具体的订单类型支持取决于交易所。
client_order_id : 客户端自定义的订单ID，用于唯一标识该订单。长度和字符限制取决于交易所的要求。强烈建议使用UUID或其他方式生成唯一ID，方便后续的订单追踪和管理。

注意事项：

所有数值类型的字段（如 amount 和 price ）通常以字符串形式提交，以避免精度丢失。
确保提供的 symbol 是交易所支持的有效交易对。
订单类型 ( type ) 和其他参数必须符合交易所的API文档规范。错误的参数可能导致订单提交失败。
client_order_id 的唯一性对于订单管理至关重要。

响应示例 (成功)

一个成功的订单提交会返回包含以下字段的JSON对象，提供关于订单状态的详细信息:

{
  "order_id": "1234567890",
  "symbol": "BTCUSD",
  "amount": "0.01",
  "price": "64500.00",
  "side": "buy",
  "type": "exchange limit",
  "client_order_id": "my_unique_order_id",
  "is_live": true,
  "is_cancelled": false,
  "is_hidden": false,
  "avg_execution_price": "0.00",
  "executed_amount": "0.00",
  "remaining_amount": "0.01"
}

字段解释:

order_id : 交易所生成的唯一订单标识符。
symbol : 交易对，例如 "BTCUSD" 代表比特币/美元。
amount : 订单数量，单位为交易对的基础货币，例如 "0.01" 代表0.01个比特币。
price : 订单价格，单位为交易对的计价货币，例如 "64500.00" 代表64500美元。
side : 订单方向，"buy" 代表买入， "sell" 代表卖出。
type : 订单类型，例如 "exchange limit" 代表限价单。其他类型可能包括 "market" (市价单) 等。
client_order_id : 是一个由客户端（你）生成的唯一ID，用于跟踪订单。客户端应确保每个订单的 client_order_id 都是唯一的，便于在本地系统进行订单管理和匹配。
is_live : 布尔值，指示订单当前是否活跃。如果为 true ，则订单正在交易所挂单等待成交。
is_cancelled : 布尔值，指示订单是否已被取消。如果为 true ，则订单已被取消。
is_hidden : 布尔值，表示订单是否为隐藏订单（也称为冰山订单），不会完全显示在订单簿上。
avg_execution_price : 订单的平均成交价格。如果订单部分成交，此字段将反映已成交部分的平均价格。如果订单尚未成交，则为 "0.00"。
executed_amount : 订单已成交的数量。如果订单部分成交，此字段将反映已成交的数量。如果订单尚未成交，则为 "0.00"。
remaining_amount : 订单剩余未成交的数量。等于 amount 减去 executed_amount 。

client_order_id 是一个由客户端生成的唯一ID，务必保证其唯一性，以便于你跟踪订单状态并在本地系统进行订单匹配。它对于调试和订单管理至关重要。

取消订单

使用 /v1/order/cancel API端点可以取消之前提交的订单。为了成功取消订单，您必须提供要取消的目标订单的唯一标识符，即 order_id 。 order_id 通常在您下单时由系统返回，您需要妥善保存以便后续操作。请务必使用正确的 order_id ，否则可能导致取消操作失败。

取消订单是一个需要身份验证的操作。也就是说，您必须通过有效的身份验证机制（例如，API密钥、JWT令牌或 OAuth 2.0）来证明您拥有取消该订单的权限。服务器会验证您的身份凭证，以确保只有订单的所有者或有权代表订单所有者操作的用户才能取消订单。

此操作通过 HTTP POST 请求来执行。 POST 方法允许您向服务器发送数据，在这种情况下，数据包括 order_id 和您的身份验证凭证。您需要在 HTTP 请求的 body 中以 JSON 格式或其他服务器接受的格式包含这些数据。

例如，一个典型的请求体可能如下所示：


{
  "order_id": "您的订单ID",
  "timestamp": "当前时间戳",
  "signature": "身份验证签名"
}

服务器收到请求后，将验证 order_id 的有效性，检查订单是否处于可以取消的状态（例如，未完成、未发货），并验证您的身份。如果一切验证通过，服务器将取消订单并返回一个成功的响应。如果出现任何错误，服务器将返回一个包含错误代码和描述的错误响应。

请注意，并非所有订单都可以取消。例如，如果订单已经开始处理或已经发货，则可能无法取消。在调用取消订单 API 之前，请务必查看您的订单状态。

示例：取消订单

POST /v1/order/cancel

该接口允许用户取消尚未完全成交的订单。取消订单请求通过 POST 方法发送到指定的API端点 /v1/order/cancel 。成功取消订单后，系统会将订单从待执行队列中移除，并将订单中锁定的资金或数字资产返还到用户的账户。

为了成功取消订单，请求体需要包含必要的参数，通常包括订单ID ( orderId ) 或客户端订单ID ( clientOrderId )。请务必根据API的具体要求提供正确的参数，并使用有效的身份验证信息进行身份验证。如果取消订单成功，服务器会返回一个包含成功状态码的响应。如果取消订单失败（例如，订单已经成交或不存在），服务器会返回一个包含错误代码和错误消息的响应，详细说明取消失败的原因。

请求体 (JSON)

用于取消订单的请求体采用 JSON 格式，必须包含以下字段：


{
  "order_id": "1234567890"
}

字段说明:

order_id :
- 类型: 字符串 (String)
- 必填: 是 (Required)
- 描述: 需要取消的订单的唯一标识符。此 ID 由系统生成，并在创建订单时返回。请务必提供有效的 order_id ，否则取消请求将失败。 order_id 区分大小写。
- 示例: "1234567890", "ABCDEFG12345"

注意事项:

请求体的 Content-Type 必须设置为 application/ 。
order_id 的长度和格式可能受到平台的特定限制。请查阅相关API文档以获取更详细的规范。
服务器在接收到取消订单请求后，将根据当前订单状态进行处理。如果订单已完成或已取消，则取消请求可能会失败。
请确保在发送取消请求之前，仔细核对 order_id 的正确性，避免误取消订单。

响应示例 (成功)

当订单取消成功时，API将返回以下JSON格式的响应。该响应提供订单的唯一标识符以及订单的取消状态。


{
  "order_id": "1234567890",
  "is_cancelled": true
}

字段解释:

order_id : 字符串类型，表示已取消订单的唯一标识符。此ID可用于追踪订单历史或进行相关查询。例如： "1234567890" 。
is_cancelled : 布尔类型，指示订单是否已成功取消。 true 表示订单已成功取消， false 表示订单未取消或取消操作失败。在本例中，值为 true 。

注意事项:

应用程序应解析此响应，并相应地更新订单状态。
如果 is_cancelled 为 false ，则应向用户显示错误消息，并建议稍后重试或联系客服。
确保 order_id 与请求取消订单时提供的ID匹配。

订单状态

您可以使用 /v1/order/status API 端点来查询特定订单的实时状态。要发起查询，您必须提供待查询订单的唯一标识符，即 order_id 。这是一个需要身份验证的 POST 请求，这意味着您需要在请求头中包含有效的 API 密钥或访问令牌，以证明您的身份并获得访问权限。此身份验证机制旨在保护用户数据和防止未经授权的访问。 API 将返回订单的详细信息，例如其当前状态（例如，已创建、待处理、已完成、已取消、部分成交）、创建时间、交易对、订单类型（例如，市价单、限价单）、数量和价格（如果适用）。请注意，订单状态可能会随着时间的推移而变化，具体取决于市场条件和交易执行情况。

示例：查询订单状态

API端点： POST /v1/order/status

该API端点用于查询特定订单的当前状态。客户端需通过HTTP POST请求向服务器发送订单识别信息，服务器将返回订单的详细状态数据。该接口设计用于提供实时的订单追踪和管理功能，确保用户能够及时了解其交易进展。

请求方法： HTTP POST

使用POST方法是为了安全地传递订单ID等敏感信息，避免在URL中暴露。请求体应包含JSON格式的数据，其中包含必要的订单识别参数。选择POST请求还可以支持更大的数据量，以便未来扩展，例如添加附加的查询条件或筛选参数。

请求体示例（JSON）：


{
  "order_id": "your_order_id_here"
}

order_id 字段是必需的，用于唯一标识需要查询的订单。确保提供正确的订单ID，否则服务器可能无法找到对应的订单或返回错误信息。实际应用中，可以根据业务需求添加其他可选参数，例如用户ID、时间范围等，以便更精确地查询订单状态。

响应示例（JSON）：


{
  "status": "completed",
  "order_details": {
    "order_id": "your_order_id_here",
    "timestamp": "2023-10-27T10:00:00Z",
    "items": [
      {
        "product_id": "product_123",
        "quantity": 1
      }
    ],
    "total_amount": "10.00 USDT"
  }
}

响应体将包含订单的当前 status ，例如 "pending"（待处理）、"processing"（处理中）、"completed"（已完成）、"canceled"（已取消）等。 order_details 字段提供订单的详细信息，例如订单创建时间戳、购买的商品列表以及总金额。时间戳使用ISO 8601格式，确保跨时区的兼容性。 items 数组包含购买的每个商品的ID和数量。 total_amount 显示订单的总金额，并指定货币单位（例如 USDT）。根据订单状态和用户权限，响应体还可以包含更多信息，例如交易哈希、支付状态、物流信息等。

请求体 (JSON)

该请求体采用JSON (JavaScript Object Notation) 格式，用于向服务器发送指令或传递数据。以下是一个具体的订单查询请求的JSON示例：

{
   "order_id": "1234567890"
}

字段说明：

order_id ： (字符串类型) 此字段是必需的，代表需要查询的具体订单的唯一标识符。它是一个字符串，例如 "1234567890"。该ID应与之前创建订单时服务器返回的ID完全一致。

注意事项：

JSON对象的键必须用双引号括起来。
确保 order_id 的值是有效的订单ID。
服务器可能还会要求提供其他参数，具体取决于API的设计。请务必查阅相关的API文档以获取完整和最新的参数列表。
如果请求体格式不正确，服务器可能会返回错误信息。因此，请仔细检查JSON的语法是否正确。可以使用JSON校验工具来验证JSON的有效性。
为了提高安全性，通常建议使用HTTPS协议来发送包含敏感信息的请求，例如订单ID。

响应示例

以下 JSON 对象是一个订单响应示例，包含了关于订单状态和执行情况的详细信息。理解这些字段对于监控和管理交易至关重要。


{
  "order_id": "1234567890",
  "symbol": "BTCUSD",
  "amount": "0.01",
  "price": "64500.00",
  "side": "buy",
  "type": "exchange_limit",
  "client_order_id": "my_unique_order_id",
  "is_live": false,
  "is_cancelled": false,
  "is_hidden": false,
  "avg_execution_price": "64500.00",
  "executed_amount": "0.01",
  "remaining_amount": "0.00"
}

order_id 是交易所分配的唯一订单标识符，可用于追踪特定订单。 symbol 指定了交易的货币对，例如 BTCUSD 代表比特币兑美元。 amount 表示订单请求的总数量，单位通常是加密货币的最小可交易单位。 price 是订单的指定价格，对于限价单而言，只有当市场价格达到或优于此价格时，订单才会被执行。 side 指示订单的方向，可以是 "buy" (买入) 或 "sell" (卖出)。 type 定义了订单类型，例如 "exchange_limit" 表示交易所限价单，会在指定价格或更优价格执行。其他可能的类型包括市价单 (market order)、止损单 (stop order) 等。 client_order_id 是由客户端（交易者）提供的自定义订单标识符，方便交易者在自己的系统中追踪订单。 is_live 表明订单的当前状态， true 表示订单活跃并等待执行， false 表示订单已完成、取消或过期。 is_cancelled 表示订单是否已被取消， true 表示订单已取消， false 表示订单未被取消。 is_hidden 指示订单是否为隐藏订单（冰山订单）， true 表示订单部分或全部隐藏在订单簿中。 avg_execution_price 是订单的平均成交价格，如果订单分多次成交，则该价格是所有成交价格的加权平均值。 executed_amount 是订单已成交的数量，反映了订单的执行进度。 remaining_amount 是订单剩余未成交的数量，随着订单执行，该值会逐渐减小。

账户管理

Gemini API 提供了一系列端点，方便用户进行全面的账户管理，其中包括实时查询账户余额以及详细追溯历史交易记录。这些功能允许用户精确掌握其数字资产的当前状态和历史活动。

用户可以通过调用 API 端点实时获取各种加密货币和法币的可用余额，从而清晰了解账户的资产配置情况。API 返回的数据通常包括可用余额、已用余额（例如，挂单所占用的资金）以及总余额，方便用户进行风险评估和资产管理。

除了余额查询外，API 还提供了丰富的历史交易记录查询功能。用户可以根据时间范围、交易类型（例如，买入、卖出、存款、提款）以及交易对等条件筛选交易记录。返回的交易记录通常包含交易时间、交易价格、交易数量、手续费等详细信息，为用户进行税务申报、审计和策略回测提供有力支持。

通过集成 Gemini API 的账户管理功能，开发者可以构建功能强大的交易应用程序，帮助用户更好地管理其数字资产并做出明智的投资决策。需要注意的是，在使用 API 进行账户管理时，务必妥善保管 API 密钥，防止泄露，并严格遵循 Gemini 的 API 使用规范，避免触发速率限制等问题。

账户余额

通过调用 /v1/balances API 端点，您可以检索与您的账户关联的各种加密货币的余额信息。该端点需要进行身份验证，因此请确保在请求头中包含有效的 API 密钥或访问令牌。这是一个 HTTP GET 请求，用于安全地获取账户余额数据。

该接口返回的余额信息通常包括可用余额、冻结余额以及总余额。可用余额是指您可以立即用于交易或转账的金额。冻结余额可能由于未完成的订单、提款请求或其他限制而无法使用。总余额是可用余额和冻结余额的总和。请注意，不同交易所或平台的具体实现可能会有所差异，返回的字段名称和含义可能略有不同。仔细查阅API文档以了解详细的字段描述。

在调用 /v1/balances 端点时，请注意速率限制，以避免因频繁请求而被暂时阻止访问。合理规划您的请求频率，并考虑使用缓存机制来优化性能。为了确保账户安全，请妥善保管您的 API 密钥或访问令牌，避免泄露给未经授权的第三方。

该端点通常支持分页参数，以便在账户拥有大量加密货币时，可以分批次地获取余额信息。您可以使用 limit 和 offset 参数来指定每页返回的记录数量和起始位置。正确使用分页参数可以提高数据检索效率，避免一次性加载大量数据导致性能问题。

示例：获取账户余额

请求方法： GET

请求路径： /v1/balances

描述： 该接口用于检索用户账户中所有可用资产的余额信息。它将返回一个包含各种加密货币和法定货币余额的列表，每个条目提供有关特定资产的可用余额、冻结余额和其他相关详细信息。

请求示例：


GET /v1/balances HTTP/1.1
Authorization: Bearer YOUR_API_KEY
Content-Type: application/

响应示例：


HTTP/1.1 200 OK
Content-Type: application/

[
  {
    "currency": "BTC",
    "available": "1.25",
    "reserved": "0.1",
    "total": "1.35"
  },
  {
    "currency": "ETH",
    "available": "5.0",
    "reserved": "0.5",
    "total": "5.5"
  },
  {
    "currency": "USDT",
    "available": "1000.0",
    "reserved": "0.0",
    "total": "1000.0"
  }
]

响应字段解释：

currency : 资产的币种代码 (例如: BTC, ETH, USDT)。
available : 可用于交易或提现的余额。
reserved : 由于未完成的订单或其他原因而被冻结的余额。
total : 可用余额和冻结余额的总和。

安全考量： 请务必使用 HTTPS 来保护您的 API 密钥，并且不要在客户端代码中暴露您的密钥。将您的 API 密钥视为敏感信息，并安全地存储和管理它们。

响应示例

[ { "currency": "BTC", "amount": "1.00", "available": "0.50", "availableForWithdrawal": "0.50" }, { "currency": "USD", "amount": "65000.00", "available": "64000.00", "availableForWithdrawal": "64000.00" } ]

amount 表示账户中的总余额，包含已冻结或正在交易中的资金。 available 表示当前可用于交易的余额，此余额不包括已挂单或用于其他操作而被锁定的资金。 availableForWithdrawal 表示可用于提现的余额，此数值通常会小于或等于 available 余额，因为它可能受限于提现规则、最小提现额度或其他限制。

例如，在上述 BTC 示例中， amount 为 1.00 BTC，表示账户总余额为 1 个比特币。 available 为 0.50 BTC，表示当前可以用于交易的比特币数量为 0.5 个。 availableForWithdrawal 同样为 0.50 BTC，表示可以提取的比特币数量为 0.5 个。剩余的 0.5 BTC 可能处于挂单状态，或者因为其他原因被暂时冻结。

在 USD 示例中， amount 为 65000.00 美元，表示账户总余额为 65000 美元。 available 为 64000.00 美元，表示当前可以用于交易的美元数量为 64000 美元。 availableForWithdrawal 为 64000.00 美元，表明有 64000 美元可以提取。剩余的1000美元可能由于未完成的交易或其他原因被暂时锁定。理解这三个余额之间的差异对于管理您的加密货币资产至关重要。

历史成交记录

/v1/mytrades 端点提供用户完整的历史成交数据查询功能。为了精准地获取特定交易对的历史记录，必须指定 symbol 参数，即交易对代码，例如 BTCUSDT 。除了必须的交易对参数外，还提供了一系列可选参数，以满足更精细的查询需求。可选参数 limit_trades 允许用户限制返回的成交记录数量，适用于只需要最近几条成交记录的场景。默认情况下，如果没有指定此参数，服务器会返回预设数量的成交记录。通过调整 limit_trades 的值，可以控制返回结果的长度，避免数据冗余。 timestamp 参数则用于指定查询的起始时间戳。通过提供一个 Unix 时间戳，可以筛选出在该时间之后发生的成交记录。这对于分析特定时间段内的交易行为非常有用。如果不指定 timestamp ，则默认返回所有历史成交记录。为了保障用户数据的安全，访问 /v1/mytrades 端点需要进行身份验证。只有通过验证的用户才能获取其账户的成交历史记录，确保数据隐私和安全。

安全

使用Gemini API进行交易需要严格的身份验证机制，这是保护您的账户安全和防止未经授权访问的关键措施。身份验证过程通常包括使用API密钥、构造payload并对其进行签名。

Gemini API的安全模型依赖于一组特定的HTTP头部，这些头部必须包含在每个经过身份验证的请求中，以确保请求的真实性和完整性。这些头部包括：

X-GEMINI-APIKEY : 您的唯一API密钥，用于标识您的账户。请务必妥善保管您的API密钥，避免泄露，因为拥有该密钥的任何人都可以代表您进行交易。
X-GEMINI-PAYLOAD : 请求体的Base64编码字符串。payload 包含了您希望执行的交易或其他操作的具体数据，经过Base64编码后，可以安全地通过HTTP协议传输。
X-GEMINI-SIGNATURE : 使用您的私钥对 payload 进行HMAC-SHA384加密生成的签名。这个签名是对 payload 的数字签名，用于验证请求的来源和完整性。服务器会使用您的公钥验证签名，以确保请求确实来自您，并且在传输过程中没有被篡改。

在实施这些安全措施时，务必仔细阅读Gemini API的文档，并严格按照其说明进行操作。不正确的实施可能导致安全漏洞，从而使您的账户面临风险。请特别注意以下几点：