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

# Embed a widget

> Add a Centaur feed or asset-positioning widget to your page, first with sample data, then live.

> [!NOTE]
>
> Widgets are in early access. Sample mode is open to everyone. Live mode is enabled for approved partners in stages.

Try a widget with sample data first. No account needed.

## 1. Try it with sample data

Pick a widget and an asset. The preview uses fictional traders and posts.

Select **Copy code** and paste it into any HTML page. The widget shows a **Sample data** label. After a few seconds, a **1 new post** button appears, as it would for a live feed.

## 2. Get a widget ID

A widget ID tells Centaur which sites may show live data. It is public, so it is safe in your page source.

1. Sign in to [Widget settings](https://app.centaur.io/settings/widgets). If **New widget ID** is greyed out, [get partner access](/guides/overview/authentication.md#get-a-partner-account) first.
2. Select **New widget ID** and name it, such as `Production site`.
3. Add each site that will show the widget, such as `https://example.com`. See [Allowed sites](#allowed-sites).
4. Leave **Live** on, select **Create**, and copy the widget ID.

## 3. Switch to live data

In the builder, select **Live**, paste your widget ID, and copy the code. Replace the sample code and open the page from an allowed site. The **Sample data** label goes away and real activity loads.

One widget ID works for any number of widgets on the same sites.

## Before you publish

* [ ] Every site that shows the widget is in the widget ID's [allowed sites](#allowed-sites).
* [ ] If your site sets a [content security policy](#content-security-policy), it allows the hosts below.
* [ ] The live widget loads from an allowed site with no errors in the browser console.
* [ ] Your app calls `destroy()` when it removes the widget. See [Widget recipes](/integrations/widget-recipes.md).
* [ ] The Centaur attribution is visible. Do not crop or cover the widget.

### Allowed sites

Centaur serves live data only to pages whose origin is in the widget ID's allowed sites. An origin is the scheme, host, and port, such as `https://example.com`. A widget ID with no allowed sites serves no live data.

| You add | It matches | It does not match |
| - | - | - |
| `https://example.com` | `https://example.com` | `https://www.example.com`, `http://example.com` |
| `https://*.example.com` | `https://www.example.com`, `https://a.b.example.com` | `https://example.com` |
| `http://localhost:3000` | `http://localhost:3000` | `http://localhost:5173` |

* Use HTTPS for public sites. Plain HTTP works only for `localhost`, `127.0.0.1`, and `[::1]`, with an explicit port.
* Each widget ID accepts up to 20 sites. A wildcard needs a domain you own, so `*.com` and `*.vercel.app` are rejected.
* Use a separate widget ID for local development, so you can turn it off without touching production.

On any other site, the widget loads but shows no live data. Allowed sites do not hide the data, which is public.

### Content security policy

Skip this if your site sends no `Content-Security-Policy` header.

| Directive | Add |
| - | - |
| `script-src` | `https://widgets.centaur.io`, plus a nonce or hash for the inline mount script |
| `style-src` | `https://widgets.centaur.io` |
| `connect-src` | `https://api.centaur.io` |
| `img-src` | `https://pbs.twimg.com`, `https://abs.twimg.com`, `https://s2.coinmarketcap.com`, `https://centaur-asset-images-prod.s3.amazonaws.com`, `https://centaur-asset-images-prod.s3.eu-west-1.amazonaws.com`, `https://centaur-telegram-assets-prod.s3.eu-west-1.amazonaws.com` |

The `img-src` hosts serve trader avatars and asset logos. Post photos can come from other HTTPS hosts; add the ones you are willing to display. If your policy blocks an avatar or logo, the widget shows the author's initials or the asset's first letter instead. Sample mode loads its fictional avatars from the widget script's own host.

To avoid an inline script, move the mount call into your own script file and load it after the SDK.

Do not add an `integrity` hash to the SDK tag. `/v1/sdk.js` changes in place. See [Runtime behavior](/integrations/widget-reference.md#runtime-behavior).

## Troubleshoot

| What you see | What to check |
| - | - |
| Nothing renders, and the console shows a blocked script or style | Your [content security policy](#content-security-policy). |
| "This feed needs a valid configuration." | IDs and option values against the [widget reference](/integrations/widget-reference.md#options). |
| "This feed is unavailable on this site." | In [Widget settings](https://app.centaur.io/settings/widgets): the widget ID is **Live**, the page's exact origin is an allowed site, and your partner account is active. |
| "No recent activity" | Not an error. The selected assets, traders, or asset classes have no recent activity. Widen the selection. |
| "Trading activity could not be loaded." with **Retry** | A temporary failure. Select **Retry**. Posts already showing stay visible while the widget retries. |

The positioning card shows the same messages, worded for positioning.

## Next steps

* [Widget recipes](/integrations/widget-recipes.md): change the asset when your page changes, style the widget, link to your own pages, and use it in React.
* [Widget reference](/integrations/widget-reference.md): every option, method, and callback.


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