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]}
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:
Build the authorization header¶
Combine your credentials in this format:
Example:
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¶
| Header | Required For | Description |
|---|---|---|
| x-api-key | All requests | Your API Key |
| x-api-nonce | All requests | Unique request ID (use UUID) |
| Accept | All requests | Always "application/json" |
| Date | All requests | GMT timestamp |
| Content-type | All requests | Always "application/json" |
| Content-SHA256 | POST/PUT only | Base64(SHA256(request body)) |
| Authorization | All requests | api [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.