Skip to main content
Every request to the Futuur API must be authenticated. Authentication uses HMAC-SHA512 signatures generated from your public/private key pair. There are no bearer tokens or session cookies — each request is independently signed.

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 Key header. 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 your HMAC 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 %XX for each of its UTF-8 bytes, with uppercase hex. That includes ! ' ( ) *, which JavaScript encodeURIComponent leaves 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 Python str(): Form-encoded bodies and query strings are always strings and are signed exactly as sent. If a name repeats, the last value is signed.
Send a form-encoded body, or a JSON body whose values are all strings ("price": "0.42", "shares": "3", "chain_id": "84532"). Then the signed text is the text you sent, in any language. Numeric, decimal, and boolean fields accept strings. Sign nested objects or arrays only from Python, where str() gives the server’s form. The endpoints with nested bodies are POST /orders/batch/, POST /orders/batch-update/, POST /orders/batch-cancel/, and the Safe relay endpoints.

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

On the phase-one preview host, replace the base URL with the one in Environment.

GET vs. POST requests

  • GET requests: sign the query string parameters plus Key and Timestamp.
  • POST and PATCH requests: sign the top-level body fields plus Key and Timestamp. If you also send a query string, those parameters are signed too, and they override body fields of the same name.
If your request has no parameters (for example GET /me/ or PATCH /orders/{id}/cancel/), you still sign just Key and Timestamp.

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 HMAC or Key header is missing, the request is treated as unauthenticated. Protected endpoints answer 401 with code not_authenticated.
  • After 300 failed HMAC attempts within a minute from one IP address, further attempts get 429 with code throttled until the minute ends.
See Errors for the response format and the full list of codes.
Never include your private key in client-side code or commit it to version control. Treat it with the same care as a password.