Poloniex API 交易指南：密钥、端点与身份验证详解

讲座 50℃

Poloniex API 交易指南

简介

Poloniex 交易所提供了一套全面的应用程序编程接口（API），为开发者和资深交易者开启了自动化交易和数据分析的大门。这套API允许用户通过编写代码的方式，无缝访问并控制他们在Poloniex平台上的账户，从而实现个性化的交易策略和高效的投资管理。通过API，用户可以实时获取市场数据，包括但不限于交易对的价格、成交量、深度等信息，并以此为基础构建量化模型或自动化交易机器人。更重要的是，Poloniex API支持多种交易指令的执行，例如限价单、市价单、止损单等，使得用户能够根据市场变化灵活调整交易策略。本指南将深入浅出地介绍Poloniex API的核心概念、认证机制、数据结构以及常用接口的使用方法，并提供一些可实际运行的代码示例，帮助你快速上手并构建自己的交易应用。

API 密钥

在使用 Poloniex API 之前，生成 API 密钥是至关重要的第一步。 登录您的 Poloniex 账户，导航至“API 密钥”页面以开始密钥创建流程。 在创建新的 API 密钥时，请务必仔细阅读并全面理解每个权限的具体含义及其潜在影响。 通常情况下，如果您计划执行任何交易操作，则必须启用“交易”权限； 若仅需获取账户信息和实时的市场数据，则启用“读取”权限即可满足需求。 为了最大程度地保障您的账户安全，强烈建议您仅授予 API 密钥执行特定任务所需的最低权限集合，避免授予不必要的权限。 您必须采取一切必要措施来妥善保管您的 API 密钥，切勿将其泄露给任何第三方，因为这可能导致严重的财务风险和数据泄露。

API 端点

Poloniex API 主要分为两种类型，以满足不同用户的需求：公共 API 和私有 API。 公共 API 提供无需身份验证即可访问的市场数据，而私有 API 则允许用户管理自己的账户，但需要身份验证。

  • 公共 API : 提供实时的市场数据，包括交易对的最新价格、24 小时交易量、买卖盘订单簿深度等信息。由于其公开性，公共 API 无需进行身份验证即可访问，方便开发者快速获取市场信息。常用的端点包括 /public ，通过构造特定的 URL，如 https://poloniex.com/public?command=returnTicker ，可以获取所有交易对的 ticker 信息，例如最高价、最低价、交易量和最后成交价等。还可以使用 returnOrderBook 命令查询指定交易对的订单簿，以及使用 returnTradeHistory 命令查询指定交易对的历史成交记录。
  • 私有 API : 允许用户管理其 Poloniex 账户，执行诸如查询账户余额、创建和取消订单、查询订单状态等操作。 私有 API 需要使用 API 密钥进行身份验证，以确保账户安全。常用的端点包括 /tradingApi ，所有请求都需要在 HTTP 请求头中携带 API 密钥（API Key）和签名（Signature），签名通常是对请求参数进行加密后的字符串，用于验证请求的有效性和防止篡改。 除了交易相关的端点，私有 API 还可能包含用于提现和充值的端点，但这些端点通常需要更高级别的权限和安全措施。

身份验证

访问私有 API 接口需要进行身份验证，以确保只有授权用户才能访问敏感数据和执行关键操作。为此，你需要在每个 HTTP 请求的头部添加 Key 和 Sign 两个字段。

  • Key : 你的 API 密钥，用于标识你的身份。请妥善保管此密钥，避免泄露。
  • Sign : 基于请求参数、你的 API 密钥以及特定的加密算法生成的 HMAC-SHA512 签名，用于验证请求的完整性和真实性，防止篡改。

生成 Sign 签名的详细步骤如下：

  1. 构建请求参数字符串。 将所有请求参数按照 key=value 的形式进行组织，并使用 & 符号将它们连接起来。例如： key1=value1&key2=value2&key3=value3 。参数的顺序会影响签名的生成，建议按照字母顺序排列。
  2. 使用 HMAC-SHA512 算法进行哈希。 将你的 API 密钥作为密钥（key），请求参数字符串作为消息（message），使用 HMAC-SHA512 算法进行哈希运算。HMAC (Hash-based Message Authentication Code) 是一种消息认证码算法，结合了密钥和哈希函数，提供更强的安全性。SHA512 是一种安全的哈希算法，能够生成 512 位的哈希值。
  3. 将哈希结果转换为十六进制字符串。 HMAC-SHA512 算法的输出是二进制数据，需要将其转换为十六进制字符串才能方便地在 HTTP 请求头中使用。通常，每个字节的二进制数据会转换为两个十六进制字符。

以下是一个 Python 示例，展示如何生成签名： 

import hashlib
import hmac
import urllib.parse

def generate_signature(api_secret, params):
    """
    使用 API 密钥和请求参数生成 HMAC-SHA512 签名。

    Args:
        api_secret (str): 你的 API 密钥。
        params (dict): 包含请求参数的字典。

    Returns:
        str: 生成的签名字符串（十六进制）。
    """
    encoded_params = urllib.parse.urlencode(params)
    signature = hmac.new(api_secret.encode('utf-8'), encoded_params.encode('utf-8'), hashlib.sha512).hexdigest()
    return signature

常用 API 调用

以下是一些常用的 Poloniex API 调用示例，旨在帮助开发者快速上手并集成 Poloniex 平台的功能：

获取交易对的 Ticker 信息 (公共 API)

接口地址： GET /public?command=returnTicker

该接口允许用户无需授权即可获取所有交易对的实时市场数据，是了解市场整体动态的重要途径。 通过调用此接口，您可以获得每个交易对的最新价格、交易量、最高价、最低价、买一价、卖一价以及时间戳等关键信息。

返回数据格式：

接口返回一个 JSON 对象，其结构如下： 

{
  "交易对名称": {
    "last": "最新成交价",
    "lowestAsk": "最低卖出价",
    "highestBid": "最高买入价",
    "percentChange": "24小时价格变化百分比",
    "baseVolume": "基础货币交易量 (例如：BTC_USD 交易对中 BTC 的交易量)",
    "quoteVolume": "报价货币交易量 (例如：BTC_USD 交易对中 USD 的交易量)",
    "isFrozen": "是否冻结 (0: 未冻结, 1: 冻结)",
    "high24hr": "24小时最高价",
    "low24hr": "24小时最低价",
    "id": "交易对ID",
    "timestamp": "时间戳"
  },
  "其他交易对名称": {
     //... 更多交易对的信息
  }
}

示例：

假设交易对名称为 BTC_USD，返回的 JSON 对象可能包含如下信息： 

{
  "BTC_USD": {
    "last": "65000.00",
    "lowestAsk": "65001.00",
    "highestBid": "64999.00",
    "percentChange": "0.02",
    "baseVolume": "1000.00",
    "quoteVolume": "65000000.00",
    "isFrozen": "0",
    "high24hr": "65500.00",
    "low24hr": "64000.00",
     "id": "1",
     "timestamp": "1678886400"
  }
}

注意事项：

  • 请注意API的调用频率限制，避免频繁请求导致IP被封禁。
  • 返回的数据是实时更新的，但由于网络延迟等因素，可能存在一定的延迟。
  • 在进行交易决策时，请务必结合其他信息来源进行综合分析。
  • isFrozen 字段表示该交易对是否被冻结，如果为1，则表示该交易对暂时无法进行交易。

获取账户余额 (私有 API)

通过私有 API 获取账户余额需要进行身份验证，确保只有授权用户才能访问其账户信息。

请求方法： POST

接口地址： /tradingApi

请求头： 

Key: YOUR_API_KEY
Sign: YOUR_SIGNATURE

其中， YOUR_API_KEY 是您在交易所注册后获得的 API 密钥，用于标识您的身份。 YOUR_SIGNATURE 是使用您的私钥对请求参数进行签名后的字符串，用于验证请求的完整性和真实性。签名算法通常包括对请求参数进行排序、拼接，并使用 HMAC-SHA256 等哈希算法加密。

请求参数： 

command=returnBalances

command 参数指定要执行的命令，这里设置为 returnBalances 表示获取账户余额。

响应：

成功调用 API 后，服务器将返回一个 JSON 对象，该对象包含您账户中所有币种的余额信息。JSON 对象的结构可能如下所示： 

{
  "BTC": "1.23456789",
  "ETH": "0.98765432",
  "USDT": "1000.00",
  "LTC": "5.00"
  // ... 其他币种
}

在这个例子中，键代表币种的名称（例如 "BTC" 代表比特币），值代表该币种在您的账户中的余额。余额以字符串形式表示，精度取决于交易所的设置。请注意，实际返回的 JSON 对象可能包含更多字段，例如可用余额、冻结余额等，具体取决于交易所 API 的实现。

安全提示：

  • 务必妥善保管您的 API 密钥和私钥，不要泄露给他人。
  • 建议使用 IP 白名单功能，限制只有特定 IP 地址才能访问您的 API 密钥。
  • 定期更换 API 密钥，以降低安全风险。
  • 在使用 API 进行交易时，务必仔细核对交易参数，防止误操作造成损失。

下单 (私有 API)

使用 POST 方法向 /tradingApi 端点发送请求，进行下单操作。

身份验证：

  • Key : 您的 API 密钥 ( YOUR_API_KEY )。请务必妥善保管您的 API 密钥，避免泄露。
  • Sign : 使用您的私钥对请求参数进行签名后生成的签名值 ( YOUR_SIGNATURE )。签名用于验证请求的真实性和完整性。

请求参数：

command=buy&currencyPair=BTC_USDT&rate=30000&amount=0.001

参数说明：

  • command : 指定交易类型，此处为 buy (买入)。其他可能的值包括 sell (卖出)。
  • currencyPair : 指定交易的货币对，此处为 BTC_USDT (比特币/泰达币)。交易所支持的货币对列表可以在API文档中找到。
  • rate : 指定限价单的价格，此处为 30000 USDT。该参数定义了您愿意购买 BTC 的最高价格。
  • amount : 指定交易的数量，此处为 0.001 BTC。该参数定义了您想要购买的 BTC 数量。

示例：

上述请求将创建一个针对 BTC_USDT 交易对的 限价买单 。该订单指定了以 30000 USDT 的价格购买 0.001 BTC。这意味着只有当市场价格达到或低于 30000 USDT 时，该订单才会被执行。

注意事项：

  • 请确保您的账户有足够的 USDT 余额来支付购买 BTC 的费用。
  • 如果市场价格高于 30000 USDT，该订单将不会立即执行，而是会进入订单簿等待被撮合。
  • API 调用可能会受到速率限制。请参考 API 文档了解具体的限制信息，避免频繁调用导致请求失败。
  • 不同的交易所可能使用不同的参数名称或要求不同的参数格式。请务必参考您所使用交易所的 API 文档。

撤单 (私有 API)

请求方式: POST

接口地址: /tradingApi

身份验证:

Key: YOUR_API_KEY (您的API密钥，用于身份验证)

Sign: YOUR_SIGNATURE (使用您的私钥生成的签名，用于确保请求的完整性和真实性)

请求参数:

command=cancelOrder&orderNumber=YOUR_ORDER_NUMBER

参数说明:

  • command : 指定API操作类型，此处固定为 cancelOrder ，表示撤单操作。
  • orderNumber : 要撤销的订单的唯一标识符。 将 YOUR_ORDER_NUMBER 替换为要取消的实际订单号。订单号通常由交易所生成并在下单时返回。

功能描述:

此API接口用于取消指定订单号的未成交订单。请确保提供的 API 密钥 ( YOUR_API_KEY ) 具有撤单的权限，并且签名 ( YOUR_SIGNATURE ) 是基于正确的消息和私钥生成的。错误的密钥或签名可能导致请求失败。

注意事项:

  • 只有未完全成交的订单才能被撤销。
  • 交易所会根据市场情况和订单状态决定是否允许撤单。
  • 撤单请求可能不会立即生效，请通过查询订单状态API确认订单是否已成功撤销。

示例:

这将尝试取消订单号为 YOUR_ORDER_NUMBER 的订单。请替换 YOUR_ORDER_NUMBER 为您想要取消的实际订单号。

错误处理

Poloniex API 会返回多种错误代码，开发者必须妥善处理这些错误，以确保交易的顺利进行和程序的稳定性。这些错误代码涵盖了身份验证、资金、订单等多个方面的问题。

  • Invalid API key : API 密钥无效。这意味着你提供的 API 密钥不正确或已被禁用。请仔细检查 API 密钥是否正确，并确保已启用所需的权限。如果问题仍然存在，请联系 Poloniex 客服。
  • Invalid signature : 签名无效。这表明请求的签名与服务器计算的签名不匹配。通常是由于使用了错误的密钥、时间戳不准确或请求参数不正确导致的。请仔细检查你的签名算法，确保所有参数都正确，并注意时间同步问题。
  • Insufficient funds : 账户余额不足。这意味着你的账户中没有足够的资金来完成交易。请检查你的可用余额，并确保有足够的资金来支付交易费用。如果需要，请先充值。
  • Order not found : 订单不存在。这通常发生在尝试取消或查询一个不存在的订单时。请确认订单 ID 是否正确，并确保订单没有被完全成交或已过期。

在你的代码中，务必检查 API 返回的错误代码，并采取适当的措施。根据不同的错误类型，你可以选择重试请求（对于临时性错误）、取消订单（如果订单已存在但无法成交）或通知用户（例如余额不足）。完善的错误处理机制能够显著提高程序的健壮性和用户体验。更高级的错误处理策略包括使用指数退避算法进行重试、记录错误日志以便调试和监控、以及设计友好的用户界面来提示用户解决问题。

代码示例 (Python)

以下是一个使用 Python requests 库调用 Poloniex API 的示例，展示了如何进行身份验证和发送请求。该示例涵盖了GET和POST请求，并详细说明了如何生成签名以确保安全通信。

import requests
import hashlib
import hmac
import urllib.parse
import

API_KEY = "YOUR_API_KEY"
API_SECRET = "YOUR_API_SECRET"

def generate_signature(api_secret, params):
encoded_params = urllib.parse.urlencode(params)
signature = hmac.new(api_secret.encode('utf-8'), encoded_params.encode('utf-8'), hashlib.sha512).hexdigest()
return signature

def poloniex_api_call(method, endpoint, params=None):
base_url = "https://poloniex.com/"

if method == "GET":
url = base_url + endpoint
if params:
url += "?" + urllib.parse.urlencode(params)
response = requests.get(url)
elif method == "POST":
url = base_url + endpoint
headers = {
"Key": API_KEY,
"Sign": generate_signature(API_SECRET, params)
}
data = urllib.parse.urlencode(params)
response = requests.post(url, headers=headers, data=data)
else:
raise ValueError("Invalid method")

response.raise_for_status() # Raise HTTPError for bad responses (4xx or 5xx)

try:
return response.()
except .JSONDecodeError:
print(f"Failed to decode JSON. Response text: {response.text}")
return None 


import requests
import hashlib
import hmac
import urllib.parse
import 

API_KEY = "YOUR_API_KEY"
API_SECRET = "YOUR_API_SECRET"

def generate_signature(api_secret, params):
    encoded_params = urllib.parse.urlencode(params)
    signature = hmac.new(api_secret.encode('utf-8'), encoded_params.encode('utf-8'), hashlib.sha512).hexdigest()
    return signature

def poloniex_api_call(method, endpoint, params=None):
    base_url = "https://poloniex.com/"

    if method == "GET":
        url = base_url + endpoint
        if params:
            url += "?" + urllib.parse.urlencode(params)
        response = requests.get(url)
    elif method == "POST":
        url = base_url + endpoint
        headers = {
            "Key": API_KEY,
            "Sign": generate_signature(API_SECRET, params)
        }
        data = urllib.parse.urlencode(params)
        response = requests.post(url, headers=headers, data=data)
    else:
        raise ValueError("Invalid method")

    response.raise_for_status()  # Raise HTTPError for bad responses (4xx or 5xx)

    try:
        return response.()
    except .JSONDecodeError:
        print(f"Failed to decode JSON. Response text: {response.text}")
        return None

示例：获取交易对行情信息

获取指定交易对，例如比特币兑美元 (BTC_USDT) 的实时行情信息。使用 Poloniex API 的 returnTicker 命令，该命令位于公共 API 端点，无需身份验证。通过构建包含 command 参数的请求来调用 API。

ticker_info = poloniex_api_call("GET", "public", {"command": "returnTicker"})

上述代码段中， poloniex_api_call 函数负责与 Poloniex API 进行交互。该函数接收三个参数：HTTP 方法（"GET"）、API 类型（"public"）以及包含命令参数的字典。

API 调用成功后， ticker_info 变量将包含一个字典，其中包含所有交易对的行情数据。通过访问 ticker_info["BTC_USDT"] ，可以获取 BTC_USDT 交易对的详细信息，例如最新成交价、最高价、最低价、交易量等。

if ticker_info: print(ticker_info["BTC_USDT"])

在打印行情信息之前，进行条件检查以确保 ticker_info 变量不为空，这表明 API 调用成功并且返回了数据。如果 ticker_info 包含数据，则打印 BTC_USDT 交易对的行情信息。返回的数据结构是一个字典，包含诸如 last (最新成交价), lowestAsk (最低卖价), highestBid (最高买价), percentChange (涨跌幅), baseVolume (基础货币交易量), quoteVolume (报价货币交易量), isFrozen (是否冻结), high24hr (24小时最高价), low24hr (24小时最低价) 等字段。

示例：获取账户余额

为了查询您的Poloniex账户中各种加密货币的余额，您需要构造一个包含 returnBalances 命令的参数字典。该命令允许您检索所有可用币种的余额信息，包括可用余额、冻结余额等详细数据。

params = {"command": "returnBalances"}

接下来，使用 poloniex_api_call 函数向Poloniex交易API发送一个POST请求。指定 "tradingApi" 表明您正在调用需要API密钥的交易端点。 将之前创建的 params 字典作为参数传递给该函数。 poloniex_api_call 函数负责处理API请求的签名、认证和发送，并返回API响应。

balances = poloniex_api_call("POST", "tradingApi", params)

收到API响应后，检查 balances 变量是否包含有效数据。如果API调用成功并且您的账户存在余额， balances 将包含一个字典，其中键为币种符号（例如 "BTC", "ETH"），值为该币种的余额信息。如果API调用失败或账户无余额， balances 可能为 None 或包含错误信息。

if balances:

如果 balances 包含有效数据，则使用 print(balances) 语句将余额信息打印到控制台。输出结果将是一个Python字典，显示每个币种的可用余额和冻结余额。

交易安全

在使用 API 进行加密货币交易时，安全性是重中之重。由于 API 密钥直接控制您的账户，任何安全疏忽都可能导致严重的资金损失。因此，务必采取以下措施，构建一个多层次的安全体系：

  • 使用强密码并定期更新 : 为您的 Poloniex 账户设置一个高强度、复杂度高的密码，并定期更改。强密码应包含大小写字母、数字和特殊符号，且长度至少为 12 个字符。避免使用容易猜测的密码，例如生日、电话号码或常用单词。定期更换密码有助于防止因密码泄露而造成的损失。
  • 启用双因素身份验证 (2FA) : 启用 2FA 可以为您的账户增加一道重要的安全防线。即使攻击者获得了您的密码，他们也需要第二个验证因素才能访问您的账户。推荐使用 Google Authenticator 或 Authy 等信誉良好的 2FA 应用。强烈建议所有用户启用 2FA，无论交易量大小。
  • 严格限制 API 密钥权限 : API 密钥应遵循最小权限原则。只授予 API 密钥执行所需操作的必要权限。例如，如果您的 API 密钥仅用于读取市场数据，则不要授予其交易或提款权限。这样，即使 API 密钥泄露，攻击者也无法进行未经授权的交易或提款。仔细审查每个 API 密钥的权限设置，确保它们符合您的实际需求。
  • 持续监控账户活动 : 定期检查您的交易历史记录、订单历史记录和账户余额，密切关注是否有任何未经授权的活动或异常情况。如果发现任何可疑活动，立即更改您的密码和 API 密钥，并联系 Poloniex 官方客服进行报告。使用交易平台的通知功能，及时接收账户活动的提醒。
  • 使用安全可靠的网络连接 : 避免在使用公共 Wi-Fi 网络进行交易。公共 Wi-Fi 网络通常缺乏安全保护，容易受到中间人攻击。使用安全的、受信任的家庭网络或移动数据网络进行交易。考虑使用 VPN（虚拟专用网络）来加密您的网络流量，进一步提高安全性。
  • 妥善保管 API 密钥，防止泄露 : 不要将 API 密钥以明文形式存储在不安全的地方，例如文本文件、电子邮件或版本控制系统中。使用加密存储或安全的密钥管理工具来保护您的 API 密钥。定期更换 API 密钥，以降低密钥泄露带来的风险。请勿在公共论坛或社交媒体上分享您的 API 密钥。
  • 进行全面的代码审计 : 如果您使用 API 编写自定义交易程序，请务必仔细检查您的代码，确保没有安全漏洞。特别注意输入验证、错误处理和身份验证方面的问题。可以考虑聘请专业的安全审计师来审查您的代码，以发现潜在的安全风险。定期更新您的代码，以修复已知的安全漏洞。

限速

Poloniex API 为了确保平台的稳定性和公平性，对所有用户的请求频率都设置了明确的限制。这意味着在一定的时间段内，你可以向 API 发送的请求数量是有限的。 当你的请求频率超过了预设的限制，Poloniex API 将会返回一个特定的错误代码，明确指出你已触发了限速机制。要有效地避免被限速，至关重要的是详细阅读并理解 Poloniex API 的官方文档，该文档会清晰地说明允许的请求频率上限。

为了更好地管理你的 API 请求，你应该仔细调整你的程序或脚本，以确保请求频率符合 Poloniex 的规定。一种有效的方法是实现速率限制器，它可以自动控制请求的发送速度，防止超出限制。

在实际应用中，可以通过检查 API 返回的 HTTP 头部信息来监控你的请求状态。 这些头部信息通常包含关于剩余请求次数（Remaining Requests）和速率限制重置时间（Rate Limit Reset Time）的关键数据。 通过实时监控这些数据，你可以动态地调整你的请求频率，并确保在达到限制之前及时停止发送请求，从而避免被限速。 妥善处理 API 返回的错误代码也至关重要，以便你的程序能够优雅地处理限速情况，并采取适当的措施，例如延迟请求或重试。

上一篇

Bitfinex P2P转账与账户安全：风险解析与防范指南

下一篇

欧易交易所Bytecoin(BCN)购买指南：轻松入手教程

相关推荐