# Quick Tutorial

Learn how to authenticate, sign, and send your first trading order using the Flipster API — all within five minutes.

### Step 1. Get Your API Key

Before making any private requests, generate an API key from [your Flipster account page](https://flipster.io/user/account/api-management). Each key contains a public key (api-key) and a secret key (used for HMAC signing). 

### Step 2. Set Up Authentication

Every private request must be signed using HMAC-based authentication. Include the following headers in each request:

```
api-key: <your_api_key>
api-expires: <unix_timestamp_of_expiration>
api-signature: <HMAC_SHA256_signature>
```

**Generating an API Signature**

{% tabs %}
{% tab title="Python" %}

```python
import hmac
import hashlib
from urllib.parse import urlparse

def generate_api_key_signature(
    secret: str,
    method: str,
    url: str,
    expires: int,
    data: bytes | None = None,
) -> str:
    """
    Generate an HMAC-SHA256 signature for Flipster API requests.

    Args:
        secret: Your API secret key.
        method: HTTP method (e.g., 'POST', 'GET').
        url: Full request URL including query parameters.
        expires: Unix timestamp (in seconds) when the request expires.
        data: Optional request payload as bytes.

    Returns:
        Hex-encoded HMAC-SHA256 signature string.
    """

    # 1. Normalize URL path and query string
    parsed = urlparse(url)
    path = parsed.path + (f"?{parsed.query}" if parsed.query else "")

    # 2. Build message: method + path + expires + (optional body)
    parts = [
        method.upper().encode("utf-8"),
        path.encode("utf-8"),
        str(expires).encode("utf-8"),
    ]
    if data:
        parts.append(data)
    message = b"".join(parts)

    # 3. Compute HMAC-SHA256 signature
    signature = hmac.new(
        secret.encode("utf-8"),
        message,
        digestmod=hashlib.sha256
    ).hexdigest()

    return signature
```

{% endtab %}

{% tab title="Javascript" %}

```javascript
function generateApiKeySignature(secret, verb, url, expires, data) {
 
    let urlStr = typeof url === 'string' ? url : url.toString();
    const urlObj = new URL(urlStr);
    let path = urlObj.pathname;
    if (urlObj.search) {
        path = path + urlObj.search;
    }

    // Construct message string: method + path + expires + payload
    // This matches Python's b''.join([method_bytes, path_bytes, expires_bytes, data])
    let messageStr = verb + path + String(expires);
    if (data !== null && data !== undefined) {
        messageStr = messageStr + data;
    }

    // Convert to bytes (UTF-8) and generate HMAC-SHA256 signature
    // CryptoJS.HmacSHA256 expects string and automatically handles UTF-8 encoding
    const signature = CryptoJS.HmacSHA256(messageStr, secret);
    
    // Debug logging
    console.log('Signature generation:');
    console.log('  Method:', verb);
    console.log('  Path:', path);
    console.log('  Expires:', expires);
    console.log('  Body:', data ? (data.length > 100 ? data.substring(0, 100) + '...' : data) : 'null');
    console.log('  Message string length:', messageStr.length);
    console.log('  Signature:', signature.toString());
    
    return CryptoJS.enc.Hex.stringify(signature);
}
```

{% endtab %}
{% endtabs %}

### Step 3. Send a Sample Order

Use the /api/v1/trade/order endpoint to place a market order.

Here’s an example using curl:

```
curl -X POST "https://<host>/api/v1/trade/order" \
  -H "Content-Type: application/json" \
  -H "api-key: <your_api_key (starts with 3|)>" \
  -H "api-expires: <unix_timestamp_of_expiration>" \
  -H "api-signature: <HMAC_SHA256_signature>" \
  -d '{
    "symbol": "BTCUSDT.PERP",
    "side": "BUY",
    "type": "MARKET",
    "quantity": "0.01"
  }'
```

### That’s it!

In just a few minutes, you’ve:

* Created an API key
* Signed your request with HMAC
* Placed and verified your first order

You’re now ready to build automated trading workflows with Flipster’s API.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://api-docs.flipster.io/quick-tutorial.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.