> ## Documentation Index
> Fetch the complete documentation index at: https://docs.yellow.pro/llms.txt
> Use this file to discover all available pages before exploring further.

# Signing Requests With API Keys

> Sign authenticated API requests with HMAC-SHA256 using your API key.

API key authentication lets you call authenticated endpoints from servers and scripts without the interactive wallet signing flow. Every authenticated request carries three headers, and the signature is recomputed per request from the request contents.

> [!WARNING]
>
> Your API secret is used to compute signatures and is **never sent** in a request. Never commit it to version control, log it, or expose it in client-side code. Store it in an environment variable or a secrets manager.

## Required headers

| Header | Value |
| - | - |
| `X-API-KEY` | Your API key |
| `X-TIMESTAMP` | Request time as a **Unix timestamp in seconds** |
| `X-SIGNATURE` | Hex-encoded HMAC-SHA256 signature (see below) |

## How the signature is computed

The signature is `HMAC-SHA256(secret, prehash)`, hex-encoded, where:

```
prehash = METHOD + PATH + TIMESTAMP + CANONICAL
```

| Part | Description |
| - | - |
| `METHOD` | Uppercase HTTP method, e.g. `GET`, `POST`, `DELETE` |
| `PATH` | Request path only, **without** the query string, e.g. `/perpetual/order` |
| `TIMESTAMP` | The same value sent in `X-TIMESTAMP` (Unix seconds) |
| `CANONICAL` | The canonical string built from the request parameters (below) |

### Building the canonical string

The canonical string is built from sorted parameters joined into `key=value` pairs with a `|` separator. Where the parameters come from depends on the method:

> [tab] POST / PUT / PATCH
>
> Use the **JSON request body**. Sort its top-level keys alphabetically and join them:
>
> ```
> key1=value1|key2=value2|...
> ```
>
> For a body of `{"market":"BTCUSDT","side":"buy","type":"limit","amount":"0.5","price":"35000"}`:
>
> ```
> amount=0.5|market=BTCUSDT|price=35000|side=buy|type=limit
> ```
>
> > [!NOTE]
> >
> > Send decimal values (`amount`, `price`, …) as **strings**, exactly as they appear in the body you transmit. This keeps the signed value identical to the sent value and avoids floating-point formatting differences.

> [tab] GET / DELETE
>
> Use the **query parameters**. Sort the parameter names alphabetically and join them. If a parameter appears multiple times, sort its values and join them with commas:
>
> ```
> key1=value1|key2=value2|...
> ```
>
> For `GET /perpetual/orders?market=BTCUSDT&app_session_id=your-session-id`:
>
> ```
> app_session_id=your-session-id|market=BTCUSDT
> ```
>
> A request with no query parameters has an **empty** canonical string.

### Worked example

For `POST /perpetual/order` at timestamp `1701938200` with the body above:

```
prehash   = POST/perpetual/order1701938200amount=0.5|market=BTCUSDT|price=35000|side=buy|type=limit
signature = hex( HMAC_SHA256(your_api_secret, prehash) )
```

The request then carries:

```http theme={null}
X-API-KEY: <your-api-key>
X-TIMESTAMP: 1701938200
X-SIGNATURE: <signature>
Content-Type: application/json
```

## Code examples

> [tab] Node.js
>
> ```javascript theme={null}
> const crypto = require('crypto');
>
> function buildAuthHeaders({ method, path, query = {}, body = null, apiKey, apiSecret }) {
>   const m = method.toUpperCase();
>   const timestamp = Math.floor(Date.now() / 1000).toString(); // Unix seconds
>
>   const canonical = (m === 'GET' || m === 'DELETE')
>     ? canonicalFromQuery(query)
>     : canonicalFromBody(body || {});
>
>   const prehash = m + path + timestamp + canonical;
>   const signature = crypto.createHmac('sha256', apiSecret).update(prehash).digest('hex');
>
>   return {
>     'X-API-KEY': apiKey,
>     'X-TIMESTAMP': timestamp,
>     'X-SIGNATURE': signature,
>     'Content-Type': 'application/json',
>   };
> }
>
> function canonicalFromBody(body) {
>   return Object.keys(body).sort().map((k) => `${k}=${body[k]}`).join('|');
> }
>
> function canonicalFromQuery(query) {
>   return Object.keys(query).sort().map((k) => {
>     const v = query[k];
>     const value = Array.isArray(v) ? [...v].sort().join(',') : v;
>     return `${k}=${value}`;
>   }).join('|');
> }
>
> // Example: place a perpetual order
> const body = { market: 'BTCUSDT', side: 'buy', type: 'limit', amount: '0.5', price: '35000' };
> const headers = buildAuthHeaders({
>   method: 'POST',
>   path: '/perpetual/order',
>   body,
>   apiKey: process.env.API_KEY,
>   apiSecret: process.env.API_SECRET,
> });
>
> await fetch('https://trade.api.yellow.pro/perpetual/order', {
>   method: 'POST',
>   headers,
>   body: JSON.stringify(body), // must match the body used for the signature
> });
> ```

> [tab] Python
>
> ```python theme={null}
> import hashlib
> import hmac
> import json
> import time
> import requests
>
> def build_auth_headers(method, path, *, api_key, api_secret, query=None, body=None):
>     m = method.upper()
>     timestamp = str(int(time.time()))  # Unix seconds
>
>     if m in ("GET", "DELETE"):
>         canonical = canonical_from_query(query or {})
>     else:
>         canonical = canonical_from_body(body or {})
>
>     prehash = f"{m}{path}{timestamp}{canonical}"
>     signature = hmac.new(
>         api_secret.encode(), prehash.encode(), hashlib.sha256
>     ).hexdigest()
>
>     return {
>         "X-API-KEY": api_key,
>         "X-TIMESTAMP": timestamp,
>         "X-SIGNATURE": signature,
>         "Content-Type": "application/json",
>     }
>
> def canonical_from_body(body):
>     return "|".join(f"{k}={body[k]}" for k in sorted(body))
>
> def canonical_from_query(query):
>     parts = []
>     for k in sorted(query):
>         v = query[k]
>         if isinstance(v, (list, tuple)):
>             v = ",".join(sorted(map(str, v)))
>         parts.append(f"{k}={v}")
>     return "|".join(parts)
>
> # Example: place a perpetual order
> body = {"market": "BTCUSDT", "side": "buy", "type": "limit", "amount": "0.5", "price": "35000"}
> headers = build_auth_headers("POST", "/perpetual/order", api_key=API_KEY, api_secret=API_SECRET, body=body)
>
> requests.post(
>     "https://trade.api.yellow.pro/perpetual/order",
>     headers=headers,
>     data=json.dumps(body),  # must match the body used for the signature
> )
> ```

## Common pitfalls

> [!WARNING]
>
> * **Sign the body you send.** The JSON you transmit must contain exactly the values used to build the canonical string. Re-serializing or reordering after signing will invalidate the signature.
> * **Seconds, not milliseconds.** `X-TIMESTAMP` is Unix **seconds**. Sending milliseconds will fail verification.
> * **Path only.** Exclude the query string from `PATH`; query parameters belong in the canonical string for `GET`/`DELETE`.
> * **Sort keys.** Both body keys and query keys must be sorted alphabetically before joining.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.