Skip to content
CTRL K
    Reference
    Read operations

    Read operations

    Every way to fetch data from the Nutrimatic SDK.

    Create a client once, then call the methods you need:

    import { createNutrimaticSdk } from '@nutrimatic/sdk'

const sdk = createNutrimaticSdk({
  ledgers: [{ id: 'evm:421018', kind: 'evm', chainId: 421018, alias: 'infinite-mainnet' }],
  mode: 'read',
  integrationContext: 'client',
})

    Use Supported ledgers for ledger IDs, Types for object shapes, Chart windows for OHLCV windows and scope, Activity feeds for event feed windows and FeedQuery, Naming conventions for list* / get* method names, and Errors for failure codes.

    Ledger scope

    Declare ledgers once at init; pass ID or alias only in method inputs.

    When you create the SDK, you declare full LedgerRef entries in config. After that, method parameters accept optional ledgers arrays of LedgerScope strings (ledger ID or alias). Responses always use the canonical ledger ID. The SDK resolves kind and chainId from your config; you never repeat them in method calls.

    type LedgerScope = LedgerId | string  // e.g. 'evm:421018' or 'infinite-mainnet'

    Resolution

    When you pass a LedgerScope string, the SDK looks it up among your configured ledgers:

    1. Exact match on id — e.g. 'evm:421018'
    2. Exact match on alias — e.g. 'infinite-mainnet'

    If neither matches, the call fails with LEDGER_NOT_SUPPORTED.

    'evm:421018' and 'infinite-mainnet' are interchangeable when they refer to the same configured ledger.

    Filtering with ledgers

    Methods that scope by chain accept an optional ledgers array of LedgerScope strings. You may mix IDs and aliases freely:

    await sdk.easy.read.listPairs({ ledgers: ['evm:421018'] })
await sdk.easy.read.listPairs({
  ledgers: ['evm:421018', 'infinite-mainnet'],
})
// 'evm:421018' and 'infinite-mainnet' resolve to the same ledger → deduplicated

    The SDK normalizes every entry to its canonical id, removes duplicates, then applies the filter. Pass one element when you need a single ledger. Omit ledgers to include all ledgers from your config.

    At a glance

    I want to…Call
    List tradable pairssdk.easy.read.listPairs()
    One tradable pair by labelsdk.easy.read.getPair()
    OHLCV chart for a pair labelsdk.easy.read.getChart()
    Token price and 24h changesdk.easy.read.getTokenPrice()
    Pool summary (spot, TVL, volume)sdk.easy.read.getPoolView()
    Trade feed for a pair labelsdk.easy.read.getTradeFeed()
    Ledgers on this deploymentsdk.catalog.listLedgers()
    All instruments on a ledgersdk.catalog.listInstruments()
    One instrument by IDsdk.catalog.getInstrument()
    Instrument editorial profilesdk.catalog.getInstrumentProfile()
    All AMM venues on a ledgersdk.catalog.listVenues()
    One venue by IDsdk.catalog.getVenue()
    Contract deployment manifestsdk.catalog.getDeployment()
    Pool telemetry viewsdk.telemetry.getAmmView()
    OHLCV candles for a venuesdk.telemetry.getCandles()
    Token telemetry viewsdk.telemetry.getInstrumentView()
    Venue event feed (all kinds)sdk.telemetry.getVenueFeed()
    Trades only on a venuesdk.telemetry.getTrades()
    Live AMM reserves and spotsdk.venues.getAmmState()
    Spot rate for a venuesdk.venues.getSpotRate()

    Naming: list methods use list*; single resources use get*. See Naming conventions.

    Choosing a level: start with easy.read when you have pair labels or simple IDs. Use catalog to discover IDs, then telemetry or venues when you already know the exact venueId or instrumentId.

    easy.read

    Convenience layer for common UI and analytics tasks. Accepts human-friendly pair labels and resolves Nutrimatic IDs for you.

    easy.read.listPairs

    Purpose: List tradable pairs (for selectors, market lists, search).

    const pairs = await sdk.easy.read.listPairs()
const onInfinite = await sdk.easy.read.listPairs({ ledgers: ['evm:421018'] })
const byAlias = await sdk.easy.read.listPairs({ ledgers: ['infinite-mainnet'] })
const scoped = await sdk.easy.read.listPairs({
  ledgers: ['evm:421018', 'infinite-mainnet'],
})
    ParameterTypeRequiredDescription
    ledgersLedgerScope[]NoRestrict results to these ledgers (ID or alias, e.g. infinite-mainnet). Omit to include pairs from every ledger in your config.

    Omit ledgers to return pairs across all ledgers in your config. See Filtering with ledgers.

    Returns: PairListing[]

    FieldTypeDescription
    pairLabelstringHuman-readable market label for lists and search (e.g. 42-USDT). Pass it to easy.read.getPair, getChart, or getTradeFeed.
    venueIdVenueIdUnderlying pool/venue ID for this pair. Pass to catalog.getVenue, telemetry.getAmmView, or venues.getAmmState for pool-level detail.
    baseInstrumentIdInstrumentIdInstrument ID of the pair’s base asset — the one being priced (e.g. 42 in 42-USDT).
    quoteInstrumentIdInstrumentIdInstrument ID of the pair’s quote asset — the pricing denominator (e.g. USDT in 42-USDT).

    Example response:

    [
  {
    "pairLabel": "42-USDT",
    "venueId": "evm:421018:amm:v2:0xabc123",
    "baseInstrumentId": "evm:421018:instrument:42",
    "quoteInstrumentId": "evm:421018:instrument:usdt"
  }
]

    Common errors: LEDGER_NOT_SUPPORTED, INFRASTRUCTURE_UNAVAILABLE

    easy.read.getPair

    Purpose: Look up one tradable pair by label (pair detail row, deep link from search).

    const pair = await sdk.easy.read.getPair({ pair: '42-USDT' })
const scoped = await sdk.easy.read.getPair({
  pair: '42-USDT',
  ledgers: ['infinite-mainnet'],
})
    ParameterTypeRequiredDescription
    pairstringYesDisplay label to look up, in the same format returned by listPairs (e.g. 42-USDT).
    ledgersLedgerScope[]NoNarrow which ledgers to search when the label could resolve on more than one.

    Returns: PairListing — see Types — PairListing

    Example response:

    {
  "pairLabel": "42-USDT",
  "venueId": "evm:421018:amm:v2:0xabc123",
  "baseInstrumentId": "evm:421018:instrument:42",
  "quoteInstrumentId": "evm:421018:instrument:usdt"
}

    Common errors: PAIR_NOT_FOUND, LEDGER_NOT_SUPPORTED, INFRASTRUCTURE_UNAVAILABLE

    easy.read.getChart

    Purpose: OHLCV candle series for a pair label (charts, sparklines, history panels).

    Window parameters (limit, after, before, scope) control how much history each request returns. See Chart windows for bootstrap, tail refresh, partial bar, and paging backward.

    // Bootstrap — initial chart load
const chart = await sdk.easy.read.getChart({
  pair: '42-USDT',
  interval: '1h',
  limit: 300,
})

// Tail refresh — only candles newer than your last closed bucket
const tail = await sdk.easy.read.getChart({
  pair: '42-USDT',
  interval: '1h',
  after: 1719792000,
})

// Live open bar only — frequent poll while chart is visible
const live = await sdk.easy.read.getChart({
  pair: '42-USDT',
  interval: '1h',
  scope: 'partialOnly',
})

// Page backward — older history when the user scrolls left
const older = await sdk.easy.read.getChart({
  pair: '42-USDT',
  interval: '1h',
  before: 1719705600,
  limit: 100,
})
    ParameterTypeRequiredDescription
    pairstringYesDisplay label for the market to chart (e.g. 42-USDT); Nutrimatic resolves it to the underlying venue.
    intervalCandleIntervalYesCandle bucket size — how much time each bar covers: '15m' | '1h' | '4h' | '1d' | '1w'. Unavailable intervals → CAPABILITY_NOT_AVAILABLE.
    limitnumberNoMax closed candles to return (newest within the window). Default 300 if omitted; cap 1000. See Chart windows.
    afternumberNoUnix seconds — return closed candles with time greater than this value. Use for incremental tail refresh; pass lastClosedCandleTime(series.candles).
    beforenumberNoUnix seconds — return closed candles with time less than this value. Use with limit to load older history; pass firstClosedCandleTime(series.candles).
    scope'default' | 'partialOnly'No'default' (or omit) — closed candles per window params plus partialCandle. 'partialOnly' — only the open (in-progress) bar; candles is always []. See Chart windows — scope
    ledgersLedgerScope[]NoScope pair resolution to these configured ledgers (ID or alias). Omit to search across all configured ledgers.

    Returns: CandleSeries — see Types — CandleSeries. Merge tail responses with mergeCandleSeries.

    Example response:

    {
  "venueId": "evm:421018:amm:v2:0xabc123",
  "interval": "1h",
  "priceAxisLabel": "42/USDT",
  "asOf": 1719795600,
  "candles": [
    { "time": 1719792000, "open": 1.02, "high": 1.05, "low": 1.01, "close": 1.04 }
  ],
  "partialCandle": {
    "time": 1719795600,
    "open": 1.04,
    "high": 1.06,
    "low": 1.03,
    "close": 1.05
  }
}

    Common errors: VENUE_NOT_FOUND, LEDGER_NOT_SUPPORTED, NORMALIZATION_FAILED, INFRASTRUCTURE_UNAVAILABLE

    easy.read.getTokenPrice

    Purpose: Instrument telemetry for tickers and headers — USD price, 24h change, optional aggregated venue market stats, and optional supply when offered for that instrument.

    const price = await sdk.easy.read.getTokenPrice({
  instrument: 'evm:421018:instrument:42',
})
// symbol shorthand when unambiguous on the configured ledger:
const priceBySymbol = await sdk.easy.read.getTokenPrice({ instrument: '42' })
    ParameterTypeRequiredDescription
    instrumentInstrumentId | stringYesFull Nutrimatic instrument ID (e.g. evm:421018:instrument:42) or a bare symbol (e.g. 42) when it’s unambiguous on your configured ledgers.
    ledgersLedgerScope[]NoNarrow symbol resolution to these ledgers when the same symbol exists on more than one configured ledger.

    Returns: InstrumentTelemetryView — price fields plus optional market and supply.

    FieldTypeDescription
    instrumentIdInstrumentIdThe instrument this view applies to, resolved from your instrument input.
    priceUsdnumberOptional. Latest price in USD when Nutrimatic can anchor the instrument via listed markets (direct stable pair or through another listed instrument with a USD price). Omit when no usable USD anchor exists. Display as-is; poll or re-fetch for updates.
    change24h{ value: number }Percent change of this instrument’s USD price over ~24 hours (e.g. 2.3 means +2.3%). Positive is up, negative is down.
    marketobjectOptional. Aggregated 24h volume and liquidity across listed venues for this instrument (liquidityUsd uses half-pool TVL per venue; see InstrumentMarketView).
    supplyobjectOptional. Total supply, issuance, treasury/vesting, holder count, and derived caps when available.

    Example response:

    {
  "instrumentId": "evm:421018:instrument:42",
  "priceUsd": 1.04,
  "change24h": { "value": 2.3 },
  "market": {
    "volume24hUsd": 125000,
    "liquidityUsd": 890000
  },
  "supply": {
    "asOf": 1753072800,
    "total": { "raw": "100451001124521553982862588", "decimals": 18 },
    "holders": { "count": 176 },
    "derived": {
      "circulating": { "raw": "15781927611436622828862588", "decimals": 18 },
      "mcapCirculating": 16413204.72,
      "fdv": 104469041.17
    }
  }
}

    Common errors: INSTRUMENT_NOT_FOUND, LEDGER_NOT_SUPPORTED, INFRASTRUCTURE_UNAVAILABLE

    easy.read.getPoolView

    Purpose: Summary metrics for one pool (pool detail pages, cards, comparison tables).

    const view = await sdk.easy.read.getPoolView({
  venue: 'evm:421018:amm:v2:0x…',
})
    ParameterTypeRequiredDescription
    venueVenueId | stringYesNutrimatic venue ID for the pool (from catalog.listVenues or a pair’s venueId).
    ledgersLedgerScope[]NoNarrow resolution to these ledgers when the venue reference could match more than one.

    Returns: AmmTelemetryView — see Types — AmmTelemetryView

    Example response:

    {
  "venueId": "evm:421018:amm:v2:0xabc123",
  "spot": {
    "value": 1.04,
    "baseInstrumentId": "evm:421018:instrument:42",
    "quoteInstrumentId": "evm:421018:instrument:usdt",
    "asOf": 1719795600
  },
  "change24h": { "value": 0.8 },
  "tvlUsd": 1250000,
  "volume24hUsd": 84000
}

    Common errors: VENUE_NOT_FOUND, INFRASTRUCTURE_UNAVAILABLE

    easy.read.getTradeFeed

    Purpose: Trade activity feed for a pair label (activity panel, trade tape).

    Window parameters (limit, after, before, scope) control how many events each request returns. See Activity feeds for bootstrap, tail refresh, and paging backward.

    // Bootstrap — initial panel load
const feed = await sdk.easy.read.getTradeFeed({
  pair: '42-USDT',
  limit: 50,
})

// Tail refresh — only events newer than your last cursor
import { lastFeedCursor } from '@nutrimatic/sdk'

const tail = await sdk.easy.read.getTradeFeed({
  pair: '42-USDT',
  after: lastFeedCursor(feed.events),
})

// Page backward — older events when the user scrolls up
import { firstFeedCursor } from '@nutrimatic/sdk'

const older = await sdk.easy.read.getTradeFeed({
  pair: '42-USDT',
  before: firstFeedCursor(feed.events),
  limit: 50,
})
    ParameterTypeRequiredDescription
    pairstringYesMarket to show activity for, as a display label (e.g. 42-USDT). Nutrimatic resolves it to the underlying venue.
    limitnumberNoMax events to return (most recent within the window; array is still ascending). Default 50 if omitted; cap 200. See Activity feeds.
    afterFeedCursorNoOnly events newer than this cursor (tail refresh). Pass lastFeedCursor(feed.events) from your last load.
    beforeFeedCursorNoOnly events older than this cursor (scroll up). Use with limit; pass firstFeedCursor(feed.events).
    scope'default' | 'headOnly'No'default' (or omit) — events matching window params. 'headOnly' — live edge only; events is always []. See Activity feeds — scope.
    kindsFeedEventKind[]NoRestrict to specific event kinds. On this method, omit to default to trades only for the resolved venue.
    ledgersLedgerScope[]NoScope pair resolution to these configured ledgers (ID or alias). Omit to search across all configured ledgers.

    Returns: TradeFeed — see Types — TradeFeed and TradeView. Merge tail responses with mergeFeedSeries.

    Example response:

    {
  "scopeId": "evm:421018:amm:v2:0xabc123",
  "scopeKind": "venue",
  "ordering": "asc",
  "asOf": 1719795600,
  "events": [
    {
      "eventId": "evm:421018:swap:0xabc…:12",
      "time": 1719795600,
      "kind": "trade",
      "ledgerId": "evm:421018",
      "txHash": "0xabc123def456",
      "actor": "0xuser000000000000000000000000000000000001",
      "venueId": "evm:421018:amm:v2:0xabc123",
      "price": 1.04,
      "baseAmount": 250,
      "quoteAmount": 260,
      "side": "buy"
    }
  ]
}

    Common errors: VENUE_NOT_FOUND, LEDGER_NOT_SUPPORTED, INFRASTRUCTURE_UNAVAILABLE

    catalog

    Discovery and metadata. Use when you need IDs, symbols, or deployment addresses before calling telemetry or venues.

    catalog.listLedgers

    Purpose: List ledgers available from Nutrimatic (runtime discovery beyond static config).

    const ledgers = await sdk.catalog.listLedgers()

    Parameters: none

    Returns: LedgerRef[] — same shape as config ledgers; see Ledgers.

    Example response:

    [
  {
    "id": "evm:421018",
    "kind": "evm",
    "chainId": 421018,
    "alias": "infinite-mainnet"
  }
]

    Common errors: INFRASTRUCTURE_UNAVAILABLE

    catalog.listInstruments

    Purpose: List instruments (tokens) on a ledger or lineage.

    const all = await sdk.catalog.listInstruments()
const onInfinite = await sdk.catalog.listInstruments({ ledgers: ['evm:421018'] })
const byAlias = await sdk.catalog.listInstruments({ ledgers: ['infinite-mainnet'] })
const lineage = await sdk.catalog.listInstruments({ lineage: 'native' })
    ParameterTypeRequiredDescription
    ledgersLedgerScope[]NoRestrict results to these ledgers (ID or alias, e.g. infinite-mainnet). Omit to list instruments across all configured ledgers.
    lineagestringNoFilter to instruments of a given lineage (e.g. 'native' for a chain’s native asset). Omit to include every lineage.

    Returns: Instrument[] — see Types — Instrument

    Example response:

    [
  {
    "id": "evm:421018:instrument:42",
    "symbol": "42",
    "ledgerId": "evm:421018",
    "lineage": "native",
    "displayName": "42",
    "decimals": 18
  }
]

    Common errors: LEDGER_NOT_SUPPORTED, INFRASTRUCTURE_UNAVAILABLE

    catalog.getInstrument

    Purpose: Fetch one instrument by ID — identity fields only (Instrument).

    const instrument = await sdk.catalog.getInstrument('evm:421018:instrument:42')
    ParameterTypeRequiredDescription
    instrumentIdInstrumentIdYesNutrimatic instrument ID for the token (from catalog.listInstruments, or a pair’s baseInstrumentId/quoteInstrumentId).

    Returns: Instrument — see Types — Instrument

    Example response:

    {
  "id": "evm:421018:instrument:42",
  "symbol": "42",
  "ledgerId": "evm:421018",
  "lineage": "native",
  "displayName": "42",
  "decimals": 18
}

    Common errors: INSTRUMENT_NOT_FOUND, LEDGER_NOT_SUPPORTED, INFRASTRUCTURE_UNAVAILABLE

    catalog.getInstrumentProfile

    Purpose: Editorial metadata for an instrument — tagline, description, logo, tags, community links. Separate from identity and market data.

    const profile = await sdk.catalog.getInstrumentProfile('evm:421018:instrument:42')
    ParameterTypeRequiredDescription
    instrumentIdInstrumentIdYesNutrimatic instrument ID for the token (from catalog.listInstruments, or a pair’s baseInstrumentId/quoteInstrumentId).

    Returns: InstrumentProfile — see Types — InstrumentProfile

    Example response:

    {
  "instrumentId": "evm:421018:instrument:42",
  "tagline": "The native asset of Infinite.",
  "description": "Native token of Infinite Mainnet.",
  "logoUrl": "https://cdn.nutrimatic.xyz/instruments/42.png",
  "links": [
    { "label": "website", "url": "https://example.com" },
    { "label": "x", "url": "https://x.com/example" }
  ],
  "tags": ["native"],
  "listedAt": "2026-01-01T00:00:00Z",
  "updatedAt": "2026-07-01T00:00:00Z"
}

    Common errors: INSTRUMENT_NOT_FOUND, LEDGER_NOT_SUPPORTED, INFRASTRUCTURE_UNAVAILABLE

    catalog.listVenues

    Purpose: List AMM venues (pools) on a ledger — source of venueId values for lower-level calls.

    const venues = await sdk.catalog.listVenues()
const onInfinite = await sdk.catalog.listVenues({ ledgers: ['infinite-mainnet'] })
    ParameterTypeRequiredDescription
    ledgersLedgerScope[]NoRestrict results to these ledgers (ID or alias, e.g. infinite-mainnet). Omit to list venues across all configured ledgers.

    Returns: AmmVenueRef[] — see Types — AmmVenueRef

    Example response:

    [
  {
    "id": "evm:421018:amm:v2:0xabc123",
    "ledgerId": "evm:421018",
    "kind": "amm",
    "protocol": "v2",
    "poolAddress": "0xabc123"
  }
]

    Common errors: LEDGER_NOT_SUPPORTED, INFRASTRUCTURE_UNAVAILABLE

    catalog.getVenue

    Purpose: Fetch one AMM venue by ID.

    const venue = await sdk.catalog.getVenue('evm:421018:amm:v2:0xabc123')
    ParameterTypeRequiredDescription
    venueIdVenueIdYesNutrimatic venue ID for the pool (from catalog.listVenues or a pair’s venueId).

    Returns: AmmVenueRef — see Types — AmmVenueRef

    Example response:

    {
  "id": "evm:421018:amm:v2:0xabc123",
  "ledgerId": "evm:421018",
  "kind": "amm",
  "protocol": "v2",
  "poolAddress": "0xabc123"
}

    Common errors: VENUE_NOT_FOUND, INFRASTRUCTURE_UNAVAILABLE

    catalog.getDeployment

    Purpose: Deployment manifest for a ledger — contract packages, names, and addresses.

    const manifest = await sdk.catalog.getDeployment('evm:421018')
const manifestByAlias = await sdk.catalog.getDeployment('infinite-mainnet')
    ParameterTypeRequiredDescription
    ledgerLedgerScopeYesWhich ledger to fetch the manifest for — ID or alias from your config (e.g. infinite-mainnet).

    Returns: DeploymentManifest — see Types — DeploymentManifest

    Example response:

    {
  "ledger": {
    "id": "evm:421018",
    "kind": "evm",
    "chainId": 421018,
    "alias": "infinite-mainnet"
  },
  "version": "1.0.0",
  "updatedAt": "2026-07-01T00:00:00Z",
  "contracts": [
    {
      "package": "dex",
      "contract": "Router",
      "address": "0xrouter",
      "access": "public"
    }
  ]
}

    Common errors: MANIFEST_NOT_FOUND, LEDGER_NOT_SUPPORTED, INFRASTRUCTURE_UNAVAILABLE

    telemetry

    Aggregated market views and time series keyed by Nutrimatic IDs. Use when you already have a venueId or instrumentId.

    telemetry.getAmmView

    Purpose: Telemetry summary for one AMM venue (same shape as easy.read.getPoolView, direct by ID).

    const view = await sdk.telemetry.getAmmView('evm:421018:amm:v2:0x…')
    ParameterTypeRequiredDescription
    venueIdVenueIdYesNutrimatic venue ID for the pool (from catalog.listVenues or a pair’s venueId).

    Returns: AmmTelemetryView — same fields as easy.read.getPoolView

    Example response:

    {
  "venueId": "evm:421018:amm:v2:0xabc123",
  "spot": {
    "value": 1.04,
    "baseInstrumentId": "evm:421018:instrument:42",
    "quoteInstrumentId": "evm:421018:instrument:usdt",
    "asOf": 1719795600
  },
  "change24h": { "value": 0.8 },
  "tvlUsd": 1250000,
  "volume24hUsd": 84000
}

    Common errors: VENUE_NOT_FOUND, INFRASTRUCTURE_UNAVAILABLE

    telemetry.getCandles

    Purpose: OHLCV candles for a specific venue — same window semantics as easy.read.getChart, addressed by venueId when you already resolved the pool.

    See Chart windows for bootstrap, tail refresh, and backward paging.

    const bootstrap = await sdk.telemetry.getCandles('evm:421018:amm:v2:0x…', '1h', {
  limit: 300,
})

const tail = await sdk.telemetry.getCandles('evm:421018:amm:v2:0x…', '1h', {
  after: 1719792000,
})
    ParameterTypeRequiredDescription
    venueIdVenueIdYesNutrimatic venue ID for the pool (from catalog.listVenues or a pair’s venueId).
    intervalCandleIntervalYesCandle bucket size — how much time each bar covers: '15m' | '1h' | '4h' | '1d' | '1w'. Unavailable intervals → CAPABILITY_NOT_AVAILABLE.
    query.limitnumberNoMax closed candles to return (newest within window). Default 300 if omitted; cap 1000. See Chart windows.
    query.afternumberNoUnix seconds — closed candles with time greater than this value (tail refresh); use lastClosedCandleTime(series.candles)
    query.beforenumberNoUnix seconds — closed candles with time less than this value (page backward with limit); use firstClosedCandleTime(series.candles)
    query.scope'default' | 'partialOnly'No'partialOnly' — only partialCandle; candles always []. See Chart windows — scope

    Returns: CandleSeries — see Types — CandleSeries. Merge with mergeCandleSeries.

    Example response:

    {
  "venueId": "evm:421018:amm:v2:0xabc123",
  "interval": "1h",
  "priceAxisLabel": "42/USDT",
  "asOf": 1719795600,
  "candles": [
    { "time": 1719792000, "open": 1.02, "high": 1.05, "low": 1.01, "close": 1.04 }
  ],
  "partialCandle": {
    "time": 1719795600,
    "open": 1.04,
    "high": 1.06,
    "low": 1.03,
    "close": 1.05
  }
}

    Common errors: VENUE_NOT_FOUND, NORMALIZATION_FAILED, INFRASTRUCTURE_UNAVAILABLE

    telemetry.getInstrumentView

    Purpose: Telemetry for one instrument by ID — same shape as easy.read.getTokenPrice (price, optional market, optional supply).

    const view = await sdk.telemetry.getInstrumentView('evm:421018:instrument:42')
    ParameterTypeRequiredDescription
    instrumentIdInstrumentIdYesNutrimatic instrument ID for the token (from catalog.listInstruments, or a pair’s baseInstrumentId/quoteInstrumentId).

    Returns: InstrumentTelemetryView

    Example response:

    {
  "instrumentId": "evm:421018:instrument:42",
  "priceUsd": 1.04,
  "change24h": { "value": 2.3 },
  "market": {
    "volume24hUsd": 125000,
    "liquidityUsd": 890000
  },
  "supply": {
    "asOf": 1753072800,
    "total": { "raw": "100451001124521553982862588", "decimals": 18 },
    "holders": { "count": 176 }
  }
}

    Common errors: INSTRUMENT_NOT_FOUND, LEDGER_NOT_SUPPORTED, INFRASTRUCTURE_UNAVAILABLE

    telemetry.getVenueFeed

    Purpose: Discrete event feed for a venue — trades, liquidity changes, and other supported kinds. Use when you know venueId.

    See Activity feeds for bootstrap, tail refresh, and FeedQuery semantics.

    const feed = await sdk.telemetry.getVenueFeed('evm:421018:amm:v2:0x…', { limit: 50 })

const tradesOnly = await sdk.telemetry.getVenueFeed('evm:421018:amm:v2:0x…', {
  limit: 50,
  kinds: ['trade'],
})
    ParameterTypeRequiredDescription
    venueIdVenueIdYesNutrimatic venue ID for the pool (from catalog.listVenues or a pair’s venueId).
    query.limitnumberNoMax events to return (newest within window). Default 50 if omitted; cap 200. See Activity feeds.
    query.afterFeedCursorNoOnly events after this cursor — tail refresh; pass lastFeedCursor(feed.events).
    query.beforeFeedCursorNoOnly events before this cursor — page backward; use together with query.limit.
    query.scope'default' | 'headOnly'No'headOnly' — live edge only; events always []. See Activity feeds — scope
    query.kindsFeedEventKind[]NoRestrict to specific event kinds (e.g. ['trade', 'liquidity_add']). Omit to receive every kind this venue supports.

    Returns: VenueFeed — see Types — VenueFeed. Merge with mergeFeedSeries.

    Example response:

    {
  "scopeId": "evm:421018:amm:v2:0xabc123",
  "scopeKind": "venue",
  "ordering": "asc",
  "asOf": 1719795600,
  "events": [
    {
      "eventId": "evt_trade_01",
      "time": 1719795500,
      "kind": "trade",
      "ledgerId": "evm:421018",
      "txHash": "0xabc123def456",
      "actor": "0xuser000000000000000000000000000000000001",
      "venueId": "evm:421018:amm:v2:0xabc123",
      "price": 2.48,
      "baseAmount": 1.5,
      "quoteAmount": 3.72,
      "side": "sell"
    },
    {
      "eventId": "evt_lp_01",
      "time": 1719795550,
      "kind": "liquidity_add",
      "ledgerId": "evm:421018",
      "txHash": "0xdef789abc012",
      "actor": "0xuser000000000000000000000000000000000001",
      "venueId": "evm:421018:amm:v2:0xabc123",
      "amount": 1000,
      "baseAmount": 50,
      "quoteAmount": 52
    }
  ]
}

    Common errors: VENUE_NOT_FOUND, INFRASTRUCTURE_UNAVAILABLE

    telemetry.getTrades

    Purpose: Trade-only feed for a venue — equivalent to getVenueFeed with kinds: ['trade'] implicit.

    const feed = await sdk.telemetry.getTrades('evm:421018:amm:v2:0x…', { limit: 50 })

    Available when trade history is supported for the venue.

    ParameterTypeRequiredDescription
    venueIdVenueIdYesNutrimatic venue ID for the pool (from catalog.listVenues or a pair’s venueId).
    query.limitnumberNoMax trades to return (newest within window). Default 50 if omitted; cap 200. See Activity feeds.
    query.afterFeedCursorNoOnly trades after this cursor — tail refresh; pass lastFeedCursor(feed.events).
    query.beforeFeedCursorNoOnly trades before this cursor — page backward; use together with query.limit.
    query.scope'default' | 'headOnly'No'headOnly' — live edge only; events always []. See Activity feeds — scope

    Returns: TradeFeed — see Types — TradeFeed and TradeView.

    Example response:

    {
  "scopeId": "evm:421018:amm:v2:0xabc123",
  "scopeKind": "venue",
  "ordering": "asc",
  "asOf": 1719795600,
  "events": [
    {
      "eventId": "evm:421018:swap:0xabc…:12",
      "time": 1719795600,
      "kind": "trade",
      "ledgerId": "evm:421018",
      "txHash": "0xabc123def456",
      "actor": "0xuser000000000000000000000000000000000001",
      "venueId": "evm:421018:amm:v2:0xabc123",
      "price": 1.04,
      "baseAmount": 250,
      "quoteAmount": 260,
      "side": "buy"
    }
  ]
}

    Common errors: VENUE_NOT_FOUND, INFRASTRUCTURE_UNAVAILABLE

    venues

    Live AMM state for a pool. Served by Telemetry API as GET /venues/{venueId}/state and GET /venues/{venueId}/spot (catalog identity remains GET /venues/{venueId}).

    venues.getAmmState

    Purpose: Current reserves and spot rate for a pool.

    const state = await sdk.venues.getAmmState('evm:421018:amm:v2:0x…')
    ParameterTypeRequiredDescription
    venueIdVenueIdYesNutrimatic venue ID for the pool (from catalog.listVenues or a pair’s venueId).

    Returns: AmmVenueState

    FieldTypeDescription
    venueIdVenueIdThe pool this state is for — echoes your venueId input.
    reservesQuantity[]Current on-chain token reserves for each side of the pool, as raw (smallest-unit) integers with decimals. Convert to display units before showing in the UI.
    spotRateCurrent spot exchange rate between base and quote, computed directly from reserves. Display as-is; re-fetch for updates rather than caching.

    Example response:

    {
  "venueId": "evm:421018:amm:v2:0xabc123",
  "reserves": [
    { "raw": "1000000000000000000", "decimals": 18 },
    { "raw": "1040000000", "decimals": 6 }
  ],
  "spot": {
    "value": 1.04,
    "baseInstrumentId": "evm:421018:instrument:42",
    "quoteInstrumentId": "evm:421018:instrument:usdt",
    "asOf": 1719795600
  }
}

    Common errors: VENUE_NOT_FOUND, INFRASTRUCTURE_UNAVAILABLE

    venues.getSpotRate

    Purpose: Current spot rate only (lighter than full state when you only need price).

    const rate = await sdk.venues.getSpotRate('evm:421018:amm:v2:0x…')
    ParameterTypeRequiredDescription
    venueIdVenueIdYesNutrimatic venue ID for the pool (from catalog.listVenues or a pair’s venueId).

    Returns: Rate — see Types — Rate

    Example response:

    {
  "value": 1.04,
  "baseInstrumentId": "evm:421018:instrument:42",
  "quoteInstrumentId": "evm:421018:instrument:usdt",
  "asOf": 1719795600
}

    Common errors: VENUE_NOT_FOUND, INFRASTRUCTURE_UNAVAILABLE

    Related

    GoalStart here
    OHLCV windows and mergeChart windows
    Trade / venue event feedsActivity feeds
    Swap, LP, settlementWrite operations
    Balances, portfolio, stake, farmBalances · Positions · Staking · Farming
    Whose balance / positions to loadWhose wallet (owner)
    Response shapesTypes
    Method namingNaming conventions
    Config and modesConfiguration
    Module mapPackages
    ErrorsErrors
    Whose wallet (`owner`)Chart windows