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

# Query Onchain Trades

> How to query onchain fills by wallet, by event, and by market

<Info>
  During development, you can use the [developer endpoints](/get-started/endpoints)
  without an API key. For production use, [request an API key](/get-started/api-key)
  for higher rate limits.
</Info>

## Use Cases

* Display global "recent fills" across all markets.
* Display market-specific fills next to orderbook and price data.
* Display wallet trade history scoped to a market or event.
* Trigger alerts for large trades using `minAmount` filters.

<Steps>
  <Step title="Set Base URL and Query Helper">
    Define the metadata API base URL and reusable query/output helpers.

    <AccordionGroup>
      <Accordion title="Initialize Helpers">
        ```typescript theme={null}
        import "dotenv/config";

        const DFLOW_METADATA_API_URL = process.env.DFLOW_METADATA_API_URL ?? "https://dev-prediction-markets-api.dflow.net";
        const DFLOW_API_KEY = process.env.DFLOW_API_KEY; // optional; not needed for dev endpoints

        const headers: HeadersInit = {};
        if (DFLOW_API_KEY) headers["x-api-key"] = DFLOW_API_KEY;

        type QueryValue = string | number | undefined | null;
        type OnchainTrade = Record<string, any>;

        function toQueryString(params: Record<string, QueryValue>): string {
          const searchParams = new URLSearchParams();

          Object.entries(params).forEach(([key, value]) => {
            if (value !== undefined && value !== null && value !== "") {
              searchParams.set(key, String(value));
            }
          });

          const query = searchParams.toString();
          return query ? `?${query}` : "";
        }

        function printTrades(trades: OnchainTrade[]) {
          trades.forEach((trade) => {
            console.log({
              id: trade.id,
              createdAt: trade.createdAt,
              marketTicker: trade.marketTicker,
              side: trade.side,
              inputAmount: trade.inputAmount,
              outputAmount: trade.outputAmount,
              wallet: trade.wallet,
              transactionSignature: trade.transactionSignature,
            });
          });
        }
        ```
      </Accordion>
    </AccordionGroup>
  </Step>

  <Step title="Get Onchain Trades by Wallet">
    Scope fills to a single wallet using `/api/v1/onchain-trades` with the
    `wallet` query parameter.

    <AccordionGroup>
      <Accordion title="Pure Wallet Filter (Global Onchain Trades)">
        ```typescript theme={null}
        async function getWalletOnchainTrades(wallet: string) {
          const response = await fetch(
            `${DFLOW_METADATA_API_URL}/api/v1/onchain-trades?wallet=${wallet}&limit=100&sortBy=createdAt&sortOrder=desc`,
            { headers }
          );

          if (!response.ok) {
            throw new Error("Failed to fetch wallet onchain trades");
          }

          const data = await response.json();
          const trades = data.trades ?? [];
          const nextCursor = data.cursor ?? null;

          printTrades(trades);

          console.log({
            wallet,
            tradeCount: trades.length,
            nextCursor,
          });
        }
        ```
      </Accordion>
    </AccordionGroup>
  </Step>

  <Step title="Get Onchain Trades Across All Markets">
    Scope fills across all markets using `/api/v1/onchain-trades`.

    <AccordionGroup>
      <Accordion title="Fetch Global Onchain Trades">
        ```typescript theme={null}
        async function getGlobalOnchainTrades() {
          const query = toQueryString({
            limit: 100,
            cursor: undefined,
            mint: undefined, // optional
            ticker: undefined, // optional
            sortBy: "createdAt",
            sortOrder: "desc",
            minAmount: undefined,
            maxAmount: undefined,
          });

          const response = await fetch(
            `${DFLOW_METADATA_API_URL}/api/v1/onchain-trades${query}`,
            { headers }
          );

          if (!response.ok) {
            throw new Error("Failed to fetch onchain trades");
          }

          const data = await response.json();
          const trades = data.trades ?? [];
          const nextCursor = data.cursor ?? null;

          printTrades(trades);
          console.log({ tradeCount: trades.length, nextCursor });
        }
        ```
      </Accordion>
    </AccordionGroup>
  </Step>

  <Step title="Get Onchain Trades by Event">
    Scope fills to all markets inside a single event using
    `/api/v1/onchain-trades/by-event/{event_ticker}`.

    <AccordionGroup>
      <Accordion title="Fetch Event Onchain Trades">
        ```typescript theme={null}
        async function getEventOnchainTrades(eventTicker: string) {
          const query = toQueryString({
            limit: 100,
            sortBy: "createdAt",
            sortOrder: "desc",
            minAmount: undefined,
            maxAmount: undefined,
          });

          const response = await fetch(
            `${DFLOW_METADATA_API_URL}/api/v1/onchain-trades/by-event/${eventTicker}${query}`,
            { headers }
          );

          if (!response.ok) {
            throw new Error("Failed to fetch onchain trades by event");
          }

          const data = await response.json();
          const trades = data.trades ?? [];
          const nextCursor = data.cursor ?? null;

          printTrades(trades);
          console.log({
            eventTicker,
            tradeCount: trades.length,
            nextCursor,
          });
        }
        ```
      </Accordion>
    </AccordionGroup>
  </Step>

  <Step title="Get Onchain Trades by Market">
    Scope fills to a single market using
    `/api/v1/onchain-trades/by-market/{market_ticker}`.

    <AccordionGroup>
      <Accordion title="Fetch Market Onchain Trades">
        ```typescript theme={null}
        async function getMarketOnchainTrades(marketTicker: string) {
          const query = toQueryString({
            limit: 100,
            sortBy: "createdAt",
            sortOrder: "desc",
            minAmount: undefined,
            maxAmount: undefined,
          });

          const response = await fetch(
            `${DFLOW_METADATA_API_URL}/api/v1/onchain-trades/by-market/${marketTicker}${query}`,
            { headers }
          );

          if (!response.ok) {
            throw new Error("Failed to fetch onchain trades by market");
          }

          const data = await response.json();
          const trades = data.trades ?? [];
          const nextCursor = data.cursor ?? null;

          printTrades(trades);
          console.log({
            marketTicker,
            tradeCount: trades.length,
            nextCursor,
          });
        }
        ```
      </Accordion>
    </AccordionGroup>
  </Step>

  <Step title="Paginate with Cursor">
    Scope historical pagination by passing each response `cursor` into the next
    `/api/v1/onchain-trades` request.

    <AccordionGroup>
      <Accordion title="Cursor Pagination Loop">
        ```typescript theme={null}
        async function fetchAllOnchainTrades(limitPerPage = 250) {
          let cursor: string | null = null;
          const allTrades: OnchainTrade[] = [];

          do {
            const query = toQueryString({
              limit: limitPerPage,
              cursor,
              sortBy: "createdAt",
              sortOrder: "desc",
            });

            const response = await fetch(
              `${DFLOW_METADATA_API_URL}/api/v1/onchain-trades${query}`,
              { headers }
            );
            if (!response.ok) throw new Error("Failed to paginate onchain trades");

            const page = await response.json();
            allTrades.push(...(page.trades ?? []));
            cursor = page.cursor ?? null;
          } while (cursor);

          printTrades(allTrades);
          return allTrades;
        }
        ```
      </Accordion>
    </AccordionGroup>
  </Step>
</Steps>

## Related Resources

<CardGroup cols={2}>
  <Card title="Onchain Trade Parsing" href="/prediction-markets/onchain-trade-parsing" icon="diagram-project">
    How outcome-token trades land onchain and what fields the parser surfaces.
  </Card>

  <Card title="Track User Positions" href="/prediction-markets/recipes/track-positions" icon="chart-line">
    Map wallet balances back to markets and outcomes.
  </Card>

  <Card title="Buy Outcome Tokens" href="/prediction-markets/recipes/buy-outcome-tokens" icon="wallet">
    Open a prediction market position from any input token.
  </Card>
</CardGroup>

## API Routes

* [GET /api/v1/onchain-trades](/resources/metadata-api/trades/onchain-trades)
* [GET /api/v1/onchain-trades/by-event/{event_ticker}](/resources/metadata-api/trades/onchain-trades-by-event)
* [GET /api/v1/onchain-trades/by-market/{market_ticker}](/resources/metadata-api/trades/onchain-trades-by-market)