Write operations

Writes follow one pattern:

request → quote (when applicable) → sign (WalletAdapter) → execute → track

You never build router calldata or coordinate bridge steps yourself. The SDK asks your WalletAdapter to sign, then Nutrimatic executes.

When is it done? Sometimes the returned handle is already confirmed or failed — stop there and refresh your UI on success. Sometimes it is still running — call settlement.track with handle.id until you get confirmed or failed (that is when you can stop a loading spinner).

Init for writes (including mode and wallet): Configuration — Modes. 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.

Costs: every write can incur network gas and Nutrimatic’s service fee. Only a swap quote returns a costs breakdown before you execute — Fees and costs.

Module map

Goal	Start here
Swap	`routing.quote` → `easy.swap`
Add / remove liquidity	`liquidity.add` / `liquidity.remove`
Balances / approve	`balances`
Portfolio positions (read-only)	`positions`
Product staking	`staking`
Farming / LM	`farming`
Follow a long-running execution	`settlement.track`
Signing	Wallet adapter

routing.quote ──► easy.swap ──► ExecutionHandle
liquidity.*   ──► ExecutionHandle
balances.approve / staking.* / farming.* ──► ExecutionHandle
                      │
                      └── settlement.track(id)  when status is not final yet

One ledger vs several steps

Most swaps and LP ops stay on one ledger. You quote, sign, and execute. If the returned ExecutionHandle is already confirmed or failed, you are done — refresh your UI from the read APIs on success.

The documented surface today ships against Infinite Mainnet (EVM). Multi-hop and cross-ledger path shapes are part of the contract for later ledgers — when a quote includes a path, Nutrimatic may keep working after the first signature. You still only sign what the SDK asks for. Poll settlement.track with handle.id until confirmed or failed.

Your situation	What you do
Handle already `confirmed` or `failed`	Use the handle; refresh reads on success
Handle still running, or quote had a `path`	Poll `settlement.track(handle.id)` until `confirmed` or `failed`

Status values, path fields, and step progress: Settlement. Market ops: Swaps · Liquidity.

After a write

Refresh market UI from read APIs (pool view, price, activity feeds). Feeds are snapshots for confirmation of on-chain activity — not a substitute for ExecutionHandle status.

Errors

Code	Meaning
`READ_ONLY_MODE`	Writes blocked because init used `mode: 'read'` — see Modes.
`CAPABILITY_NOT_AVAILABLE`	This write is not available for this config or request. Do not retry like infra.
`WALLET_REQUIRED`	A `WalletAdapter` is required and none was configured.
`USER_REJECTED`	The user (or adapter) declined to sign.
`QUOTE_EXPIRED`	The quote’s `expiresAt` passed, or the sign request expired before execution.
`SLIPPAGE_EXCEEDED`	Market moved beyond the allowed `slippageBps` (bps) before the trade could settle.
`INSUFFICIENT_ALLOWANCE`	Token spend allowance is too low for this operation.

Full list: Errors.

→ Configuration — Modes · Whose wallet (owner) · Packages — Write path

Live market data Fees and costs