circuit data --help. See Data for the TypeScript
surface, where agent.data.<method> calls the command of the same name in camel case.
Across every command
- Units: a Base figure counts the market’s base asset, and a Quote figure is stated in its quote asset. On a market row, a Usd figure is that quote figure valued at Circuit’s own mark for the quote asset, null when Circuit holds no such mark. An OHLC figure is quote units per one base unit, and a rate is a fraction, never a percent.
- A venue is where a thing trades; a vendor is a third party reporting facts it does not host.
- A read that answers observations answers : each key that answered contributes its own newest observation and a key that answered nothing contributes no tip, so the read’s tip is the oldest of the tips that answered, and age is the seconds from the read’s instant, —as-of or now, back to it, null when rows is empty or nothing the read names answered. assets answers identity, which does not decay, so it answers with no age and takes no —max-age.
- —max-age is a safe positive integer in seconds and fails the read with 412 DATA_TOO_OLD, carrying that age and that tip, when the tip is older than it. An empty answer is a known zero, so it has no age and is never rejected.
- A venue, dex or venue symbol the catalog holds no market under fails the read with 404 MARKET_NOT_CATALOGED, naming every symbol it does not hold, rather than answering an empty envelope; a delisted market is still cataloged, so it still answers.
- A repeatable parameter may be named more than once; the answer is grouped by key and every row names its own.
- A command that takes —lookback answers, without it, its newest observation per key as of —as-of or now: the last closed bar, the live funding or open interest row, the current mark, the latest yield reading, or the newest ended day of revenue or volume. markets is the exception, where the window only adds the windowed figures.
- A history read is bounded before it runs: —lookback at the asked grain over the asked symbols must come to at most 100000 bars; a wider read is rejected naming its bound. Assets paginate with nextCursor: up to 2000 rows per page in the CLI and SDK, or 50 in Terminal.
Discovery
assets
Which asset is this identifier, and what other identifiers does it carry: one row per asset with every contract address, venue listing and vendor key that maps to it.
One row per id.
Parameters: venue (optional; hyperliquid); venueSymbol (optional, repeatable); dex (optional); network (optional); address (optional); vendor (optional; defillama, defillama-yields, coingecko, morpho); vendorKey (optional); assetType (optional; coin, perpetual, vault, prediction, stock, fiat); cursor (optional); asOf (optional). See parameter definitions.
Row fields: id, symbol, name, assetType, underlyingAsset, venueIdentifiers[].venue, venueIdentifiers[].dex, venueIdentifiers[].venueSymbol, venueIdentifiers[].quoteAsset, venueIdentifiers[].quoteSymbol, venueIdentifiers[].maximumLeverage, venueIdentifiers[].orderSizeDecimals, venueIdentifiers[].delistedAt, vendorIdentifiers[].vendor, vendorIdentifiers[].vendorKey, contracts[].network, contracts[].address. See field definitions.
markets
Which markets does this venue list right now, and how is each one trading: one row per live market with its mid, its price 24 hours ago, 24h volume, open interest and predicted funding, in quote units and USD. A derived view that owns no fact: every figure is a join over candles and the current mid, open interest and funding, plus the quote asset’s mark. Its age bounds the mid, open interest and funding; price24hAgo, volumeQuote and volumeUsd are as of the last complete hour by definition and never move the tip. price24hAgo is null when the hourly bar ending 24 hours before the current hour is missing, and volumeQuote is null, never zero, when no complete hourly bar falls in the trailing 24 hours. —lookback is optional and names the window for the five windowed figures, which stand as of the last complete day or settlement, contribute no tip, and read null when no window is asked for. It is the one command with no —as-of.
One row per venue, dex, venueSymbol.
Parameters: venue (required; hyperliquid); dex (optional); assetType (optional; coin, perpetual, vault, prediction, stock, fiat); lookback (optional); maxAge (optional). See parameter definitions.
Row fields: venue, dex, venueSymbol, assetType, baseSymbol, quoteSymbol, maximumLeverage, orderSizeDecimals, price, priceUsd, price24hAgo, volumeQuote, volumeUsd, openInterestBase, openInterestQuote, openInterestUsd, fundingRate, settlesAt, medianDailyVolumeQuote, medianDailyVolumeUsd, observedDayCount, cumulativeFundingRate, fundingSettlementCount. See field definitions.
Prices and history
mids
What is this market trading at now: the venue’s current mid, in quote units per one base unit. History is candles; with —as-of the answer is the close of the candle bar ending at that instant, which is the accepted approximation.
One row per venue, dex, venueSymbol.
Parameters: venue (required; hyperliquid); venueSymbol (required, repeatable); dex (optional); asOf (optional); maxAge (optional). See parameter definitions.
Row fields: venue, dex, venueSymbol, timestamp, price. See field definitions.
candles
What did this market trade over each bar of the window: open, high, low, close, base volume and trade count. The one owner of per-market volume, at every window. A bar is observed at its close, so the window holds every bar closing inside it, the read’s tip is the newest bar’s close, and a —max-age under one bar of —grain is rejected.
One row per venue, dex, venueSymbol, grain, timestampOpen.
Parameters: venue (required; hyperliquid); venueSymbol (required, repeatable); dex (optional); grain (required; 1m, 5m, 15m, 1h, 4h, 1d); lookback (optional); asOf (optional); maxAge (optional). See parameter definitions.
Row fields: venue, dex, venueSymbol, grain, timestampOpen, open, high, low, close, volumeBase, tradeCount, collectedFrom. See field definitions.
marks
What was this token worth in USD over each bin of the window, keyed by network and contract address rather than by market. A row is the window’s last observation inside its bin, stamped at that observation’s own instant; the bin is the finest of 15m, 1h, 4h and 1d that fits the window in 200 of them, so —lookback 24h bins at 15m and 30d at 4h. Circuit’s own price history, never a venue mid, and only for tokens Circuit itself prices: held wallet inventory, a held receipt token’s underlying, and coins under a live price trigger. Any other token, on any network, has no marks and returns no rows; —network accepts only the networks Circuit prices.
One row per network, address, tokenId, pricedAt.
Parameters: network (required; solana, hypercore, ethereum:1, ethereum:42161, ethereum:137, ethereum:10, ethereum:8453, ethereum:56, ethereum:43114, ethereum:480, ethereum:143, ethereum:999, ethereum:4663); address (required); tokenId (optional); lookback (optional); asOf (optional); maxAge (optional). See parameter definitions.
Row fields: network, address, tokenId, priceUsd, pricedAt. See field definitions.
Derivatives
funding_rates
What funding is this market predicted to charge at its next hourly settlement, or which rates it actually settled over a —lookback window, each row carrying the settlement it is charged at. The current row is the predicted rate and its settlesAt lies in the future; under —as-of it is the rate settled at or before that instant, so settlesAt lies in the past and the quantity means the same thing either way.
One row per venue, dex, venueSymbol, settlesAt.
Parameters: venue (required; hyperliquid); venueSymbol (required, repeatable); dex (optional); lookback (optional); asOf (optional); maxAge (optional). See parameter definitions.
Row fields: venue, dex, venueSymbol, settlesAt, fundingRate. See field definitions.
open_interest
How much open interest does this market carry now, or at each observation instant of a —lookback window. The one market fact candles cannot hold; a spot market has no row. The current row is stamped at its own refresh instant.
One row per venue, dex, venueSymbol, timestamp.
Parameters: venue (required; hyperliquid); venueSymbol (required, repeatable); dex (optional); lookback (optional); asOf (optional); maxAge (optional). See parameter definitions.
Row fields: venue, dex, venueSymbol, timestamp, openInterestBase. See field definitions.
Fundamentals
yields
What does this vault or pool yield, how much does it hold, and what is one share worth, as one vendor measures it. The three vendors measure different things, so a read names one.
One row per vendor, asset, timestamp.
Parameters: asset (required); vendor (required; defillama-yields, morpho, onchain); lookback (optional); asOf (optional); maxAge (optional). See parameter definitions.
Row fields: asset, vendor, denominationAsset, denominationSymbol, timestamp, apyIncludingRewards, apyExcludingRewards, totalValueLocked, underlyingPerShare. See field definitions.
revenue
How much revenue did this asset’s protocol earn on each day of the window, as DeFi Llama reports it, with fees, total and holders side by side; or, with —sort-by, which assets earned the most of one of them over the window. The three figures overlap and never sum. A ranked read answers one row per asset carrying each figure’s window sum and observedDayCount, ordered descending on the one —sort-by names, over every asset or only the ones —asset names. A —lookback listing names —asset, since every asset over every day has no ceiling; without —lookback the newest day of every asset is one row each.
One row per vendor, asset, day.
Parameters: asset (optional, repeatable); sortBy (optional; holders, total, fees); order (optional; desc, asc); limit (optional); lookback (optional); asOf (optional); maxAge (optional). See parameter definitions.
Row fields: asset, vendor, denominationAsset, denominationSymbol, day, firstObservedAt, holders, total, fees, contributingProtocols, symbol, observedDayCount. See field definitions.
volumes
How much volume did this asset trade across every exchange on each day of the window, as a vendor aggregates it; or, with —sort-by, which assets traded the most over the window. It runs against the vendor’s tracked set, so an asset outside that set fails ASSET_NOT_TRACKED rather than reporting no volume. A ranked read answers one row per asset carrying the window sum and observedDayCount, ordered descending, over the whole tracked set or only the ones —asset names. A —lookback listing names —asset; without —lookback the newest day of every tracked asset is one row each.
One row per vendor, asset, day.
Parameters: asset (optional, repeatable); sortBy (optional; volume); order (optional; desc, asc); limit (optional); lookback (optional); asOf (optional); maxAge (optional). See parameter definitions.
Row fields: asset, vendor, denominationAsset, denominationSymbol, day, firstObservedAt, volume, symbol, observedDayCount. See field definitions.
Parameter definitions
address: Contract address of the token, as spelled under an assets row’s “contracts”.asOf: ISO-8601 timestamp with offset, from year 0001 onward; the window, known catalog links and age where present are measured from this instant.asset: Asset id, as returned in the “id” field of an assets row.assetType: The kind of thing the asset is; as a flag it narrows to that kind, judged on markets by the base asset.cursor: The nextCursor a previous page returned, to read the page after it. It pins that page’s instant and position, so keep the same filters and repeat until nextCursor is null to walk the whole set; changing filters or an explicit asOf rejects it. Omit it to start at the first page.dex: Hyperliquid dex the market lives on, as spelled under a markets row: main for the venue’s own perps and every spot pair, otherwise the builder dex’s name. Omit it to read every dex the venue lists.grain: Bar size; a 1d bar is a calendar day, and the trailing 24 hours is the last 24 1h bars.limit: Answer 1 to 100000 ranked rows; takes —sort-by beside it.lookback: Window length back from —as-of, or from now without it; e.g. “48h” or “90d”. A bar is in the window when its close is. Omit it for the newest observation per key.maxAge: Reject when the read’s tip, the oldest of the newest observations of the keys that answered, is older than this many seconds (412 DATA_TOO_OLD).network: Network the contract lives on, as spelled under an assets row’s “contracts”.order: desc, the default, ranks largest first; asc ranks smallest first. A null figure comes last either way. Takes —sort-by beside it.sortBy: Rank instead of list: sum this row field over the window for every asset in scope and answer one row per asset, ordered descending with nulls last, with observedDayCount as the mean’s denominator.tokenId: Sub-token of a multi-token, ERC-1155-style contract; EVM networks only, and null for a contract holding one token.vendor: The third party that reports on the asset.vendorKey: The vendor’s own id for the asset, as listed under an assets row’s “vendorIdentifiers”.venue: Where the market trades, as listed under an assets row’s “venueIdentifiers”.venueSymbol: The venue’s own symbol for the market, case-sensitive, as spelled under a markets row.
Field definitions
address: Contract address of the token, as spelled under an assets row’s “contracts”.apyExcludingRewards: Compounded annual yield from the vault’s own interest alone, leaving incentive rewards out.apyIncludingRewards: Compounded annual yield including incentive rewards. APY is the one basis stored, so a vendor’s APR is compounded before it is written.asset: Asset id, as returned in the “id” field of an assets row.assetType: The kind of thing the asset is; as a flag it narrows to that kind, judged on markets by the base asset.collectedFrom: How the bar reached us: api from the venue’s live window, archive rebuilt from its trade archive; null on a folded bar built from both.contributingProtocols: The vendor’s protocol slugs whose figures were summed into this day.cumulativeFundingRate: Sum of the settled funding rates inside the window, never a mean and never annualized. Divide by fundingSettlementCount for the mean rate per settlement.day: The day the activity happened, not the day the vendor stamped its reading. A day answers once it has ended, at or before the read’s instant; the running day is never served, since a vendor’s figure for it is a trailing window that overlaps the day before.delistedAt: When the venue stopped listing this market, null while it still trades.denominationAsset: The asset this row’s figures are stated in.denominationSymbol: Ticker of the denomination asset. A fundamentals row states its unit once, here, rather than suffixing each field.dex: Hyperliquid dex the market lives on, as spelled under a markets row: main for the venue’s own perps and every spot pair, otherwise the builder dex’s name.fees: What users paid the protocol, in the row’s denomination: one day of it on a day row, the window sum on a ranked row; null when the vendor reported none.firstObservedAt: When we first saw this revision of the day’s figure. A vendor restatement appends a new revision, and a read returns the newest one as of the request.fundingRate: A fraction charged per settlement interval, never annualized. The interval is the venue’s own, the gap between consecutive settlesAt values, hourly on Hyperliquid.fundingSettlementCount: How many settlements inside the window contributed to cumulativeFundingRate, the denominator of its mean.grain: Bar size; a 1d bar is a calendar day, and the trailing 24 hours is the last 24 1h bars.holders: The share of revenue accruing to token holders, in the row’s denomination: one day of it on a day row, the window sum on a ranked row; null when the vendor reported none.maximumLeverage: Highest leverage the venue allows on this market, null when it publishes none.medianDailyVolumeQuote: Median of the window’s daily volumes, each day being one 1d bar’s whole-day base volume valued at that same bar’s close. It is not the median of volumeQuote, which values each hour at its own close.medianDailyVolumeUsd: medianDailyVolumeQuote restated in USD at the quote asset’s current mark, not at each day’s own mark.network: Network the contract lives on, as spelled under an assets row’s “contracts”.observedDayCount: On a ranked row, how many distinct days inside the window contributed to the sum. On a markets row, how many 1d bars the median was taken over. Either way it is the caller’s own denominator, so a mean is its division rather than a stored figure.orderSizeDecimals: How many decimal places the venue accepts in an order’s size on this market.price: The venue’s mid, in quote units per one base unit, and never a display mark price.price24hAgo: Close of the hourly bar ending 24 hours before the start of the current hour, the accepted approximation of the venue’s own rolling 24-hour reference. A rolling offset, never a calendar boundary.pricedAt: The instant the observation this row reports was priced, so points do not sit on bucket boundaries.priceUsd: On a marks row, the token’s observed USD price. On a markets row, the mid restated in USD through the quote asset’s mark, never a mark of the base asset, and null when Circuit holds no such mark.quoteAsset: Asset id of the market’s pricing leg; a perpetual’s quote asset is its dex’s collateral token.settlesAt: The settlement instant the funding rate is charged at: the end of the hour now accruing while the rate is predicted, in the past once it has settled.timestampOpen: The instant the bar opens; it closes one grain later.tokenId: Sub-token of a multi-token, ERC-1155-style contract; EVM networks only, and null for a contract holding one token.total: Protocol revenue, in the row’s denomination: one day of it on a day row, the window sum on a ranked row; null when the vendor reported none.underlyingAsset: The asset this one derives its value from, such as a perpetual’s or a vault’s underlying, null when it stands alone.underlyingPerShare: Underlying assets redeemable for one vault share, in the row’s denomination, never a share price.vendor: The third party that reports on the asset.vendorKey: The vendor’s own id for the asset, as listed under an assets row’s “vendorIdentifiers”.venue: Where the market trades, as listed under an assets row’s “venueIdentifiers”.venueSymbol: The venue’s own symbol for the market, case-sensitive, as spelled under a markets row.volume: Volume traded across every exchange the vendor aggregates, in the row’s denomination: one day of it on a day row, the window sum on a ranked row.volumeQuote: Volume over the 24 complete hourly bars before the current hour, each valued at its own close, null rather than zero when the market has no bar in that window.