Skip to content

Authentication

Overview

Every API request to Cactus Custody must be authenticated using SHA256 with ECDSA signature. This guide walks you through the authentication process step-by-step.

API Rate Limit: 30 requests per second

Get Your API Credentials

Generate your key pair

Generate a public-private ECDSA key pair (Refer to Generate Key Pair).

Submit your public key

  • Log in as Administrator
  • Navigate to: User Management β†’ User β†’ Public Key
  • Upload your public key file in PEM format
  • You'll receive an AKID via email

Get your API Key

To obtain your API key, please contact our team.

Prepare Your API Request

Before making your request, gather these components:

Component Description Example
Request Method HTTP method in UPPERCASE GET, POST, PUT
URI The API endpoint path /custody/v1/api/wallets
Parameters Query string parameters (if any) ?coin=BTC
x-api-nonce Unique request identifier Generate a UUID. A UUID can be generated using built-in libraries provided by the programming language you are using.
Date The timestamp must reflect the current time in GMT format; otherwise, an error will occur Tue, 03 Mar 2020 12:26:57 GMT

Date Format: Date must be in the exact format: EEE, dd MMM yyyy HH:mm:ss zzz and use GMT+0 timezone; otherwise, error code 10380002 will be returned.

Build the Content To Sign

This is the string you'll sign with your private key. The format differs between GET and POST requests.

Format

GET\n
application/json\n
\n
application/json\n
[GMT Date]\n
x-api-key:[Your API Key]\n
x-api-nonce:[Your Nonce]\n
[URI]?{[Sorted Parameters]}

Notice the empty line after the second application/json (line 3 is blank)

Example

GET\n
application/json\n
\n
application/json\n
Tue, 03 Mar 2020 12:26:57 GMT\n
x-api-key:X5SGmgTAoYaVw1t7oD2p82pHgf0eNNVw3wxYGgM2\n
x-api-nonce:36dbe33ed529455cb0638eef0f5f59e3\n
/custody/v1/api/wallets?{b_id=[4a3e2fb40faa4b9d94480559ac01e8de], coin_names=[BTC,LTC], hide_no_coin_wallet=[false], total_market_order=[0]}

Format

POST\n
application/json\n
[Body Hash]\n
application/json\n
[GMT Date]\n
x-api-key:[Your API Key]\n
x-api-nonce:[Your Nonce]\n
[URI]

Body Hash Calculation: Base64(SHA256(request_body))

Example

POST\n
application/json\n
3cLLd5MmUAMM2BneR7eT0NV9AZ4TUJ2F7xy31krmInQ=\n
application/json\n
Tue, 03 Mar 2020 13:26:57 GMT\n
x-api-key:X5SGmgTAoYaVw1t7oD2p82pHgf0eNNVw3wxYGgM2\n
x-api-nonce:36dbe33ed529455cb0638eef0f5f59e3\n
/custody/v1/api/projects/4a3e2fb40faa4b9d94480559ac01e8de/order/create

Parameter formatting rules

  • Format: {paramName=[paramValue], paramName=[paramValue]}
  • Sorting: Multiple parameters must be in alphabetical order by parameter name

Generate The Signature

Sign the content

Using your private key, sign the "Content to Sign" string:

Signature = Base64(SHA256withECDSA(ContentToSign))

Build the authorization header

Combine your credentials in this format:

api [AKId]:[Signature]

Example:

api e4c9f9024bff472cba51cb2a9fe0f974:MEUCIQCOWdpspTVI0KlkZNPwHTr8JAdo0tBtLeg6I9aeqRr4+QIgeXfCgrqhLkyXAjh21NcP1AHXH9V4a3bTl+GaevmbQyo=

Make Your API Request

GET request headers

{
    "x-api-key": "H12q1kJRfa341wajqyZ6ya6cm9ZtOJaq3DXWJTb4",
    "x-api-nonce": "59ae8151fb5949d5ac3e35e919e26265",
    "Accept": "application/json",
    "Date": "Tue, 03 Mar 2020 12:26:57 GMT",
    "Content-type": "application/json",
    "Authorization": "api e4c9f9024bff472cba51cb2a9fe0f974:MEUCIQCOWdpspTVI0KlkZNPwHTr8JAdo0tBtLeg6I9aeqRr4+QIgeXfCgrqhLkyXAjh21NcP1AHXH9V4a3bTl+GaevmbQyo="
}

POST request headers

{
    "x-api-key": "H12q1kJRfa341wajqyZ6ya6cm9ZtOJaq3DXWJTb4",
    "x-api-nonce": "59ae8151fb5949d5ac3e35e919e26265",
    "Accept": "application/json",
    "Content-SHA256": "l5lLhZ9tlS/bnbPa2LUTkki5cFVQ3n9+4Imtkmaoz6U=",
    "Date": "Tue, 03 Mar 2020 12:26:57 GMT",
    "Content-type": "application/json",
    "Authorization": "api e4c9f9024bff472cba51cb2a9fe0f974:MEUCIQCOWdpspTVI0KlkZNPwHTr8JAdo0tBtLeg6I9aeqRr4+QIgeXfCgrqhLkyXAjh21NcP1AHXH9V4a3bTl+GaevmbQyo="
}

Header Fields Reference

HeaderRequired ForDescription
x-api-keyAll requestsYour API Key
x-api-nonceAll requestsUnique request ID (use UUID)
AcceptAll requestsAlways "application/json"
DateAll requestsGMT timestamp
Content-typeAll requestsAlways "application/json"
Content-SHA256POST/PUT onlyBase64(SHA256(request body))
AuthorizationAll requestsapi [AKId]:[Signature]

Common Mistakes

Watch out for these common mistakes:

Newline characters are REAL newlines

The \n in "Content to Sign" are actual newline characters, not the literal string "\n". Make sure your code interprets them correctly.

Parameters must be alphabetically sorted

URL parameters must be sorted alphabetically by parameter name. The order matters for signature validation!

GET requests have an empty line

Notice the empty line after "application/json" in GET requests (line 3). POST requests have the body hash in that position instead.

Date format must match exactly

The date must follow the format: EEE, dd MMM yyyy HH:mm:ss zzz. Even small variations will cause authentication to fail. Do note that the timing format must be in GMT +0.

Rate limiting

Don't exceed 30 requests per second or your requests will be throttled.

Need Help? If you're still having trouble with authentication, please contact our support team with your request details.