Overview
Every request to the Coinut Partner Ramp API must be cryptographically signed using HMAC-SHA256. The server verifies the signature against your API Secret stored on the Coinut side. Requests without a valid signature are rejected with401 Unauthorized or 422 Unprocessable Entity.
Required Headers
Include these four headers in every authenticated request:| Header | Required | Description |
|---|---|---|
X-API-Key | Yes | Your API key |
X-Timestamp | Yes | Unix timestamp in seconds (as string) |
X-Nonce | Yes | A unique random string per request (e.g., UUID) |
X-Signature | Yes | HMAC-SHA256 signature (lowercase hex string) |
The latest machine-readable contract also declares an
X-API-Secret security scheme, but the narrative signing instructions only require X-API-Key, X-Timestamp, X-Nonce, and X-Signature. Confirm the expected header set in sandbox before production rollout.How to Generate the Signature
Signature Generation Code Examples
Complete Authenticated Request Example
The following shows a fullGET /balance request with all headers and a sample response.
Request
Response (New API — 200 OK)
Always
SUCCESS for successful requests.List of balance objects, one per currency.
Error Responses
| Status Code | Meaning | Resolution |
|---|---|---|
422 | Invalid parameters, authentication failure, or failed operation | Verify the canonical string, headers, and request body |
401 | Possible gateway or middleware authentication failure | Handle defensively even though the latest contract primarily documents 422 |
IP Whitelisting
Restrict API access to your server IP addresses for additional security.Get Current IP Whitelist
Update IP Whitelist
| Field | Required | Description |
|---|---|---|
ipWhiteList | Yes | Array of IP addresses. Empty array [] means no restriction. |
Best Practices
Use Unique Nonces
Never reuse a nonce. Each request must have a uniqueX-Nonce value.
Correct
Incorrect
Use Timestamp in Seconds
TheX-Timestamp must be a Unix timestamp in seconds (not milliseconds or microseconds).
| Language | Expression | Output |
|---|---|---|
| JavaScript | Math.floor(Date.now() / 1000) | 1717900800 |
| Python | str(int(time.time())) | 1717900800 |
| Java | String.valueOf(Instant.now().getEpochSecond()) | 1717900800 |
Store Secrets Server-Side
| Do | Don’t |
|---|---|
Store in environment variables (process.env.API_SECRET) | Hardcode in source files |
| Use a secrets manager (AWS Secrets Manager, HashiCorp Vault) | Log to console or debug output |
| Load at runtime from secure storage | Pass in URL query parameters |
| Restrict access via IAM roles | Commit to Git repositories |
Rotate Secrets Regularly
- Generate a new key pair from the partner dashboard
- Update your server environment with the new secret
- Test the new credentials in sandbox
- Revoke the old key pair
You can have multiple active key pairs during rotation. Revoke the old key only after confirming the new one works in production.

