Skip to main content
Run a small Next.js app that shows a Centaur feed, first with sample data and then with live data. Its request code is plain TypeScript, so you can move it into any backend later.

​
1. Run the starter app with sample data

You need Node.js 24 and npm. You do not need an account.
Open http://localhost:3000. You see three fictional posts under a Sample data label. Choose an asset or select Refresh to read the feed again.

​
2. Switch to live data

  1. Create an API key in API key settings. You need an active Centaur account with a verified email; see Get access. New keys include the feed.read scope this app needs.
  2. Copy .env.example to .env.local.
  3. In .env.local, set CENTAUR_DATA_MODE=live and set CENTAUR_API_KEY to your key.
  4. Restart npm run dev.
The label changes to Live API mode and recent activity loads. If the key is missing or lacks feed.read, the page shows an error. It never falls back to sample data.
Keep the API key on your server. Never put it in a NEXT_PUBLIC_ variable or browser code. Anyone who can reach a public deployment of this app spends the key’s quota.

​
3. Make it yours

​
Call the API directly

Every request goes to https://api.centaur.io/v2 with your key in the x-api-key header. Set the key in your terminal first:
The examples repository also has TypeScript recipes that run on Node.js 24 with no installation. They use the same parameter names as REST.

​
Read and filter the feed

Omit assetIds for the general feed. Add traderIds=42 to narrow to a trader. Different filters intersect. An empty results array means no matching activity. Look up IDs once during setup with Find IDs, not before every read.
The `assetClass` filter is not available in production yet. Do not rely on it until this note is removed.
Once it is available, add assetClass=crypto or a comma-separated list of supported classes. It works alongside asset and trader filters.

​
Read the next page

Copy meta.nextCursor from the previous response and keep the same filters:
Stop when meta.hasMore is false. Do not read or change the cursor. To poll for new activity instead, see Partner feed.

​
Read asset positioning

`GET /v2/assets/positioning` is pending release. Use it only after it is available in your environment.
This read needs the stats.read scope.
A snapshot with zero positions is valid data. An asset listed in meta.missingAssetIds is unavailable.

​
Handle errors

Run curl with --include --fail-with-body to see the HTTP status, headers, and error body. In the TypeScript recipes, catch CentaurApiError to read status, code, requestId, and retryAfter. Network failures and timeouts keep their native errors. The client does not retry on its own.
  • 401 or 403: check the key and its scopes.
  • 422: check your parameters.
  • 429 or a temporary failure: wait for Retry-After, then retry.
Keep upstream error details on your server and show visitors a safe message. Errors and limits lists every status.

​
Next steps

  • Data reads: every read, its scope, and which one answers which question.
  • Partner feed: pagination, polling for changes, and freshness.
  • Webhooks: receive new activity instead of polling.
  • API reference: every endpoint, parameter, and field.
Last modified on October 22, 2026