Market data

Use REST to load market snapshots and candle history. These authenticated reads describe a market; they do not authorize trading.

Endpoints

Method	Path	Input
`GET`	`/v1/tokens`	Required `chain` and `query`
`GET`	`/v1/markets/candles`	Required `chain`, `token`, and `interval`; optional `before`
`GET`	`/v1/markets/trades`	Required `chain` and `token`; optional `limit`
`GET`	`/v1/markets/holders`	Required `chain` and `token`; optional `limit`
`GET`	`/v1/markets/new-pairs`	Optional `chain`, `launchpad`, `query`, `sinceMinutes`, and `limit`

Use Chains and tokens to resolve the market before requesting these resources. Token snapshots include optional price, market cap, liquidity, tax, fee, and rolling-volume fields. Missing data is not zero.

Candle history and live updates

GET /v1/markets/candles

curl 'https://starswap.cc/api/v1/markets/candles?chain=solana&token=solana%3Anative&interval=1m' \
  -H "Authorization: Bearer $STARSWAP_API_KEY"

Supported intervals are 1s, 1m, 5m, 15m, 1h, 4h, 1d, and 1w. The response contains candles and hasMore. When more history is available, request an older page with before set to the oldest candle's timestamp in milliseconds. Empty history and a failed request are distinct states; do not invent candles from a spot price.

The app's live candle subscription uses /v1/markets/candles/stream. Its latest close drives both the chart and the overview price. Load fields that candles do not carry, such as rolling volume, liquidity, and recent trades, through REST. Reconcile candle history after confirmed transport reconnects; missing trade-sparse timestamp buckets are not transport gaps.

Streaming endpoints use Encore's WebSocket protocol and are not represented in the HTTP OpenAPI download. Use an Encore-compatible streaming client for those routes. A normal HTTP GET is sufficient for every REST endpoint in the table.

Protocol TVL

GET /v1/protocol/tvl is public and does not require a bearer key. It reports positionsValueUSD, the fully priced USD value of onchain token positions across active StarSwap-managed wallets. Settlement balances and vault reserves are separate measures.

Snapshots refresh about hourly. calculatedAt identifies the last complete successful scan, and refreshIntervalSeconds describes the refresh schedule. A failed scan retains the preceding snapshot. positionsValueUSD: null means that no complete snapshot is available yet; do not display it as zero.