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

# Real-Time Charts

> Bootstrap TradingView-style bars by outcome id and keep the view live

AGG chart history is keyed by `VenueMarketOutcome.id` and comes from `GET /charts/bars`.
That endpoint returns one canonical bar series for a single outcome and resolution using
TradingView-style `[from, to)` and `countBack` semantics. Aggregate charts are not supported.

<Tabs>
  <Tab title="SDK (vanilla JS/TS)">
    Works in browsers, Node.js, and React Native. Bring your own chart library.

    ## 1. Set up the client

    ```typescript theme={null}
    import { createAggClient } from "@agg-build/sdk";

    const client = createAggClient({
      baseUrl: "https://api.agg.market",
      appId: "your-app-id",
      wsUrl: "wss://ws.agg.market/ws",
    });
    ```

    ## 2. Fetch historical bars

    ```typescript theme={null}
    const history = await client.getChartBars({
      venueMarketOutcomeId: "your-outcome-id",
      resolution: "5m",
      from: Date.now() - 24 * 60 * 60 * 1000,
      to: Date.now(),
    });

    const historicalBars = history.data;
    ```

    ## 3. Request bars with `countBack`

    ```typescript theme={null}
    const trailingBars = await client.getChartBars({
      venueMarketOutcomeId: "your-outcome-id",
      resolution: "5m",
      to: Date.now(),
      countBack: 300,
    });
    ```

    ## 4. Render with your chart library

    ```typescript theme={null}
    const chartData = historicalBars.map((c) => ({
      time: c.t / 1000,
      open: c.o,
      high: c.h,
      low: c.l,
      close: c.c,
      volume: c.v ?? undefined,
    }));

    yourChart.setData(chartData);
    ```

    ## 5. Optional live overlay

    ```typescript theme={null}
    import { CandleBuilder } from "@agg-build/sdk";

    const builder = new CandleBuilder();
    const ws = client.createWebSocket({
      onSnapshot: (_outcomeId, book) => {
        if (book.midpoint != null) builder.addMidpoint(book.midpoint, book.timestamp);
      },
      onDelta: (_outcomeId, book) => {
        if (book.midpoint != null) builder.addMidpoint(book.midpoint, book.timestamp);
      },
      onTrade: (trade) => {
        builder.addTrade(trade.price, trade.size, trade.timestamp);
      },
    });

    // Both live subscriptions and historical bars are keyed by outcome ID.
    ws.subscribe("your-outcome-id", "orderbook");
    ws.subscribe("your-outcome-id", "trades");
    ```
  </Tab>

  <Tab title="Hooks (React)">
    <Note>
      See the [Setup Guide](/api/setup) for the one-time `AggProvider` and `QueryClientProvider`
      setup. This recipe starts at the hook layer.
    </Note>

    ## 1. Use `useMarketChart`

    ```tsx theme={null}
    import { useMarketChart } from "@agg-build/hooks";

    function MarketChart({ venueMarketOutcomeId }: { venueMarketOutcomeId: string }) {
      const { data, isLoading } = useMarketChart({
        marketId: venueMarketOutcomeId,
        interval: "5m",
        startTs: Date.now() - 24 * 60 * 60 * 1000,
        endTs: Date.now(),
      });

      if (isLoading) return <div>Loading...</div>;

      const primaryVenue = data?.primaryVenue;
      const candles = primaryVenue ? data.venues[primaryVenue]?.candles ?? [] : [];

      return (
        <YourChart
          data={candles.map((c) => ({
            time: c.time,
            open: c.open,
            high: c.high,
            low: c.low,
            close: c.close,
          }))}
        />
      );
    }
    ```

    ## 2. Use `countBack` for scrollback

    ```tsx theme={null}
    function TrailingChart({ venueMarketOutcomeId }: { venueMarketOutcomeId: string }) {
      const { data } = useMarketChart({
        marketId: venueMarketOutcomeId,
        interval: "5m",
        endTs: Date.now(),
        countBack: 500,
      });

      const primaryVenue = data?.primaryVenue;
      const candles = primaryVenue ? data.venues[primaryVenue]?.candles ?? [] : [];

      return <YourChart data={candles} />;
    }
    ```

    ## 3. Live overlays remain optional

    `useMarketChart()` returns canonical historical bars under the hook's `primaryVenue`
    entry. If you need a forming bar on top of that history, layer on live orderbook/trade
    updates with the SDK `CandleBuilder`.
  </Tab>

  <Tab title="UI Components">
    Drop-in React components for charts, orderbooks, and full event/market layouts.

    ## [Event Market Page](/components/pages/event-market-page)

    ```tsx theme={null}
    import { EventMarketPage } from "@agg-build/ui/pages";

    function EventPage({ eventId }) {
      return <EventMarketPage eventId={eventId} />;
    }
    ```

    This renders a hero chart plus stacked market detail cards with live charts and orderbooks.

    ## [Market Details](/components/events/market-details) card

    ```tsx theme={null}
    import { MarketDetails } from "@agg-build/ui/events";

    function MarketCard({ event, marketId }) {
      return <MarketDetails event={event} marketId={marketId} defaultTab="graph" />;
    }
    ```

    ## Standalone chart

    ```tsx theme={null}
    import { LineChart } from "@agg-build/ui/primitives";

    function Chart({ series }) {
      return <LineChart series={series} height={320} chartType="candlestick" live />;
    }
    ```

    Browse the live [Event Market Page reference](/components/pages/event-market-page) and
    [Market Details reference](/components/events/market-details).
  </Tab>
</Tabs>

## Supported resolutions

`GET /charts/bars` supports four stored resolutions:

| Interval  | Code   |
| --------- | ------ |
| 1 minute  | `"1m"` |
| 5 minutes | `"5m"` |
| 1 hour    | `"1h"` |
| 1 day     | `"1d"` |

## How it works

```text theme={null}
GET /charts/bars            -> Canonical historical bars   -> Initial render
Optional live WS overlay    -> CandleBuilder / hooks       -> Forming bar updates
```

For wire-level details, resnapshot behavior, and authenticated streaming, see
[WebSocket Protocol](/api/websocket).

## Related

<CardGroup cols={2}>
  <Card title="WebSocket Protocol" icon="gear" href="/api/websocket">
    Subscribe, authenticate, handle heartbeats, and reconnect safely.
  </Card>

  <Card title="Real-Time Orderbook" icon="code" href="/recipes/websocket-orderbook">
    Reuse the same orderbook stream for depth views and chart inputs.
  </Card>

  <Card title="User Notifications" icon="key" href="/recipes/websocket-notifications">
    Handle authenticated order and balance events on the same socket.
  </Card>
</CardGroup>