Settlement

Use this page after a write returns an ExecutionHandle and you need to know when that operation is finished — for example, when to stop a loading spinner.

If the handle is already confirmed or failed, you are done — refresh your UI from the read APIs. Otherwise call settlement.track with handle.id until the status is confirmed or failed.

You poll status. You do not run bridges, hops, or plan steps yourself — Nutrimatic does that. You only sign what your WalletAdapter is asked to sign.

Multi-step and cross-ledger plans are part of the contract shape; today’s documented ledger is Infinite Mainnet (EVM). Tracking an existing id is a status read on that execution — it does not start a new write.

Signing across steps

A multi-step path may require more than one signature. The SDK calls WalletAdapter.sign again when a later step needs it (purpose may be 'settlement' or the write’s purpose). Your adapter should treat each SignRequest independently — sign what is asked, or reject with USER_REJECTED. You never submit steps yourself.

Polling

While status is still running (pending, submitted, or in_progress):

• Call settlement.track(handle.id) on an interval you choose (many UIs use ~1–2s; back off if you see repeated INFRASTRUCTURE_UNAVAILABLE).
• Stop when confirmed or failed.
• If you get CAPABILITY_NOT_AVAILABLE, stop and show the error — do not keep polling.

Status vocabulary

Handle, settlement, and each plan step use the same status values — ExecutionStatus:

Stop polling when status is confirmed or failed.

When to call settlement.track

Overview of the write flow: Write operations.

settlement.track

const status = await sdk.settlement.track(handle.id)

Parameters

Returns — SettlementStatus

Each entry in steps:

Rules

• Overall status is the source of truth for “am I done?”. Do not infer completion from a single step.
• When both path and steps are present, steps[i] describes path.steps[i].
• path on settlement matches the plan for this execution. It may echo the quote’s path; treat either as UI context, not as something you execute.
• A failed overall status means the execution failed — show failure and stop. You do not retry individual steps through the SDK.

Example response (plan still running; first step confirmed):

{
  "id": "exec_01HZY…",
  "status": "in_progress",
  "updatedAt": 1719799300000,
  "path": {
    "steps": [
      {
        "instrumentId": "evm:421018:instrument:42",
        "venueId": "evm:421018:amm:v2:0xabc123",
        "ledger": "evm:421018"
      },
      {
        "instrumentId": "evm:421018:instrument:usdt",
        "venueId": "evm:421018:amm:v2:0xdef456",
        "ledger": "evm:421018"
      }
    ]
  },
  "steps": [
    {
      "index": 0,
      "status": "confirmed",
      "ledger": "evm:421018",
      "txRef": "0xabc…"
    },
    {
      "index": 1,
      "status": "submitted",
      "ledger": "evm:421018"
    }
  ]
}

Path

A Path is Nutrimatic’s ordered plan when a quote or execution is not a single pool hop — for example several hops on one ledger, or steps that touch more than one ledger.

You may see it on:

Integrator contract

• Read-only for your UI (progress, labels, which assets/venues are involved).
• You never submit, reorder, or skip steps.
• Presence of path on a quote means you should plan to call settlement.track after the write until status is confirmed or failed.
• Absence of path usually means a single-step route — you may still need settlement.track if the handle is still running.

interface PathStep {
  readonly instrumentId: InstrumentId
  readonly venueId?: VenueId
  readonly ledger?: LedgerId
}

interface Path {
  readonly steps: readonly PathStep[]
}

Example (two hops):

{
  "steps": [
    {
      "instrumentId": "evm:421018:instrument:42",
      "venueId": "evm:421018:amm:v2:0xabc123",
      "ledger": "evm:421018"
    },
    {
      "instrumentId": "evm:421018:instrument:usdt",
      "venueId": "evm:421018:amm:v2:0xdef456",
      "ledger": "evm:421018"
    }
  ]
}

Errors

Other failures may be specific to the tracked id. See Errors — When to use which code.

→ Write operations · Swaps · Types — Execution