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

# Quickstart

> Create a user and give them their first stock.

You'll need your Stockly **API key**. Send it as the `x-api-key` header on every request.
Replace `https://api.stockly.com` below with your Stockly API base URL.

## 1. Create a user

Provide an `email`, your own `externalId`, or both.

<CodeGroup>
  ```bash cURL theme={null}
  curl -s -X POST https://api.stockly.com/v1/users \
    -H "content-type: application/json" \
    -H "x-api-key: $STOCKLY_API_KEY" \
    -d '{ "email": "jane@example.com", "externalId": "acme-user-42" }'
  ```

  ```ts TypeScript theme={null}
  const res = await fetch("https://api.stockly.com/v1/users", {
    method: "POST",
    headers: {
      "content-type": "application/json",
      "x-api-key": process.env.STOCKLY_API_KEY!,
    },
    body: JSON.stringify({ email: "jane@example.com", externalId: "acme-user-42" }),
  });
  const { user } = await res.json();
  ```
</CodeGroup>

Keep the `user.id` — you'll reference it when giving stock and reading the portfolio.

## 2. Give stock

Give a user \$1 of Apple. Pick `assetSymbol` from the catalog (`GET /v1/assets`) and generate
a fresh `idempotencyKey` per award (a UUID works well).

<CodeGroup>
  ```bash cURL theme={null}
  curl -s -X POST https://api.stockly.com/v1/rewards \
    -H "content-type: application/json" \
    -H "x-api-key: $STOCKLY_API_KEY" \
    -d '{
      "userId": "6f1d2a3b-7c8d-4e9f-a0b1-c2d3e4f5a6b7",
      "idempotencyKey": "order-1001-reward",
      "amountUsd": 1,
      "assetSymbol": "AAPL",
      "source": "cashback"
    }'
  ```

  ```ts TypeScript theme={null}
  const res = await fetch("https://api.stockly.com/v1/rewards", {
    method: "POST",
    headers: {
      "content-type": "application/json",
      "x-api-key": process.env.STOCKLY_API_KEY!,
    },
    body: JSON.stringify({
      userId: "6f1d2a3b-7c8d-4e9f-a0b1-c2d3e4f5a6b7",
      idempotencyKey: crypto.randomUUID(),
      amountUsd: 1,
      assetSymbol: "AAPL",
      source: "cashback",
    }),
  });
  const { reward } = await res.json();
  ```
</CodeGroup>

The award comes back with status `recorded`. Stockly then fulfills it and the stock appears
in the user's portfolio (status `executed`).

## 3. Read the portfolio

Read the user's holdings, live value, and return any time:

```bash cURL theme={null}
curl -s https://api.stockly.com/v1/users/6f1d2a3b-7c8d-4e9f-a0b1-c2d3e4f5a6b7/portfolio \
  -H "x-api-key: $STOCKLY_API_KEY"
```

```json Response theme={null}
{
  "value": 1.02,
  "costBasis": 1.0,
  "change": "+2.0%",
  "holdings": [
    { "asset": "AAPL", "quantity": 0.0034, "value": 1.02, "costBasis": 1.0, "change": "+2.0%" }
  ]
}
```

<Check>
  That's it — you created a user, gave them stock, and read their portfolio. Open the
  **API Reference** tab for every endpoint, field, and an interactive playground.
</Check>