Concepts
User
One of your customers. Create them, then give them stock and read their portfolio.
Stock award
Stock you give a user (e.g. “$1 of AAPL”). Recorded instantly, then fulfilled — read it
back any time to see its status.
Portfolio
A user’s holdings and their live value, including return versus what you’ve given —
GET /v1/users/{userId}/portfolio.Catalog
The stocks you can give —
GET /v1/assets.How it works
1
Create a user
POST /v1/users with an email or your own externalId.2
Give stock
POST /v1/rewards with the user, an amount in USD, and a stock symbol from the
catalog. The award is recorded instantly.3
Stockly fulfills it
Stockly buys the fractional stock and adds it to the user’s portfolio. The award’s
status moves to executed.4
Read the portfolio
GET /v1/users/{userId}/portfolio any time for the user’s holdings, live value, and
return.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-idheader, echoed in error bodies, for support and correlation.