Authentication - Hit Documentation

Hit trading bots use API key authentication with HMAC-SHA256 signatures. Public market data endpoints do not require authentication. Private trading endpoints and the /user WebSocket namespace require a trading API key, secret and passphrase.

Keep the API secret and passphrase out of source control and browser code. They are for server-side bots and services.

Credentials

Configure your bot with:

export HIT_API_KEY='API_KEY'
export HIT_API_SECRET='API_SECRET'
export HIT_API_PASSPHRASE='API_PASSPHRASE'

API key creation and key management are handled in the Hit app. These docs cover how to use an existing trading key from a programmatic client.

REST HMAC Headers

Every authenticated REST request must include:

Header	Value
`hit-api-key`	API key identifier
`hit-signature`	HMAC-SHA256 signature
`hit-timestamp`	Unix timestamp in milliseconds
`hit-passphrase`	API passphrase returned at key creation

The signature message is:

timestamp + "\n" + method + "\n" + pathWithQuery + "\n" + body

Rules:

The four parts are joined with one newline character (\n, byte 0x0A) between each, and no newline follows body. A request without a body therefore ends with the newline that precedes the empty body.
method is uppercase, such as GET, POST or DELETE.
pathWithQuery includes /api/v1 and the query string exactly as sent, including the ?, and excludes the scheme and host. With no query string it is just the path.
body is the request body exactly as sent, byte for byte. Serialize it once into a variable, then sign and send that same string. Signing a separate re-serialization of your object produces a different signature.
Timestamps must be within 30 seconds of server time.

Legacy Signature Message

The original message is still accepted, with no retirement date set, so existing bots keep working unchanged:

timestamp + method + path + body

It differs from the recommended message in two ways, not one. The parts are concatenated with no separator between them, and the parts themselves are different: path excludes the query string, and body is a re-serialization of the parsed JSON rather than the bytes you sent. Inserting newlines into a legacy message does not produce a valid recommended-form signature. For a GET request to /api/v1/markets/user-positions?id=abc&id=def with timestamp 1699123456789 and no body, the two forms sign:

Form	Message signed
Recommended	`1699123456789\nGET\n/api/v1/markets/user-positions?id=abc&id=def\n`
Legacy	`1699123456789GET/api/v1/markets/user-positions`

Each \n above is one newline character, not the two characters \ and n.

Where the Legacy Message Is Required

The recommended message is built from the raw request body the server captured. Where there is no raw body to capture, only the legacy message can match. Two cases matter in practice:

File uploads. A multipart/form-data request has no raw body available to the server, so a signature over the bytes you sent cannot match.
The /user WebSocket handshake. WebSocket authentication runs through a different service that builds only the concatenated message. See WebSocket Auth.

REST Signing Examples

TypeScript
Python
Rust

import { createHmac } from "node:crypto";

type JsonBody = Record<string, unknown>;

function signRequest(
  apiSecret: string,
  timestamp: string,
  method: string,
  pathWithQuery: string,
  body = "",
) {
  const message = [timestamp, method.toUpperCase(), pathWithQuery, body].join("\n");

  return createHmac("sha256", apiSecret).update(message).digest("hex");
}

async function hitRequest(method: string, path: string, body?: JsonBody) {
  const apiHost = "https://hit.com";
  // Any query string belongs in `path`, because it is part of the signed message.
  const fullPath = `/api/v1${path}`;
  const timestamp = Date.now().toString();
  // Serialized once, then both signed and sent.
  const bodyText = body ? JSON.stringify(body) : "";

  const response = await fetch(`${apiHost}${fullPath}`, {
    method,
    headers: {
      "Content-Type": "application/json",
      "hit-api-key": process.env.HIT_API_KEY!,
      "hit-signature": signRequest(
        process.env.HIT_API_SECRET!,
        timestamp,
        method,
        fullPath,
        bodyText,
      ),
      "hit-timestamp": timestamp,
      "hit-passphrase": process.env.HIT_API_PASSPHRASE!,
    },
    body: bodyText || undefined,
  });

  if (!response.ok) {
    throw new Error(`${response.status}: ${await response.text()}`);
  }

  return response.json() as Promise<unknown>;
}

const orders = await hitRequest("GET", "/orders");
console.log(orders);

import hashlib
import hmac
import json
import os
import time

import requests


def sign_request(
    secret: str, timestamp: str, method: str, path_with_query: str, body: str = ""
) -> str:
    message = "\n".join([timestamp, method.upper(), path_with_query, body])
    return hmac.new(secret.encode(), message.encode(), hashlib.sha256).hexdigest()


def hit_request(method: str, path: str, payload: dict | None = None):
    api_host = "https://hit.com"
    # Any query string belongs in path, because it is part of the signed message.
    full_path = f"/api/v1{path}"
    timestamp = str(int(time.time() * 1000))
    # Serialized once, then both signed and sent.
    body = json.dumps(payload, separators=(",", ":")) if payload else ""

    response = requests.request(
        method,
        f"{api_host}{full_path}",
        headers={
            "Content-Type": "application/json",
            "hit-api-key": os.environ["HIT_API_KEY"],
            "hit-signature": sign_request(
                os.environ["HIT_API_SECRET"],
                timestamp,
                method,
                full_path,
                body,
            ),
            "hit-timestamp": timestamp,
            "hit-passphrase": os.environ["HIT_API_PASSPHRASE"],
        },
        data=body or None,
        timeout=10,
    )
    response.raise_for_status()
    return response.json()


print(hit_request("GET", "/orders"))

json.dumps(payload, separators=(",", ":")) produces the exact string that requests sends as the body, so signing that same body variable signs the bytes the server receives.

use hmac::{Hmac, Mac};
use reqwest::blocking::Client;
use serde_json::Value;
use sha2::Sha256;
use std::env;
use std::time::{SystemTime, UNIX_EPOCH};

type HmacSha256 = Hmac<Sha256>;

fn timestamp_ms() -> String {
    SystemTime::now()
        .duration_since(UNIX_EPOCH)
        .expect("system clock before unix epoch")
        .as_millis()
        .to_string()
}

fn sign_request(
    secret: &str,
    timestamp: &str,
    method: &str,
    path_with_query: &str,
    body: &str,
) -> String {
    let message = format!(
        "{}\n{}\n{}\n{}",
        timestamp,
        method.to_uppercase(),
        path_with_query,
        body
    );
    let mut mac = HmacSha256::new_from_slice(secret.as_bytes()).expect("hmac accepts any key");
    mac.update(message.as_bytes());
    hex::encode(mac.finalize().into_bytes())
}

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = Client::new();
    // Any query string belongs in full_path, because it is part of the signed message.
    let full_path = "/api/v1/orders";
    let timestamp = timestamp_ms();
    let signature = sign_request(
        &env::var("HIT_API_SECRET")?,
        &timestamp,
        "GET",
        full_path,
        "",
    );

    let response: Value = client
        .get(format!("https://hit.com{}", full_path))
        .header("Content-Type", "application/json")
        .header("hit-api-key", env::var("HIT_API_KEY")?)
        .header("hit-signature", signature)
        .header("hit-timestamp", timestamp)
        .header("hit-passphrase", env::var("HIT_API_PASSPHRASE")?)
        .send()?
        .error_for_status()?
        .json()?;

    println!("{response:#}");
    Ok(())
}

WebSocket Auth

The /user Socket.IO namespace authenticates after connect with a user-connect message. The WebSocket signature message is different from REST:

timestamp + WEBSOCKET + /user

The newline-separated REST message does not apply here. The handshake is verified by a different service, which builds only the concatenated message above, so signing the newline form fails authentication.

Payload:

{
  "auth": {
    "apiKey": "API_KEY",
    "signature": "HMAC_SIGNATURE",
    "timestamp": "1778748000000",
    "passphrase": "API_PASSPHRASE"
  }
}

The server responds on user-authenticated with { "success": true } or { "success": false, "error": "..." }.

Authentication Failures

A REST request whose trading API key fails authentication returns 401 with the message Authentication failed. The response does not say which check failed, so work through the causes in order:

A required header is missing.
The timestamp is outside the 30 second window, usually because the host clock has drifted.
The API key is unknown or no longer active.
The passphrase does not match the key.
The signature matches neither accepted message.

If your client branches on the older, more specific messages such as Invalid signature or Invalid passphrase, stop: those strings are no longer returned. The one exception is a key that could not be checked, which never gets a 401. A request whose key could not be checked against its current credentials, because the auth service could not be asked about it or did not answer with them or a refusal, returns 503 with error: CREDENTIAL_UNVERIFIABLE and no Retry-After header instead. Your key was not checked, so re-send the request, signed again with a fresh hit-timestamp, and keep the key.

Security Notes

Keep API secrets out of source control and client-side browser code.
Use separate keys for separate bots or services.
Deactivate unused or compromised keys immediately.
Keep host clocks synchronized; requests outside the timestamp window are rejected.

​Credentials

​REST HMAC Headers

​Legacy Signature Message

​Where the Legacy Message Is Required

​REST Signing Examples

​WebSocket Auth

​Authentication Failures

​Security Notes

Credentials

REST HMAC Headers

Legacy Signature Message

Where the Legacy Message Is Required

REST Signing Examples

WebSocket Auth

Authentication Failures

Security Notes