Guía de autenticación de API

Ejemplo: flujo de credenciales de cliente: A continuación se muestra un ejemplo de solicitud en el que se utilizan las credenciales del cliente y la estructura de respuesta:

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

En caso de éxito, recibirás una respuesta de JSON como:

{
 «jsonrpc»: «2.0",
 «id»: 1,
 «resultado»: {
 «access_token»: «1582628593469.1mbq-j_4.cbp-oqow... uArm», 
 «expirar»: 31536000,
 «refresh_token»: «1582628593469.1gp4rqd0.a9wa78... A9jm»,
 «scope»: «cuenta principal de conexión»,
 «token_type»: «portador»
 }

El access_token es una cadena larga (truncada arriba) que se utiliza para autenticar las solicitudes posteriores. El campo expires_in (en segundos) indica durante cuánto tiempo es válido el token, y el refresh_token se puede almacenar para renovar el acceso cuando sea necesario. El alcance muestra el alcance de acceso otorgado a este token (más información sobre los ámbitos más adelante) y token_type

Uso del token: Una vez que tengas un token de acceso, debes incluirlo en cualquier solicitud de API privada. La forma de incluirlo depende del tipo de conexión:

Autenticación de firmas de

Para realizar un firma de cliente autenticación:

1. Prepare los componentes:

2. Construye la cadena para firmar:

flujo de firmas de clientes de Deribit firma una secuencia de bytes muy específica. Utilice HMAC‑SHA256 con tu Secreto de cliente como clave y codifican hexágonamente el resumen.

Fórmula:

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

Detalles importantes

Shell (OpenSSL) de una línea

Forma general, funciona en Linux y 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"

Ejemplo

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. Enviar la solicitud:

Llame al público/auth con grant_type=client_signature e incluyen:

Ejemplo de solicitud JSON-RPC con valores calculados anteriormente:

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

En caso de éxito, el servidor devuelve un access_token y refresh_token, igual que con la autenticación de credenciales de cliente.

También puede usar el siguiente código de Python para generar automáticamente la firma y completar el proceso de autenticación en el entorno de prueba

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)

Cuando te autenticas con público/de autenticación (con las credenciales del cliente o la firma del cliente), la respuesta contiene tanto un access_token y un refresh_token.

¿Por qué usar un token de actualización?

Los tokens de acceso tienen una vida útil limitada (definida en el expires_in campo). En lugar de volver a proporcionar su ID de cliente y su secreto de cliente cada vez, puede llamar público/de autenticación otra vez con grant_type=refresh_token y tu token de actualización almacenado. Esto prolonga la sesión de forma segura sin exponer sus credenciales.

Ejemplo:

{
  "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>"
  }
}

La respuesta contiene una nueva access_token (y un nuevo refresh_token).

Comportamiento de sesión

Mejores prácticas

Token de horquilla

Los tokens de sesión se pueden «clonar» mediante el public/fork_token método. Se trata de una función avanzada que ayuda a gestionar varias sesiones. fork_token toma un token de actualización válido de un token de ámbito de sesión existente y genera un nuevo token de acceso para una nueva sesión (con el nombre que especifiques). En otras palabras, te permite convertir una sesión existente en otra sin volver a proporcionar el secreto de su cliente. Esto solo está permitido para los tokens de ámbito de sesión (no puedes bifurcar un token solo de conexión

¿Cuándo usar el token de bifurcación?

Supongamos que ya tiene una aplicación autenticada en un servidor y desea activar un segundo cliente (o un subservicio) mediante el misma cuenta y clave de API. En lugar de almacenar el secreto del cliente o volver a solicitar las credenciales, puedes tomar el token de actualización de la primera sesión y llamar public/fork_token para crear un nuevo token de sesión para el segundo cliente. El nuevo token tendrá los mismos alcances que el original (pero estará vinculado a un nombre de sesión diferente). Ambas sesiones pueden funcionar simultáneamente con la misma clave de API

Token de intercambio

public/exchange_token te permite convertir un token de actualización en un nuevo token de acceso para una subcuenta diferente. UN subject_id identifica la subcuenta de destino, por lo que este método es la forma estándar de cambiar entre subcuentas sin volver a enviar tu secreto de cliente. El token resultante conserva los mismos permisos a menos que indiques una anulación del alcance

¿Cuándo usar el token de intercambio?

Estás autenticado en una subcuenta y debes actuar en otra subcuenta con la misma clave de API. Llama public/exchange_token con:

Para mayor comodidad, Deribit también admite dos métodos alternativos para las solicitudes HTTP: Autenticación básica y Autenticación 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. 

Con Autenticación HMAC (Credenciales de firma de Deribit), firmas la solicitud con tu secreto (como en el método client_signature) y lo incluyes en un Authorization: deri-hmac-sha256 ... encabezado.

Estos métodos eliminan la necesidad de solicitar un token previamente, pero normalmente se usan en escenarios avanzados o si prefieres no gestionar la actualización de los tokens por separado. La mayoría de los desarrolladores consideran que es el método más sencillo de usar público/de autenticación para obtener un token de portador y usarlo en llamadas posteriores.