API 身份验证指南

示例-客户凭证流程： 以下是使用客户端凭证的示例请求和响应结构：

GET /api/v2/public/auth?grant_type=client_credentials&client_id=<YOUR_CLIENT_ID>&client_secret=<YOUR_CLIENT_SECRET>

成功后，您将收到 JSON 响应，例如：

{
 “jsonrpc”：“2.0”，
 “id”：1,
 “结果”：{
 “access_token”：“1582628593469.1mbq-j_4.cbp-oqow... uARM”， 
 “expires_in”：31536000，
 “refresh_token”：“1582628593469.1gp4rqd0.a9wa78... a9jm”，
 “范围”：“连接主账户”，
 “token_type”：“持有者”
 }

access_token 是一个长字符串（上面已截断），用于对后续请求进行身份验证。expires_in 字段（以秒为单位）告诉您令牌的有效期限，并且可以存储 refresh_token 以在需要时续订访问权限。范围显示了该令牌的授予访问范围（有关范围的更多信息见下文），token_type 将是 “

使用代币： 获得访问令牌后，必须将其包含在任何令牌中 私有 API 请求。如何包含它取决于连接类型：

客户签名认证

要执行 客户签名 身份验证：

1。准备组件：

2。生成待签字符串：

Deribit 的客户端签名流程签署了一个非常具体的字节序列。 HMAC‑SHA256 和你的 客户机密 作为密钥并对摘要进行十六进制编码。

公式：

StringToSign = Timestamp + "\n" + Nonce + "\n" + Data
Signature    = HEX_STRING( HMAC-SHA256( ClientSecret, StringToSign ) )

重要细节

Shell (OpenSSL) 单行

通用格式，适用于 Linux 和 macOS：

ClientId="YOUR_CLIENT_ID"
ClientSecret="YOUR_CLIENT_SECRET"

Timestamp="$(date +%s000)"                          # ms since epoch; on macOS this is fine
Nonce="$(LC_ALL=C tr -dc 'a-z0-9' </dev/urandom | head -c8)"
Data=""                                             # or some context string

Signature="$(
  printf "%s\n%s\n%s" "$Timestamp" "$Nonce" "$Data" \
  | openssl dgst -sha256 -hmac "$ClientSecret" -r \
  | cut -d' ' -f1
)"
echo "$Signature"

示例

ClientId=AMANDA
ClientSecret=AMANDASECRECT
Timestamp=1576074319000
Nonce=1iqt2wls
Data=""

Signature="$(
  printf "%s\n%s\n%s" "$Timestamp" "$Nonce" "$Data" \
  | openssl dgst -sha256 -hmac "$ClientSecret" -r \
  | cut -d' ' -f1
)"
echo "$Signature"
# -> 56590594f97921b09b18f166befe0d1319b198bbcdad7ca73382de2f88fe9aa1

3. 发送请求：

致电公众/身份验证 grant_type=client_signature 并包括：

使用之前计算的值对 JSON-RPC 请求进行示例：

{
  "jsonrpc": "2.0",
  "id": 9929,
  "method": "public/auth",
  "params": {
    "grant_type": "client_signature",
    "client_id": "AMANDA",
    "timestamp": 1576074319000,
    "nonce": "1iqt2wls",
    "data": "",
    "signature": "56590594f97921b09b18f166befe0d1319b198bbcdad7ca73382de2f88fe9aa1"
  }
}

成功后，服务器返回 access_token 和 refresh_token，与客户端凭证身份验证相同。

您还可以使用以下 Python 代码自动生成签名并在测试环境中完成身份验证过程

import datetime
import random
import string
import hashlib
import hmac
import requests
from datetime import datetime

ClientId = ""
clientSecret = ""
Timestamp = round(datetime.now().timestamp() * 1000)
Nonce = ''.join(random.choice(string.ascii_lowercase + string.digits) for _ in range(8))
data = ""

def calcSignature(method, uri, secret, timestamp, nonce, body):
    requestData = f'{method}\n{uri}\n{body}\n'
    message = f'{timestamp}\n{nonce}\n{requestData}'
    return hmac.new(
        bytes(secret, "ascii"),  # Changed to 'utf-8'
        msg=bytes(message, "utf-8"),  # Changed to 'utf-8'
        digestmod=hashlib.sha256
    ).hexdigest().lower()

Signature = calcSignature("GET", "/api/v2/private/get_account_summary?currency=BTC&extended=true", clientSecret, Timestamp, Nonce, data)

headers = {
    'Authorization': f'deri-hmac-sha256 id={ClientId},ts={Timestamp},nonce={Nonce},sig={Signature}',
    'Content-Type': 'application/json'  # Added Content-Type header
}

response = requests.get(
    "https://test.deribit.com/api/v2/private/get_account_summary?currency=BTC&extended=true", 
    headers=headers
)

print(response.json())
print(ClientId, Timestamp, Nonce, Signature)

当您使用进行身份验证时 公共/身份验证 （使用客户凭证或客户签名），响应中同时包含 access_token 还有一个 refresh_token。

为什么要使用刷新令牌？

访问令牌的生命周期有限（定义在 expires_in 字段）。您可以致电，而不是每次都重新提供您的客户端 ID 和客户密钥 公共/身份验证 再说一遍 grant_type=refresh_token 以及您存储的刷新令牌。这样可以安全地延长会话时间，而不会暴露您的证书

示例：

{
  "method": "public/auth",
  "params": {
    "grant_type": "refresh_token",
    "refresh_token": "<1756301374726.1R2lPbsF.Q_Oqe7J-NpqHhhVV46NHvJuaidr5S1e3pdaO9pAvUoPmJFnSU9faJqxSiTp2Q4I_oT8XsiQo3mMu-0wFoqnY80Epz84XmRH-wQaCZ0jJEMFLUWZI-ILtUPMoPwvL9QFxhAX9sw8J-8559qNHjAJ_X3a_oGk8GTmIpEEF6Zenr00VWiPsMWxY17LmQf6xXd5q4kHk7cLsyoTSv76qrP-260xsshwomb6iJ7SMdTQYlG1D69mBBr1q_ECupVoOm0w9Wp0pxC0KSqyalhuNMLcKGFZveCA-pZQ2GH93WQptzVA-Mh0Gcw>"
  }
}

回复中包含一个新的 access_token （还有一个新的 refresh_token）。

会话行为

最佳实践

分叉代币

可以使用 “克隆” 会话令牌 公共/fork_token 方法。这是一项高级功能，可帮助管理多个会话。 fork_token 从现有的会话范围令牌中获取有效的刷新令牌，并为新会话生成新的访问令牌（使用您指定的名称）。换句话说，它允许您将现有会话分叉到另一个会话 无需重新提供您的客户机密信息。这仅适用于会话范围的令牌（您不能分叉仅限连接的

何时使用分叉代币？

假设您的应用程序已经在一台服务器上进行了身份验证，并且您想使用启动第二个客户端（或子服务） 相同的账户和 API 密钥。您可以从第一次会话中获取刷新令牌并调用，而不必存储客户端密钥或再次要求提供证书 公共/fork_token 创建一个 新的 第二个客户端的会话令牌。新令牌将具有与原始令牌相同的范围（但绑定到不同的会话名称）。两个会话可以在同一 API 密钥下并行运行

交换代币

公共/交易所代币 允许您将刷新令牌转换为其他子账户的新访问令牌。 subject_id 标识目标子账户，因此此方法是在子账户之间切换的标准方式，无需再次发送您的客户端密钥。除非您提供范围覆盖，否则生成的令牌将保持相同的权限。

何时使用交换代币？

您在一个子账户上进行了身份验证，需要使用相同的 API 密钥对另一个子账户进行操作。打电话 公共/交易所代币 和：

为方便起见，Deribit 还支持 HTTP 请求的两种替代方法： 基本身份验证 和 HMAC 身份验证。

With Basic Auth, you can send: Authorization: Basic <base64(client_id:client_secret)> in your HTTP request, and Deribit will authenticate and execute the request in one step. 

和 HMAC 身份验证 （Deribit 签名证书），您使用您的密钥（如 client_signature 方法）对请求进行签名，并将其包含在 Authorization: deri-hmac-sha256 ... 标题。

这些方法无需事先发出令牌请求，但通常用于高级场景或不想单独处理令牌刷新时使用。大多数开发人员发现它最容易使用 公共/身份验证 获取持有者令牌并将其用于后续调用。