Bitget REST API文档解读与开发者使用指南

Bitget REST API 文档解读

一、概述

Bitget是一个全球领先的加密货币交易平台，致力于为用户提供多种加密货币金融衍生品的交易服务。作为一个具备高度竞争力的交易平台，Bitget不仅支持现货交易，还涵盖了期货、杠杆交易、CopyTrading等多种创新性的交易方式。为了满足不同用户群体的需求，Bitget提供了强大的开发者工具，包括REST API接口，帮助开发者实现更加灵活和高效的自动化交易。

Bitget的REST API是一个功能丰富且易于集成的工具，能够为开发者提供包括账户信息查询、市场数据获取、订单操作等多项核心功能。通过这一API，开发者可以在自己的应用程序中实现自动化交易策略，实时获取市场行情数据，并且能够在平台上执行下单、撤单等操作，极大地提高了交易的便捷性和效率。

Bitget的REST API还提供了安全保障机制，采用了高级的加密技术，确保交易过程中的数据安全性和隐私保护。通过REST API，开发者不仅可以访问到各种实时市场数据，还能够执行高效的订单管理，包含查询订单状态、修改订单和取消订单等操作，全面满足程序化交易和数据分析的需求。

本文将深入解读Bitget REST API的主要功能和使用方法，帮助开发者更好地理解API的结构和调用方式，从而充分利用这一强大工具，实现更加智能化和个性化的交易策略。

二、身份认证

在使用Bitget的REST API时，身份认证是确保数据安全和操作权限的关键步骤。为了保障用户的交易安全，Bitget采用了API Key与Secret Key的双重身份验证机制。API Key是每个用户在Bitget平台上创建API时生成的唯一标识符，它用于标识并允许访问指定账户的API接口。通过该API Key，系统能够识别请求来源，并根据API权限设定执行相应的操作。

Secret Key则是与API Key配套的私密信息，只有用户本人知晓。它并不会直接暴露于任何外部接口，而是用来生成签名（Signature）。这个签名是通过将请求的所有参数按照特定的顺序进行加密处理后，生成的哈希值。通过签名，Bitget可以验证请求的真实性，确保请求没有被篡改，并确保只有拥有正确Secret Key的用户才能执行相关操作。这一过程大大提高了API的安全性，防止了中间人攻击和伪造请求。

在进行API请求时，用户需要将API Key与签名一起包含在请求的头部或参数中，以便Bitget服务器能够校验请求的合法性。同时，Bitget平台还允许用户为API Key设置权限控制，用户可以根据具体需求，为每个API Key分配不同的访问权限，例如读取市场数据、执行交易或管理资金等，进一步增强了系统的安全性。

1. 获取API Key

要生成API Key，用户需要先登录Bitget账户，进入个人账户界面后，找到并点击“API管理”选项。这将带用户进入API密钥管理页面。在该页面，用户可以选择创建新的API密钥，按照页面的提示完成操作。创建成功后，用户将获得一对API密钥，其中包括API Key和Secret Key。API Key用于在后续调用API时进行身份验证，Secret Key则是与API Key配对使用的密钥，用于加密和解密请求数据。

需要注意的是，Secret Key在生成时只会显示一次，创建完成后无法再次查看。因此，在生成API Key后，务必妥善保管Secret Key，避免丢失或泄露。如果Secret Key丢失，用户只能通过删除旧的API密钥并重新生成新的API Key和Secret Key来替换。为了确保账户安全，建议用户不要将API Key和Secret Key存储在公开的地方，如在线文档或代码中，应使用安全的方式进行存储。

2. 请求签名

在使用API进行请求时，必须使用API Key和Secret Key进行配合。为了确保请求的安全性和完整性，API请求需要经过签名验证。签名是通过HMAC SHA256算法生成的，这是一种基于密钥的消息认证码（HMAC）算法，具有高安全性。签名的生成过程会涉及API请求的路径、参数、时间戳等多个因素。这些元素共同作用，确保每次请求都是唯一且不可篡改的。

签名生成过程包括将API请求的路径、所有请求参数（包括但不限于查询参数、请求体等）以及一个精确到毫秒的时间戳进行合并。然后，使用Secret Key对这些信息进行HMAC SHA256算法加密，生成一个固定长度的哈希值作为签名。该签名会附加到请求的头部或请求体中，以便在服务端进行验证。通过这种方式，服务器能够确保请求没有被中途修改或伪造。

时间戳的作用不仅仅是防止重放攻击，还能够确保每个签名请求的时效性。由于HMAC SHA256算法的不可逆性，外部人员无法轻易推算出原始的Secret Key或伪造合法的签名。因此，签名机制是加密货币API请求中至关重要的安全环节，能够有效保障数据的隐私性与完整性。

三、常用接口

1. 获取账户信息

• 接口路径 ： GET /api/v2/account
• 请求方式 ：GET
• 功能说明 ：该接口用于获取用户的账户信息，包括但不限于资产总览、可用余额、冻结资产、已借资产、未偿还的贷款、交易手续费等。用户可以通过此接口全面了解账户的当前状态，并实时获取与账户相关的各种财务数据。接口返回的账户信息还包含每个币种的详细资产数据，支持对比查询不同币种的资产分布和动态变化情况。接口返回的数据结构清晰，便于开发者直接解析和处理，以满足账户管理、数据监控和财务报表生成等多种场景需求。

请求示例

http请求示例展示了如何通过HTTP GET方法与Bitget的API进行交互，获取账户信息。在此示例中，HTTP请求的目标是访问Bitget交易平台的API接口，具体为获取账户信息接口，URL路径为/api/v2/account。通过此请求，用户能够获取与账户相关的详细信息，如余额、资产、交易历史等。

请求的必要头信息包括：

• Host : 指定目标服务器的域名或IP地址，确保请求发送至正确的API端点。在此示例中，目标主机为api.bitget.com。
• X-BITGET-APIKEY : 该字段包含通过Bitget平台注册获得的API密钥，作为身份验证的凭证。用户需要通过正确的API密钥确保请求来源的合法性。请替换为实际的 api 密钥。
• X-BITGET-SIGN : 这是签名字段，用于验证请求的完整性和真实性。该签名通常基于API密钥、请求参数及其他相关信息，通过特定的加密算法生成。为了确保数据的安全性和防止恶意篡改，必须根据要求生成签名。
• X-BITGET-TIMESTAMP : 时间戳字段，用于防止重放攻击，确保请求的时效性。该时间戳通常是请求发出时的UTC时间，精确到毫秒，确保请求在指定时间窗口内有效。

用户在发送此请求时，必须按照Bitget的API文档要求生成并传递这些信息，确保每个请求都能被正确处理并返回预期结果。签名的生成方法及API密钥的管理要求，用户可以参考官方文档中关于身份验证和安全机制的章节。

响应示例

{ "code": "00000", "data": { "totalAssets": "1000.00", "availableBalance": "800.00", "frozenBalance": "200.00", "currency": "CNY", "accountType": "个人账户", "lastUpdated": "2025-02-09T15:30:00Z", "transactionHistory": [ { "transactionId": "TX1234567890", "amount": "500.00", "type": "充值", "status": "成功", "timestamp": "2025-02-01T10:00:00Z" }, { "transactionId": "TX0987654321", "amount": "200.00", "type": "提现", "status": "处理中", "timestamp": "2025-02-05T13:45:00Z" } ], "userDetails": { "userId": "U123456789", "email": "[email protected]", "phone": "+8613800138000", "lastLogin": "2025-02-09T14:00:00Z" } } }

2. 获取市场行情

• 接口路径 ： GET /api/v2/market/ticker
• 请求方式 ：GET
• 功能说明 ：该接口用于获取指定交易对的最新市场行情数据，包括但不限于买一价、卖一价、最新成交价、24小时成交量、24小时价格波动等关键信息。返回的数据可以帮助用户实时监控市场动向，评估当前市场的流动性和价格波动情况。市场行情数据对于交易者而言至关重要，能够帮助其制定交易策略、调整持仓以及判断市场趋势。
• 返回数据 ：接口返回的数据通常包括以下几个重要字段：
  • symbol ：交易对的名称，如 "BTC/USDT"。
  • buy ：当前买一价，即市场上最高的买入价格。
  • sell ：当前卖一价，即市场上最低的卖出价格。
  • last ：最新成交价格，即最后一次成交的价格。
  • high_24h ：过去24小时的最高成交价格。
  • low_24h ：过去24小时的最低成交价格。
  • volume_24h ：过去24小时内该交易对的总成交量。
  • change_24h ：过去24小时内价格的涨跌幅度。
• 数据更新频率 ：市场行情数据会实时更新，通常每秒钟或每几秒钟刷新一次，以确保用户获得最新的市场信息。
• 使用场景 ：该接口适用于实时监控市场状态，查看各个交易对的买卖价差，帮助用户及时做出交易决策。也可以用于大宗交易、算法交易等高频交易策略中，以获取准确的市场数据。

请求示例

http GET /api/v2/market/ticker?symbol=BTCUSDT Host: api.bitget.com X-BITGET-APIKEY: your api key X-BITGET-SIGN: signature X-BITGET-TIMESTAMP: timestamp X-BITGET-REQ-SIGN: request signature Content-Type: application/; charset=UTF-8 Accept-Encoding: gzip, deflate, br User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/58.0.3029.110 Safari/537.36

在这个请求示例中，采用了 HTTP GET 请求方法来访问 Bitget 交易平台的市场行情数据。请求 URL 采用了 "/api/v2/market/ticker" 路径，并通过查询参数 "symbol" 指定了所需查询的交易对。在本例中，查询的是比特币（BTC）与美元稳定币（USDT）之间的市场行情。

请求头部包括多个必要的身份验证字段：

• X-BITGET-APIKEY : 用于标识 API 调用者身份的 API 密钥，这通常是你在 Bitget 开发者平台申请的密钥。
• X-BITGET-SIGN : 是用来验证请求是否被篡改的签名，通常是通过 API 密钥、请求体内容和其他参数生成的哈希值。
• X-BITGET-TIMESTAMP : 时间戳，表示请求发送的时间，通常是当前 UTC 时间的毫秒级表示，用于防止重放攻击。
• X-BITGET-REQ-SIGN : 请求签名，用于进一步加强安全性，确保请求内容的完整性。
• Content-Type : 定义了请求体的媒体类型。此处指定为 "application/"，表示请求发送的是 JSON 格式的数据。
• Accept-Encoding : 用于指定客户端能够接收的内容编码类型，"gzip, deflate, br" 表示支持这三种压缩算法。
• User-Agent : 用于标识发起请求的客户端软件和设备信息，可以帮助服务器了解请求的来源。

这种格式的请求通常用于获取某一特定市场对的实时行情数据，例如查询 BTC/USDT 交易对的最新价格、24小时成交量、涨跌幅等信息。请求返回的 JSON 数据将包含这些市场指标，供开发者进一步处理。

响应示例

{ "code": "00000", "data": { "symbol": "BTCUSDT", "buy": "50000.00", "sell": "50010.00", "last": "50005.00", "high": "50500.00", "low": "49500.00", "volume": "1200.00", "ask": "50005.50", "bid": "49995.00", "timestamp": "1641511600000", "change24h": "0.10%", "percentage_change_24h": "0.10", "market_cap": "950000000000", "total_supply": "21000000", "open": "49950.00", "close": "50005.00" } }

3. 下单接口

• 接口路径 ： POST /api/v2/order
• 请求方式 ：POST
• 功能说明 ：该接口用于提交新的交易订单。用户可以通过此接口发起市场订单或限价订单。市场订单会以当前市场价格立即成交，而限价订单则在价格条件满足时执行。下单时，用户需要提供必要的参数，包括交易对、订单类型、价格、数量等。用户可以选择不同的交易策略和执行方式，以满足不同的交易需求。接口支持高级功能，如止损订单、止盈订单以及市价成分订单等，允许用户灵活控制交易风险。所有的订单提交操作都会返回一个唯一的订单ID，用于后续查询订单状态、撤销订单等操作。此接口还包括对订单有效时间的设置，用户可以选择即时有效、当天有效等不同的有效期选项。

请求参数

请求示例

http POST /api/v2/order Host: api.bitget.com Content-Type: application/ X-BITGET-APIKEY: your api key X-BITGET-SIGN: signature X-BITGET-TIMESTAMP: timestamp

在进行API请求时，必须在HTTP请求头中包含以下关键字段：

• Host : 用于指定API的主机地址。在此示例中，主机地址为api.bitget.com。
• Content-Type : 请求体的内容类型。对于此请求，Content-Type应设置为application/，表示请求体采用JSON格式。
• X-BITGET-APIKEY : 您的API密钥。它用于验证请求的来源，确保该请求来自已授权的用户。
• X-BITGET-SIGN : 请求签名。它是由API密钥、请求体内容以及其他相关信息一起生成的加密签名，用于确保数据的完整性和安全性。
• X-BITGET-TIMESTAMP : 请求的时间戳。时间戳有助于防止重放攻击，确保请求在特定时间内有效。

请求体部分为JSON格式，包含以下字段：

• symbol : 交易对标识符。此示例中，交易对为BTC/USDT，表示比特币和美元稳定币的交易。
• side : 交易方向。可以是"buy"（买入）或"sell"（卖出）。在此请求中，side值为"buy"，表示用户希望买入。
• price : 订单价格。此示例中的价格为50000.00，表示用户希望以每个比特币50000.00美元的价格买入。
• size : 订单的数量。此请求中，size为0.01，表示用户希望购买0.01个比特币。
• type : 订单类型。在此示例中，订单类型为"limit"，表示限价单。限价单会在指定价格或更好的价格执行。
• clientOid : 客户端订单ID。此字段用于唯一标识订单，在订单处理过程中可以追踪。此请求中，clientOid值为"order_123456"。

当API收到该请求后，会根据请求参数创建一个新的订单并返回相应的结果。此请求包含基本的交易信息，但在实际应用中，可能还会根据API的要求或交易策略添加其他字段。

响应示例

{ "code": "00000", "data": { "orderId": "order_123456", "symbol": "BTCUSDT", "side": "buy", "price": "50000.00", "size": "0.01", "status": "new", "timestamp": "2025-02-09T12:00:00Z", "filledSize": "0.00", "remainingSize": "0.01", "orderType": "limit", "timeInForce": "GTC", "clientOrderId": "client_order_7890", "avgFillPrice": null, "createdAt": "2025-02-09T12:00:00Z", "updatedAt": "2025-02-09T12:00:00Z" } }

4. 撤单接口

• 接口路径 ： POST /api/v2/order/cancel
• 请求方式 ：POST
• 功能说明 ：该接口用于撤销未成交的订单。通过该接口，用户可以在订单未完全执行或尚未匹配成交的情况下，主动取消订单。撤单操作将导致该订单从订单簿中移除，并不再参与后续的交易匹配。
• 请求参数 ：
  • order_id ：订单的唯一标识符。撤单时必须指定订单ID，用于明确要撤销的目标订单。此参数为必填项。
  • symbol ：订单的交易对标识符，指定该订单所属的交易市场。例如："BTC/USDT" 或 "ETH/BTC"。此参数为必填项。
  • client_order_id ：用户自定义的订单标识符。此参数是可选的，如果用户在创建订单时设置了该字段，则可以通过此字段来撤销订单。
• 返回字段 ：
  • status ：撤单请求的状态，成功时返回 "ok"，失败时返回具体的错误信息。
  • order_id ：撤单成功时返回的订单ID，确认撤销的订单。
  • symbol ：撤单成功时返回的交易对标识符。
  • error ：如果撤单失败，返回具体的错误信息。例如，可能会出现的错误包括订单已经成交、订单ID无效等。
• 注意事项 ：
  • 只有未成交的订单可以被撤销，已经部分成交或完全成交的订单无法进行撤单。
  • 撤单请求会在后台处理，可能会有一定的延迟，尤其是在高峰期。
  • 该接口支持批量撤单操作，可以同时撤销多个订单，只需在请求中提供多个订单ID。
  • 若撤单请求成功，用户的资金将立即返回至可用余额。

请求参数

请求示例

http
POST /api/v2/order/cancel
Host: api.bitget.com
Content-Type: application/
X-BITGET-APIKEY: your api key
X-BITGET-SIGN: signature
X-BITGET-TIMESTAMP: timestamp

在这个示例中，HTTP请求采用了POST方法，旨在调用Bitget的取消订单接口。请求的目标地址为/api/v2/order/cancel，该接口用于取消用户在交易所下达的指定订单。

请求头部包含了几个重要的字段：

• Host: 这是目标API的主机地址，指向Bitget的API服务器，确保请求能正确路由到相关服务。
• Content-Type: 指定请求体的内容类型为application/，表明请求体内容是JSON格式的数据。
• X-BITGET-APIKEY: 这是API请求的认证密钥，每个API用户都有一个唯一的API密钥，通过它可以验证请求的合法性和身份。
• X-BITGET-SIGN: 请求签名，用于验证请求的完整性和防止篡改。签名是使用API密钥、时间戳和请求体等信息通过特定算法生成的。
• X-BITGET-TIMESTAMP: 这是一个时间戳，表示请求的发送时间，防止重放攻击，确保每个请求的时效性。

请求体部分使用JSON格式，其中包括一个关键字段：

• orderId: 这是要取消的订单ID，唯一标识一个订单。用户需要提供已存在的订单ID，该订单将在Bitget平台上被标记为取消。

这种请求格式的设计旨在确保API请求的安全性、可验证性和高效性。在实际操作中，开发者应根据具体的业务需求，替换 api key、signature和timestamp等动态字段值。

响应示例

{ "code": "00000", "data": { "orderId": "order_123456", "status": "cancelled", "statusDescription": "订单已取消", "cancellationTime": "2025-02-09T15:30:00Z", "cancelReason": "用户请求取消", "transactionDetails": { "amount": "100.00", "currency": "USD", "paymentMethod": "信用卡" }, "refundDetails": { "refundAmount": "100.00", "refundMethod": "信用卡", "refundStatus": "处理中" }, "user": { "userId": "user_78910", "userEmail": "[email protected]" } } }

5. 获取订单信息

• 接口路径 ： GET /api/v2/order
• 请求方式 ：GET
• 功能说明 ：该接口用于查询特定订单的详细信息，包括订单的最新状态、成交信息、交易历史及相关订单变动。通过该接口，用户能够获取关于订单的实时更新，帮助用户实时跟踪订单的执行情况，确保交易的透明性和有效性。返回的信息通常包括订单的唯一标识符、当前状态（如挂单、已成交、已取消等）、成交数量、成交价格、下单时间、成交时间等详细数据，适用于用户进行订单监控和分析。

请求示例

http
GET /api/v2/order?orderId=order 123456
Host: api.bitget.com
X-BITGET-APIKEY: your api_key
X-BITGET-SIGN: signature
X-BITGET-TIMESTAMP: timestamp

在上述请求示例中，您将看到一个标准的API请求格式，这个请求是使用GET方法进行调用的。该请求的目的是查询特定订单的信息。URL路径包含了API版本号（v2），以及目标资源（订单信息）的路径。具体来说，路径中包含了 orderId 参数，它指定了查询的订单ID。

请求头 部分包含了若干个关键字段，分别是：

• Host : 这个字段指定了请求的目标主机，所有请求都会发送到 api.bitget.com 这个服务器。
• X-BITGET-APIKEY : 这是一个用于身份验证的API密钥，确保只有授权的用户才能访问该接口。您需要将 your_api_key 替换为实际的API密钥。
• X-BITGET-SIGN : 该字段包含请求签名。为了保证请求的安全性，您需要使用特定的加密算法（如HMAC-SHA256）生成该签名，并确保请求内容的完整性。
• X-BITGET-TIMESTAMP : 该字段记录请求发送的时间戳，单位为秒。它用于防止重放攻击，确保请求是最新的。

为了提高安全性和防止恶意篡改，所有请求都必须使用正确的签名方式，并且时间戳需要与服务器时间接近。签名是通过请求的关键参数（如 orderId 和时间戳）以及API密钥一起生成的。

响应示例

{ "code": "00000", "data": { "orderId": "order_123456", "symbol": "BTCUSDT", "side": "buy", "price": "50000.00", "size": "0.01", "status": "filled", "filled": "0.01", "remaining": "0.00", "createdAt": "2025-02-09T10:15:00Z", "updatedAt": "2025-02-09T10:16:30Z", "executedValue": "500.00", "fee": { "currency": "USDT", "amount": "1.00" }, "orderType": "limit", "timeInForce": "GTC", "triggerPrice": null, "lastFillPrice": "50000.00", "averageFillPrice": "50000.00", "statusMessage": "Order has been successfully filled", "isMarketOrder": false, "isStopOrder": false, "userData": { "accountId": "user_987654", "userName": "cryptoTrader123" } } }

四、错误码

Bitget的REST API在处理请求时，会根据不同情况返回错误码。这些错误码的作用是帮助用户迅速识别和理解请求失败的具体原因，从而采取有效的解决措施。每个错误码都有对应的描述，帮助开发者和用户在调试时迅速定位问题。以下是一些常见的错误码及其详细说明：

五、限制与注意事项

1. 请求频率 ：Bitget平台对API请求的频率进行了严格的限制，以防止恶意行为和滥用资源。频繁的请求，尤其是超出限额的请求，可能会导致系统自动拒绝该请求。开发者需要注意API的访问限制，并尽量优化请求频率，避免出现请求被封锁的情况。一般情况下，API的请求频率限制会根据用户的账户级别、API权限等因素有所不同，开发者应当根据文档中的规范进行合理安排。
2. 数据格式 ：Bitget的API返回的数据格式为JSON（JavaScript Object Notation），这是一种轻量级的、易于人类阅读和编写的格式。开发者需要解析JSON格式的数据，提取出有效的信息。在解析时，要注意不同的API端点返回的JSON数据结构可能有所不同，因此在处理数据时要根据具体的接口文档进行适配。另外，开发者应对JSON数据的字段进行校验，以确保所获得的信息完整且准确。
3. 安全性 ：为了确保账户安全，开发者必须妥善保管API Key和Secret Key，防止泄露给未经授权的第三方。这些密钥是用户与Bitget平台之间进行安全交互的核心凭证。如果这些密钥被泄露，可能导致账户遭受盗用或恶意操作。为提高安全性，建议采用IP白名单等功能，仅允许受信任的IP地址进行API请求。开发者应当定期更换API Key，并启用二次验证等安全措施，以进一步降低潜在风险。