Configuration

createNutrimaticSdk accepts a single config object.

Fields

Full example

All fields together (only ledgers, mode, and integrationContext are required):

import { createNutrimaticSdk } from '@nutrimatic/sdk'

const sdk = createNutrimaticSdk({
  apiBaseUrl: 'https://telemetry.nutrimatic.xyz', // optional — omitted by default
  ledgers: [
    { id: 'evm:421018', kind: 'evm', chainId: 421018, alias: 'infinite-mainnet' },
  ],
  mode: 'read',
  integrationContext: 'client', // 'client' | 'backend'
  // wallet: myWalletAdapter, // writes + default owner on portfolio reads
})

apiBaseUrl

Optional. When omitted, the SDK uses the canonical Telemetry host (reads only):

https://telemetry.nutrimatic.xyz

Writes (swaps, etc.) use a separate Gateway host when available — not this URL.

Default (most apps)

Omit apiBaseUrl in config. No extra setup required.

Test or custom Telemetry

Set apiBaseUrl when you point at a test Telemetry host (or your own Telemetry) that serves the same /nutrimatic/v1 paths.

ledgers

Each ledger describes a blockchain Nutrimatic should scope data to. See Supported ledgers for the full list of ledger IDs, kinds, and aliases you can use here.

Declare ledgers once at init; reference them everywhere else by ID or alias. This is the only place you pass the full ledger shape. Every method call after that uses a Ledger scope string instead.

You can list more than one ledger when your app supports multiple chains.

Config rules

The SDK validates your ledger entries when you call createNutrimaticSdk. Invalid config throws at init — not on later method calls.

Example of invalid config: two ledgers sharing the alias infinite-mainnet, or an alias set to evm:421018 when that value is already an id.

Referencing ledgers in method calls

Do not repeat kind or chainId in method parameters. Pass ledger IDs or aliases in a ledgers array:

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

Resolution, deduplication, and error behaviour are documented in Ledger scope.

Modes

The SDK has read operations (charts, prices, feeds, catalog, positions, …) and write operations (swap, liquidity, approve, stake, farm, …). On a write, Nutrimatic prepares the operation, your wallet signs, and Nutrimatic executes.

Choose mode once at init:

If you call a write while mode is 'read', the SDK throws READ_ONLY_MODE. Use 'full' and pass a wallet.

If a write is not available for this config or request, the SDK throws CAPABILITY_NOT_AVAILABLE — do not retry that like a network timeout. See Errors.

→ Write operations · Wallet adapter

wallet

Optional. Bring-your-own WalletAdapter — Nutrimatic does not ship or manage wallets. Pass it when your app runs writes that need a signature, or when portfolio reads omit owner — Whose wallet (owner). Check SignRequest.kind before signing; do not assume every payload is an EVM transaction.

Integration context

integrationContext is where your code runs. Whether writes are allowed is mode.

Errors

Configuration mistakes (for example a missing integrationContext, duplicate ledger aliases, or an alias that collides with a ledger id) throw at init. Runtime failures throw NutrimaticError with a stable code.