API Key Management

⚠️ API access is available only for business accounts.

Create a business account

Corporate account details

API keys are managed in the API section of the YouHodler web application.

Operations

The following operations are available for API keys:

Create API Key — issue a new API key
Revoke API Key — disable an existing API key
Reactivate API Key — re-enable a previously revoked API key (a new key will be issued)

Secret

When an API key is successfully created, you will also receive a secret.

The secret is required for request signing and authentication. Detailed information about request signing is provided in the section below.

IP Whitelist (Optional)

You can optionally restrict API key usage by configuring an IP whitelist.

Both IPv4 and IPv6 addresses are supported.

Only requests originating from the whitelisted IP addresses will be accepted by the API.

API Key Authentication

Include your API key in the x-apikey HTTP header with every request:

curl -X GET "https://api.youhodler.com/v1/balance" \
  -H "x-apikey: YOUR_API_KEY"

Signing POST Requests

All POST requests must be signed with an Ed25519 signature. The signature is computed over the raw request body and sent in the x-signature header.

When you create API credentials, YouHodler returns an Ed25519 private key (PKCS#8 DER format, base64-encoded). Keep it secret — the server only stores the corresponding public key and cannot recover your private key.

Required Fields

Every POST request body must include:

Field	Type	Description
`timestamp`	number	Current time in milliseconds (Unix epoch)
`recvWindow`	number	(optional) Maximum allowed delay in ms between `timestamp` and server time. Default: `5000`, max: `60000`

How to Sign

Build the JSON request body including timestamp (and optionally recvWindow).
Sign the raw JSON string (bytes) using your Ed25519 private key.
Base64-encode the 64-byte Ed25519 signature.
Send the result in the x-signature header.

Examples

Java

import java.net.URI;
import java.net.http.*;
import java.nio.charset.StandardCharsets;
import java.security.*;
import java.security.spec.PKCS8EncodedKeySpec;
import java.util.Base64;

String privateKeyBase64 = "YOUR_PRIVATE_KEY_BASE64"; // PKCS#8 DER, base64
String apiKey = "YOUR_API_KEY";

long timestamp = System.currentTimeMillis();
String body = "{\"fromTicker\":\"btc\",\"toTicker\":\"usd\",\"fromAmount\":\"0.1\",\"timestamp\":" + timestamp + "}";

// Load Ed25519 private key
byte[] keyBytes = Base64.getDecoder().decode(privateKeyBase64);
PKCS8EncodedKeySpec keySpec = new PKCS8EncodedKeySpec(keyBytes);
KeyFactory kf = KeyFactory.getInstance("Ed25519");
PrivateKey privateKey = kf.generatePrivate(keySpec);

// Sign the body
Signature signer = Signature.getInstance("Ed25519");
signer.initSign(privateKey);
signer.update(body.getBytes(StandardCharsets.UTF_8));
String signatureBase64 = Base64.getEncoder().encodeToString(signer.sign());

// Send the request
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.youhodler.com/v1/convert/getQuote"))
    .header("x-apikey", apiKey)
    .header("x-signature", signatureBase64)
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString(body))
    .build();

HttpResponse<String> response = HttpClient.newHttpClient()
    .send(request, HttpResponse.BodyHandlers.ofString());

Note: Ed25519 support requires Java 15+.

Node.js

const crypto = require("node:crypto");

const privateKeyBase64 = "YOUR_PRIVATE_KEY_BASE64"; // PKCS#8 DER, base64
const apiKey = "YOUR_API_KEY";

const body = JSON.stringify({
  fromTicker: "btc",
  toTicker: "usd",
  fromAmount: "0.1",
  timestamp: Date.now(),
});

const privateKey = crypto.createPrivateKey({
  key: Buffer.from(privateKeyBase64, "base64"),
  format: "der",
  type: "pkcs8",
});

const signature = crypto.sign(null, Buffer.from(body, "utf8"), privateKey);
const signatureBase64 = signature.toString("base64");

// Use signatureBase64 as the x-signature header value

Python

from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey
from cryptography.hazmat.primitives.serialization import load_der_private_key
import base64, json, time, requests

private_key_b64 = "YOUR_PRIVATE_KEY_BASE64"  # PKCS#8 DER, base64

private_key = load_der_private_key(base64.b64decode(private_key_b64), password=None)

body = json.dumps({
    "fromTicker": "btc",
    "toTicker": "usd",
    "fromAmount": "0.1",
    "timestamp": int(time.time() * 1000),
})

signature = private_key.sign(body.encode("utf-8"))
signature_b64 = base64.b64encode(signature).decode()

resp = requests.post(
    "https://api.youhodler.com/v1/convert/getQuote",
    headers={
        "x-apikey": "YOUR_API_KEY",
        "x-signature": signature_b64,
        "Content-Type": "application/json",
    },
    data=body,
)

Signature Errors

HTTP Status	Error Code	Error Label	Description
401	9008	`MISSING_SIGNATURE`	The `x-signature` header is missing on a POST request
401	9009	`INVALID_SIGNATURE`	The signature does not match
401	1001	`INVALID_TIMESTAMP`	The `timestamp` is missing or the request has expired

Authentication Errors

If authentication fails, the API returns one of the following errors:

HTTP Status	Error Code	Error Label	Description
401	9006	`MISSING_API_KEY`	The `x-apikey` header was not provided
401	9007	`INVALID_API_KEY`	The API key is invalid or has been revoked
401	9001	`UNAUTHORIZED`	General authorization failure
403	9012	`INVALID_IP`	Request IP is not in the allowlist
403	9013	`KYC_NOT_VERIFIED`	KYC verification not completed
403	9014	`API_NOT_AVAILABLE`	API access is not available for this account

Example error response:

{
  "errorCode": 9006,
  "errorLabel": "MISSING_API_KEY",
  "errorDescription": "Missing X-APIKEY in headers"
}

Security Best Practices

Never expose your API key or private key in client-side code or public repositories.
Keep the Ed25519 private key secure — it cannot be recovered from the server.
Rotate your API credentials periodically through your account manager.
Use IP allowlisting to restrict which IPs can use your API key.
Always include a timestamp in POST requests and keep recvWindow as small as practical to limit replay attacks.