Quickstart - Stockly

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.

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" }'

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();

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

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"
  }'

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();

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:

cURL

curl -s https://api.stockly.com/v1/users/6f1d2a3b-7c8d-4e9f-a0b1-c2d3e4f5a6b7/portfolio \
  -H "x-api-key: $STOCKLY_API_KEY"

Response

{
  "value": 1.02,
  "costBasis": 1.0,
  "change": "+2.0%",
  "holdings": [
    { "asset": "AAPL", "quantity": 0.0034, "value": 1.02, "costBasis": 1.0, "change": "+2.0%" }
  ]
}

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.

​1. Create a user

​2. Give stock

​3. Read the portfolio

1. Create a user

2. Give stock

3. Read the portfolio