> ## 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.

# Introduction

> Reward your users with fractional stock, in a few API calls.

Stockly lets you reward your customers with fractional stock. You create a user, give them
stock, and read their portfolio — Stockly handles buying the stock and holding it for the
user behind the scenes.

## Concepts

<CardGroup cols={2}>
  <Card title="User" icon="user">
    One of your customers. Create them, then give them stock and read their portfolio.
  </Card>

  <Card title="Stock award" icon="gift">
    Stock you give a user (e.g. "\$1 of AAPL"). Recorded instantly, then fulfilled — read it
    back any time to see its status.
  </Card>

  <Card title="Portfolio" icon="chart-line">
    A user's holdings and their live value, including return versus what you've given —
    `GET /v1/users/{userId}/portfolio`.
  </Card>

  <Card title="Catalog" icon="layer-group">
    The stocks you can give — `GET /v1/assets`.
  </Card>
</CardGroup>

## How it works

<Steps>
  <Step title="Create a user">
    `POST /v1/users` with an email or your own `externalId`.
  </Step>

  <Step title="Give stock">
    `POST /v1/rewards` with the user, an amount in USD, and a stock symbol from the
    [catalog](#what-you-can-give). The award is recorded instantly.
  </Step>

  <Step title="Stockly fulfills it">
    Stockly buys the fractional stock and adds it to the user's portfolio. The award's
    `status` moves to `executed`.
  </Step>

  <Step title="Read the portfolio">
    `GET /v1/users/{userId}/portfolio` any time for the user's holdings, live value, and
    return.
  </Step>
</Steps>

## What you can give

Give any stock in the catalog — `GET /v1/assets`. Use the `symbol` from the catalog as
`assetSymbol` when giving stock.

## Conventions

* **Base URL** — your Stockly API base URL, e.g. `https://api.stockly.com`. All endpoints live under `/v1`.
* **JSON** — all request and response bodies are JSON.
* **IDs** are UUIDs; **timestamps** are ISO 8601 UTC.
* **Request IDs** — every response includes an `x-request-id` header, echoed in error bodies, for support and correlation.

Ready? Head to the [Quickstart](/quickstart).