# Stratex API — Quickstart

Get from signup to your first backtest and setup with webhook in a few steps.

---

## 1. Sign up and log in

1. Go to the **signup** page (linked from the [landing page](/landing.html)).
2. Create an account (email, password; company name optional).
3. Log in. You’ll land on the main dashboard.

---

## 2. Create an API key

1. Open **API & Account** (or Account Dashboard) from the main page or settings.
2. Click **Create API key**.
3. Give it a name (e.g. `My Agent`) and choose permissions: **backtest** and/or **alerts**.
4. Copy the **raw key** and store it securely. It is shown only once.

Use the key on every API request:

- **Header (preferred):** `Authorization: Bearer <your-api-key>`
- **Alternative:** `X-Api-Key: <your-api-key>`

---

## 3. Discover available markets

Before running a backtest, list markets that actually have ingested data (human labels and date ranges from the catalog — not a fixed count):

```bash
curl https://your-api-host/api/v1/markets \
  -H "Authorization: Bearer YOUR_API_KEY"
```

Use the `market` key (and ranges/timeframes) from the response when estimating or running a backtest. Auth is required.

---

## 4. Run your first backtest

1. **Create a setup** (required for backtesting):

   ```bash
   curl -X POST https://your-api-host/api/v1/service/setups \
     -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "name": "Quickstart GOLD BUY",
       "symbol": "GOLD",
       "direction": "BUY",
       "timeframe": "5m"
     }'
   ```

   From the response, note **`setupId`**.

2. **Run a backtest** with that setup:

   ```bash
   curl -X POST https://your-api-host/api/v1/backtest/run \
     -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "setupId": "PASTE_SETUP_ID_HERE",
       "symbol": "GOLD",
       "timeframe": "5m",
       "startDate": "2024-01-01",
       "endDate": "2024-01-31"
     }'
   ```

   The response includes the run result, full trade list, summary, and **`runId`** (or `id`) so you can fetch details later with `GET /api/v1/backtest/:id`.

3. **Optional:** Add `"includeChartImage": true` to the run body to receive a base64 summary chart in the response.

---

## 5. Create a setup with webhook (alerts)

To receive live triggers via **webhook**:

1. When creating the setup, add **`webhookUrl`** (and optionally **`webhookSecret`** for signature verification):

   ```json
   {
     "name": "GOLD 5m alert",
     "symbol": "GOLD",
     "direction": "BUY",
     "timeframe": "5m",
     "webhookUrl": "https://your-server.com/webhooks/stratex",
     "webhookSecret": "your-optional-secret"
   }
   ```

2. When the setup triggers, the service POSTs a minimal JSON payload to `webhookUrl`. If you set `webhookSecret`, verify the request using the `X-Webhook-Signature: sha256=<hex>` header (HMAC-SHA256 of the body).

3. **Change webhook URL or secret later** without recreating the setup:

   ```bash
   curl -X PATCH https://your-api-host/api/v1/service/setups/PASTE_SETUP_ID_HERE \
     -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"webhookUrl":"https://your-new-endpoint.example/hook","webhookSecret":"new-secret"}'
   ```

   Send only the fields you want to change. Use `"webhookUrl":""` or `null` to clear the URL (fall back to polling). For any change other than these two fields, **create a new setup**.

**Alternative — polling:** If you don’t set a webhook, call **`GET /api/v1/alerts/pending`** (with optional `?since=<iso8601>`) to fetch pending triggers. Each call marks returned alerts as delivered.

---

## 6. Check usage and billing

- **Usage:** `GET /api/v1/usage` (with your API key) returns current billing period usage: bars processed (backtest) and setup evaluations by timeframe.
- **Billing:** From the Account Dashboard, use **Manage billing** to open the Stripe Customer Portal (subscription, payment methods).

---

## Next steps

- **[API Reference](/docs/api-reference.md)** — All endpoints, request/response shapes, error codes.
- **[Agent Skill](/docs/agent-skill.md)** — Workflow, structured setup schema, webhook vs polling, error handling.
- **Discovery:** `GET /api/v1/agent-info` (no auth) for capabilities, pricing, doc URLs, and `marketsUrl`. Markets **data** requires auth: `GET /api/v1/markets`.