Skip to main content

​
Generating an API Key

To generate an API Key
  1. Sign into your account with a web browser
  2. Click on your address in the upper right corner
  3. Click “API Keys”
  4. Click Add New API Key
  5. Name the key
  6. Select the correct permissions
  7. Click “Create API Key”
  8. Record the secret key
Important: The secret key should be treated the same way as a password and not stored in an unencrypted manner. Please place this information in a password manager or key vault.

​
IP Whitelisting

It is strongly recommended to whitelist the IP addresses which are allowed to make requests for the given API key. Up to 16 IP addresses can be added per API key. Only IPv4 addresses are supported at this time. The default state with no whitelisted addresses (empty whitelist) is to allow requests from any IP. If there are addresses on the whitelist, then only requests from the whitelisted IPs are allowed. Requests from IPs not on the whitelist will error with code 401 and message: "IP addr x.x.x.x is not allowed for key ondoKeyId_yyyyyyyy".

​
Making an authenticated REST request

Authenticated REST requests need the following headers:
  • ONDO-KEY-ID The key id (including the “ondoKeyId_” prefix)
  • ONDO-TIMESTAMP Number of milliseconds since the Unix epoch, this must be within 30 seconds of the time the request is received.
  • ONDO-SIGN hex representation of SHA256 HMAC of the following four strings concatenated together using the API Secret (including the “ondoApiSecret_” prefix).
    • timestamp identical to the ONDO-TIMESTAMP header
    • method HTTP method in uppercase
    • requestPath full path and query parameters of the URL, excluding the hostname
    • body request body string

​
Error Codes

Requests made through API key authentication can fail with the following error codes:
  • api_key_not_found — The API key provided could not be found.
  • failed_to_parse_timestamp — The timestamp provided could not be parsed.
  • timestamp_too_far — The timestamp is too far from the server timestamp (more than 30 seconds in the past or future)
  • failed_to_decode_hex_signature — The hex signature could not be decoded.
  • signature_mismatch — There is a mismatch in the signature.
  • key_doesnt_have_scope — The API key does not have the required scope for the endpoint.
  • ip_not_permitted — The IP address making the request is not whitelisted for this API key.

​
Example in Go

package main
import (
  "crypto/hmac"
  "crypto/sha256"
  "encoding/hex"
  "fmt"
  "io"
  "net/http"
  "strings"
  "time"
)
func main() {
  keyId := "ondoKeyId_KEYID"
  apiSecret := "ondoApiSecret_SECRET"
  method := "GET"
  base := "https://api.ondoperps.xyz"
  path := "/v1/perps/orders?market=AAPL-USD.P&limit=1000"
  body := ""
  req, _ := http.NewRequest(method, base+path, strings.NewReader(body))
  timestamp := fmt.Sprintf("%d", time.Now().UnixMilli())
  // Ensure path contains query params `?market=AVAX-USDC&limit=1000`.
  concattedString := timestamp + method + path + body
  mac := hmac.New(sha256.New, []byte(apiSecret))
  mac.Write([]byte(concattedString))
  sig := mac.Sum(nil)
  req.Header.Set("ONDO-KEY-ID", keyId)
  req.Header.Set("ONDO-TIMESTAMP", timestamp)
  req.Header.Set("ONDO-SIGN", hex.EncodeToString(sig))
  res, err := http.DefaultClient.Do(req)
  if err != nil {
    fmt.Printf("http err: %s", err)
    return
  }
  data, _ := io.ReadAll(res.Body)
  fmt.Printf("Status: %s, Body: %s", res.Status, data)
}
Note: in Go, req.URL.RequestURI() contains the query parameters and should be used, whereas req.URL.Path does not.

​
Example in Python

import hmac
import hashlib
import time
import requests

key_id = "ondoKeyId_KEYID"
api_secret = "ondoApiSecret_SECRET"
method = "GET"
base = "https://api.ondoperps.xyz"
path = "/v1/perps/orders?market=AAPL-USD.P&limit=1000"
body = ""

url = base + path
timestamp = str(int(time.time() * 1000))
# Ensure path contains query params `?market=AAPL-USD.P&limit=1000`
concatted_string = timestamp + method + path + body
mac = hmac.new(api_secret.encode(), concatted_string.encode(), hashlib.sha256)
signature = mac.hexdigest()

headers = {
    "ONDO-KEY-ID": key_id,
    "ONDO-TIMESTAMP": timestamp,
    "ONDO-SIGN": signature
}

response = requests.get(url, headers=headers)

print(f"Status: {response.status_code}, Body: {response.text}")