Skip to main content

DeFi Authorization

To ensure the security and integrity of data, Changelly DeFi API uses a Key-Pair Authentication mechanism. Instead of transmitting sensitive passwords or secret keys directly, every request must be cryptographically signed using a digital signature.

Authorization headers​

All requests to Changelly DeFi API must include the following custom headers:

HeaderDescriptionPurpose
x-api-keyBase64-encoded SHA-256 hash of your Public Key.Client Identification: Identifies which partner is making the request.
x-api-signatureAn RSA digital signature of the request payload.Integrity: Ensures the request hasn't been tampered with.
x-api-timestampThe current time in Unix Timestamp format.Freshness: Prevents the processing of outdated POST requests.
x-api-nonceA unique, random string (UUID) for each POST request.Replay Protection: Ensures a specific request is only processed once.

Signature generation​

The value in the x-api-signature header is generated using the RSASSA-PKCS1-v1_5 algorithm with a SHA-256 hash. To create a valid signature, follow these steps:

Construct the payload​

Create a raw string by concatenating the following components using a colon : as a delimiter HTTP_METHOD:PATH:QUERY_PARAMS:REQUEST_BODY.

Normalization rules​

To ensure the server generates an identical hash, you must normalize your data:

  • Query Parameters: Sort parameters alphabetically by key.
  • Request Body: If a JSON body exists, it must be serialized with sorted keys and consistent spacing (no extra whitespace unless part of the data).
  • Empty Values: If there are no query parameters or no body, use an empty string for that segment.

Signing​

Sign the resulting string using your Private Key. The server will use your stored Public Key to verify that the signature matches the data received. If any part of the request was modified in transit, the signature will be invalid.

Additional security mechanisms​

Timestamp validation​

The x-api-timestamp header prevents attackers from capturing a valid POST request and sending it later. The server compares the provided timestamp with its current system time.

  • Threshold: Requests older than 1 hour will be rejected.
  • Error: Timestamp is too old.

Replay attack protection​

The x-api-nonce is a unique identifier for a single POST request. The server stores all used nonces in a cache (Redis) for the duration of the timestamp's validity.

  • Validation: If the server receives a request with a nonce that has already been used, the request is rejected.
  • Error: Nonce reuse.

DeFi Key pair generation

To generate the Private key (secret) and Public key pair, please use the scripts provided on this page.

warning

Keep your private key in a safe place and don't share it with anyone, not even us.

You need to share with us only your:

  • Public key;
  • API key Base64.