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

# Data

> Discover assets and markets; read prices, derivatives and fundamentals from every agent run.

`agent.data` exposes ten read-only methods, named after their `circuit data` commands in camel
case. [Data commands](./data-commands) defines each command's parameters, rows and conventions,
using the same groups and order as CLI help.

Observation reads return `{ rows, age }`. `assets` returns identity as `{ rows, nextCursor }`
(null on the last page), without `age` or `maxAge`. Query fields cross the wire as strings:
write a numeric `maxAge` as `"120"`. Repeatable parameters accept one value or an array:
`venueSymbol` on market commands and `assets`, and `asset` on `revenue` and `volumes`.

## Discovery

Resolve identifiers with `assets`, then inspect listed markets with `markets`:

```typescript theme={null}
const { rows: assets } = await agent.data.assets({ venue: "hyperliquid", venueSymbol: "USDC" });
await agent.data.markets({ venue: "hyperliquid", assetType: "perpetual", lookback: "30d" });
```

`asset` is an `assets` row's `id`, minted per database. Resolve it at runtime; never hardcode it
across environments or substitute a symbol. To walk assets, keep the same filters and pass
`nextCursor` back until it is null:

```typescript theme={null}
let cursor: string | undefined;
do {
  const page = await agent.data.assets({ assetType: "coin", ...(cursor ? { cursor } : {}) });
  await agent.log(page.rows);
  cursor = page.nextCursor ?? undefined;
} while (cursor);
```

## Prices and history

```typescript theme={null}
await agent.data.mids({ venue: "hyperliquid", venueSymbol: "BTC", dex: "main" });
await agent.data.candles({
  venue: "hyperliquid",
  venueSymbol: ["BTC", "ETH", "SOL"],
  grain: "1h",
  lookback: "48h",
});
await agent.data.marks({
  network: "ethereum:1",
  address: "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
  lookback: "1h",
});
```

Without `lookback`, a command that accepts it answers its newest observation per key;
`asOf` reads history. `markets` uses `lookback` only for its windowed figures and takes no `asOf`.
Prices from `marks` are display and accounting facts only. Transaction execution rechecks live
facts independently.

## Derivatives

```typescript theme={null}
await agent.data.fundingRates({ venue: "hyperliquid", venueSymbol: "BTC", lookback: "24h" });
await agent.data.openInterest({ venue: "hyperliquid", venueSymbol: "BTC", lookback: "30d" });
```

Omit `lookback` for current funding rates and open interest.

## Fundamentals

Use an asset ID resolved through `assets`:

```typescript theme={null}
await agent.data.yields({ asset: assets[0].id, vendor: "onchain", lookback: "30d" });
await agent.data.revenue({ asset: assets[0].id, lookback: "90d" });
await agent.data.volumes({ asset: assets[0].id, lookback: "30d" });
```

For rankings, `sortBy` returns one row per asset carrying its window sum and `observedDayCount`.
`order` defaults to descending; `limit` bounds the ranking. Omit `asset` to rank the full set.
Revenue carries `fees`, `total` and `holders` side by side; `sortBy` selects the ranking field.

```typescript theme={null}
await agent.data.revenue({ lookback: "30d", sortBy: "fees", limit: "20" });
await agent.data.volumes({ lookback: "30d", sortBy: "volume", order: "asc" });
```

Failures throw [`ApiError`](./error-handling); catch only for a real alternative or added context.