Skip to main content

​
Generate Request Signature

Orderly uses the ed25519 elliptic curve standard for request authentication via signature verification.
1

Orderly Account ID

Register your account and obtain your account ID. The registration steps are provided here. Add your account ID to the request header as orderly-account-id.
2

Orderly Key

Add your Orderly public key to the request header as orderly-key. To generate and add a new Orderly key, see the documentation. You can also obtain Orderly keys from frontend builders like WOOFi Pro.
3

Timestamp

Take the current timestamp in milliseconds and add it as orderly-timestamp to the request header.
4

Normalize request content

Normalize the message to a string by concatenating the following:
  1. Current timestamp in milliseconds, e.g. 1649920583000
  2. HTTP method in uppercase, e.g. POST
  3. Request path including query parameters (without base URL), e.g. /v1/orders?symbol=PERP_BTC_USDC
  4. (Optional) If the request has a body, JSON stringify it and append
Example result:
1649920583000POST/v1/order{"symbol": "PERP_ETH_USDC", "order_type": "LIMIT", "order_price": 1521.03, "order_quantity": 2.11, "side": "BUY"}
5

Generate signature

Sign the normalized content using the ed25519 algorithm, encode the signature in base64 url-safe format, and add the result to the request header as orderly-signature.
6

Content type

Set the Content-Type header:
  • GET and DELETE: application/x-www-form-urlencoded
  • POST and PUT: application/json
7

Send the request

The final request should have the following headers:
HeaderDescription
Content-TypeRequest content type
orderly-account-idYour Orderly account ID
orderly-keyYour Orderly public key
orderly-signatureed25519 signature (base64url)
orderly-timestampRequest timestamp (ms)
The Orderly key should be used without the ed25519: prefix when used in code samples below.

​
Full Example

import io.github.cdimascio.dotenv.Dotenv;
import net.i2p.crypto.eddsa.EdDSAPrivateKey;
import net.i2p.crypto.eddsa.spec.EdDSANamedCurveTable;
import net.i2p.crypto.eddsa.spec.EdDSAParameterSpec;
import net.i2p.crypto.eddsa.spec.EdDSAPrivateKeySpec;
import okhttp3.OkHttpClient;
import okhttp3.Request;
import okhttp3.Response;

import org.bitcoinj.base.Base58;
import org.json.JSONObject;

public class AuthenticationExample {
public static void main(String[] args) throws Exception {
String baseUrl = "https://testnet-api.orderly.org";
String orderlyAccountId = "<orderly-account-id>";

      Dotenv dotenv = Dotenv.load();
      OkHttpClient client = new OkHttpClient();

      String key = dotenv.get("ORDERLY_SECRET");
      EdDSAParameterSpec spec = EdDSANamedCurveTable.getByName(EdDSANamedCurveTable.ED_25519);
      EdDSAPrivateKeySpec encoded = new EdDSAPrivateKeySpec(Base58.decode(key), spec);
      EdDSAPrivateKey orderlyKey = new EdDSAPrivateKey(encoded);

      Signer signer = new Signer(baseUrl, orderlyAccountId, orderlyKey);

      JSONObject json = new JSONObject();
      json.put("symbol", "PERP_ETH_USDC");
      json.put("order_type", "MARKET");
      json.put("order_quantity", 0.01);
      json.put("side", "BUY");
      Request req = signer.createSignedRequest("/v1/order", "POST", json);
      String res;
      try (Response response = client.newCall(req).execute()) {
         res = response.body().string();
      }
      JSONObject obj = new JSONObject(res);

}
}

​
Security

Orderly validates every request through three checks. A request must pass all three to be accepted.

​
Request Timestamp

The request is rejected if the orderly-timestamp header differs from the API server time by more than 300 seconds.

​
Signature Verification

The orderly-signature header must be a valid ed25519 signature generated from the normalized request content and signed with your Orderly secret key.

​
Orderly Key Validity

The orderly-key header must reference a key that has been added to the network, is associated with the account, and has not expired.