> ## Documentation Index
> Fetch the complete documentation index at: https://docs.centaur.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Trader events on your chart

> Load Centaur trader events into your existing Lightweight Charts or Advanced Charts integration.

Centaur hosts the integration code and loads public trader events directly into your page.
You supply your chart, licensed candles and explicit market-to-asset mapping. An enabled
[widget registration](https://docs.centaur.io/guides/overview/authentication.md#widget-id) identifies your approved origins;
its ID is public. **No Centaur API key or partner event-fetching backend is required.**

[Explore the synthetic chart](https://demo.centaur.io/chart),
[connect a public registration](https://demo.centaur.io/chart-adapter/v1/hosted-example.html), or
[download the browser example](https://demo.centaur.io/chart-adapter/v1/hosted-chart-example.tar.gz).
The synthetic chart makes no live API requests. The browser example can load real public events,
but its candles remain synthetic and clearly labelled.

## Register your page

Create a registration in [Widget settings](https://app.centaur.io/settings/widgets), enable it,
and add your website's origin. For the public connection example, also allow
`https://demo.centaur.io`. Use a real Centaur asset ID from [asset discovery](https://docs.centaur.io/integrations/find-ids.md).

The registration shares the hosted widgets' public-data policy. It does not grant access to private
traders or user-specific entitlements. Disabled registrations, revoked partner access and unapproved
origins stop event delivery. Origin restrictions do not make public data confidential.

## Lightweight Charts

Use your existing Lightweight Charts 5.2 candlestick series. The hosted integration adds avatar
markers above the candles and an accessible event selector in your details container.

```js theme={null}
import { connect } from 'https://demo.centaur.io/chart-adapter/v1/lightweight.js'

series.setData(candles)
const integration = connect({
  widgetId: 'YOUR_PUBLIC_WIDGET_REGISTRATION_ID',
  chart,
  series,
  detailsContainer: document.querySelector('#event-details'),
  assetId: centaurAssetId,
  candles,
  barDurationSeconds: 3600,
})

// When your candle window, interval or asset changes:
series.setData(nextCandles)
integration.update({
  assetId: nextCentaurAssetId,
  candles: nextCandles,
  barDurationSeconds: 3600,
})

// Optional user-triggered refresh; there is no background polling.
await integration.refresh()

// Before removing your chart:
integration.destroy()
```

Centaur owns event loading, pagination and stale-request cancellation. Your page owns the chart and
price series. Supply candles with unique ascending UTC **seconds**, valid OHLC prices and a fixed
positive bar duration. Events in session gaps or outside loaded intervals are omitted, never snapped
to the nearest candle. This interface requires fixed-duration bars; it does not infer variable-length
calendar months or exchange session boundaries. Three avatar markers appear per candle, followed by an overflow group whose
details retain the remaining actions.

## Advanced Charts

Keep your existing Advanced Charts library and market datafeed. Centaur wraps the datafeed's mark
operations while preserving candle delivery and existing partner marks. Avatars appear near the
time axis; a mark click opens the shared Centaur details panel. This uses Advanced Charts, not the
TradingView-hosted Advanced Chart widget or Trading Platform.

```js theme={null}
import { connect } from 'https://demo.centaur.io/chart-adapter/v1/advanced.js'

const integration = connect({
  widgetId: 'YOUR_PUBLIC_WIDGET_REGISTRATION_ID',
  datafeed: partnerDatafeed,
  resolveAssetId: (symbol) => centaurAssetIds[symbol.ticker] ?? null,
  detailsContainer: document.querySelector('#event-details'),
})

const widget = new TradingView.widget({
  ...chartOptions,
  datafeed: integration.datafeed,
})
widget.onChartReady(() => integration.bind(widget))

// On a refresh action:
integration.refresh()

// Before widget.remove():
integration.destroy()
```

Return `null` from `resolveAssetId` when your symbol has no explicit Centaur asset mapping. The
integration must be installed before creating the chart. Do not replace the partner datafeed with
a Centaur-only candle provider. Centaur does not supply or redistribute the Advanced Charts library.
Use your approved TradingView distribution and retain its required attribution.

Advanced Charts `refresh()` asks the chart to reload its marks. Use `onState` to observe completion;
Lightweight Charts `refresh()` also returns a promise for the load.

V1 supports time-based charts for **24x7 markets**, including calendar intervals, and **intraday
intervals for session-based markets**. For session-based daily, weekly or monthly charts, it shows
an explicit unsupported-interval message and asks the user to choose an intraday interval. It does
not guess which session a calendar label represents. Non-time-based charts, such as Renko, Kagi,
Point and Figure, and range charts, are unsupported. The partner's chart and marks remain available.

Displayed bar boundaries come from Advanced Charts, including intervals it rebuilds from smaller
candles. The wrapper does not treat raw input-candle timestamps as the final displayed bars.

## Loading and event details

Both integrations load on initial display and relevant chart changes. `refresh()` requests a fresh
window explicitly. They do not poll in the background. `destroy()` cancels Centaur work, removes its
listeners and details, and preserves the partner chart. For Advanced Charts, it also stops contributing
Centaur marks while retaining the partner's marks.

Optional `onState` reports `{ status: 'loading' | 'ready' | 'error', message?, appliedTimeRange? }`.
Loading, access errors and incomplete windows are visible in the details area. A failed or incomplete
request is not reported as a successful empty chart. For a dense window, narrow the visible range.

The hosted endpoint returns public events with trader names, avatars and permitted source links.
Missing avatars use initials. A missing source link is valid because signal visibility does not grant
message visibility. Source text and media are not inserted into chart tooltips.

System-generated events are hidden. Other assumed actions remain visible and are labelled as inferred;
retrospective actions are labelled separately. Missing event prices stay unavailable.

## Market and history boundaries

Map the canonical Centaur asset ID to your venue, market and quote explicitly. Public symbols are
changeable display labels. **Centaur event prices are not executions on your venue.** The public quote
symbol describes the asset's preferred market, not historical execution provenance. Markers represent
semantic event time; their position does not imply a price conversion or an execution.

The integration keeps your chart and candles unchanged, including when you display a longer history.
Within the visible loaded range, it requests at most the latest **90 days**, with the end no later
than now. The server may narrow this further to its current public-retention window. The details
panel explicitly shows **Event coverage: start to end**, using the returned `appliedTimeRange`, so
older candles are not mistaken for covered event history.

The endpoint rejects requests spanning more than 90 days. The integration follows up to ten pages;
if more remain, it shows an incomplete-window error asking for a smaller range rather than silently
truncating events. `/feed` is not used as a historical event source. Unsupported chart configurations
must not be interpreted as a successful empty result.

## Hosting, staging and version pinning

The two ESM files are independent of the hosted widgets SDK. Their Centaur URLs allow cross-origin
module loading. Allow the module host in your page's script policy and the API host in its connection
policy. Avatars also need your page's image policy to permit their returned URLs.

Production modules use `https://api.centaur.io` by default. For an authorized staging integration,
use `https://demo.preview.centaur.io/chart-adapter/v1/` and explicitly set
`apiOrigin: 'https://api.preview.centaur.io'`. Preview protection still applies.

The custom-domain V1 URLs track compatible releases. For a fixed version, use the exact retained,
publicly accessible Vercel deployment URL from that release's evidence, preserving the same file path.
Do not attach a fixed integrity hash to a moving V1 URL. A deployment URL is usable only while that
deployment remains retained and accessible. Centaur can roll back the demo deployment to restore its
hosted modules; partners control which pinned deployment they load.

## Existing manual-data integrations

The original [`adapter.js`](https://demo.centaur.io/chart-adapter/v1/adapter.js) and
[backend example](https://demo.centaur.io/chart-adapter/v1/partner-chart-example.tar.gz) remain available
for integrations that supply already-hydrated events themselves. That older `mount` API does not
fetch events. Its backend requires an API key; the hosted `connect` integrations above do not.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.