Get your API keys
Get a public/private HMAC pair from Settings → API keys, or derive the same pair by signing with your wallet (phase-one preview host only). Full steps and the wallet-derive payload are in Get your API keys.- Public key — included in every request as the
Keyheader. Safe to log. - Private key — used to sign requests. Never share or log this value.
On the phase-one preview host, HMAC authenticates the HTTP request and nothing else. Every order in
OOM or USDC also needs an EIP-712 LimitOrderIntent signed by your Safe owner key. HMAC never replaces that wallet signature. See Environment and On-chain trading.Required headers
Every authenticated request must include these three headers:Signing process
The server rebuilds one string from your request and compares its HMAC-SHA512 with yourHMAC header. The method and the path are not signed. Only the parameters, Key, and Timestamp are.
1
Collect the parameters
Start with the top-level fields of the request body (a JSON object or form fields). Add the query string parameters; on a duplicate name the query string value wins. Then add
Key (your public key) and Timestamp (the exact string you send in the header). A request with no body and no query string signs only Key and Timestamp.2
Sort by name (case-sensitive)
Sort by parameter name in code-point order, the order Python’s
sorted() produces. Uppercase letters sort before lowercase, so Key and Timestamp come before category. A case-insensitive or locale-aware comparator (for example JavaScript localeCompare) produces a different string.3
Encode exactly like Python urlencode
Join the pairs as
name=value&name=value. Convert each name and value to text, then percent-encode it with the rules of Python urllib.parse.urlencode (quote_plus):- Letters, digits, and
_ . - ~stay as they are. - A space becomes
+, not%20. - Every other character becomes
%XXfor each of its UTF-8 bytes, with uppercase hex. That includes! ' ( ) *, which JavaScriptencodeURIComponentleaves unescaped.
4
Sign with your private key
Compute an HMAC-SHA512 digest using your private key as the secret and the string as the message. Send the hex digest (not base64) in the
HMAC header.How values become text
The server signs what it parsed, not the bytes you sent. For a JSON body, each top-level value is converted with Pythonstr():
Form-encoded bodies and query strings are always strings and are signed exactly as sent. If a name repeats, the last value is signed.
Timestamp window
Timestamp must be an integer Unix time in seconds, within 300 seconds of the server clock in either direction. Keep your clock synchronized (NTP) and sign every request fresh.
Code examples
GET vs. POST requests
- GET requests: sign the query string parameters plus
KeyandTimestamp. - POST and PATCH requests: sign the top-level body fields plus
KeyandTimestamp. If you also send a query string, those parameters are signed too, and they override body fields of the same name.
Errors
Every HMAC failure returns the same status and code. The API does not tell you which check failed.401 Unauthorized
Two cases look different:
- If the
HMACorKeyheader is missing, the request is treated as unauthenticated. Protected endpoints answer401with codenot_authenticated. - After 300 failed HMAC attempts within a minute from one IP address, further attempts get
429with codethrottleduntil the minute ends.