Skip to content
CTRL K
    Reference
    Balances

    Balances

    Use this module when your UI needs to show how much of a token a wallet holds, whether a spender is already allowed to spend that token, or when the user must approve before another write (swap, stake, farm deposit, etc.).

    Amounts are display decimals (what you show the user), not raw/smallest-unit. approve uses a Wallet adapter.

    Rules

    • Pass owner only when you need a specific address; omit it when a wallet is configured — Whose wallet (owner).
    • approve is its own write. It does not run inside swap, stake, or farm — call it when allowance is too low, then call the other write.
    • After a successful approve, re-read getAllowance (or rely on your next write failing with INSUFFICIENT_ALLOWANCE if you skip the check).
    • approve can incur gas and the service fee when it runs. The SDK does not return a costs list before approve — Fees and costs.

    Where does spender come from?

    spender is the contract address that will move the token after approval (router, staking contract, farm, …). Take it from a known source below — not from placeholder examples.

    SourceWhen
    catalog.getDeploymentLook up the ledger’s DeploymentManifest and use the address for the contract your flow needs (e.g. the Router entry for swaps).
    Product / integration notes from NutrimaticWhen your integration is given a specific spender for a program

    Pass that address into getAllowance and approve. Do not hard-code random addresses from examples (0xspender… is a placeholder).

    balances.getBalance

    How much of one instrument an address holds. Omit owner to use the connected wallet.

    const balance = await sdk.balances.getBalance({
  instrumentId: 'evm:421018:instrument:42',
})

    Parameters

    FieldTypeDescription
    instrumentIdInstrumentIdToken to look up (catalog instrument id).
    ownerstringOptional. Address to query. Omit to use the connected wallet — Whose wallet (owner).

    Returns — Balance

    FieldTypeDescription
    instrumentIdInstrumentIdSame asset you asked for.
    amountstringHeld amount as a display decimal (e.g. "12.5"). Show as-is.
    ownerstringAddress that was queried.
    ledgerLedgerIdCanonical ledger id (never an alias).

    Example response:

    {
  "instrumentId": "evm:421018:instrument:42",
  "amount": "12.5",
  "owner": "0xabc…",
  "ledger": "evm:421018"
}

    balances.getAllowance

    How much of a token a spender (usually a contract) may still move on behalf of the owner. Use this before a write that needs approval, or to decide whether to call approve.

    const allowance = await sdk.balances.getAllowance({
  instrumentId: 'evm:421018:instrument:42',
  spender: '0xspender…',
})

    Parameters

    FieldTypeDescription
    instrumentIdInstrumentIdToken whose allowance you are reading.
    spenderstringContract that may spend — from the deployment manifest (not a made-up address).
    ownerstringOptional. Token owner. Omit to use the connected wallet — Whose wallet (owner).

    Returns — Allowance

    FieldTypeDescription
    instrumentIdInstrumentIdToken this allowance is for.
    ownerstringAddress that owns the tokens.
    spenderstringAddress that may spend.
    amountstringRemaining approved amount (display decimal). "0" means approve (or raise the allowance) before the next write.
    ledgerLedgerIdCanonical ledger id.

    Example response:

    {
  "instrumentId": "evm:421018:instrument:42",
  "owner": "0xabc…",
  "spender": "0xspender…",
  "amount": "0",
  "ledger": "evm:421018"
}

    balances.approve

    Ask the user to allow a spender to use up to amount of a token. Signing uses purpose: 'approve'.

    const handle = await sdk.balances.approve({
  instrumentId: 'evm:421018:instrument:42',
  spender: '0xspender…',
  amount: '100',
})

    Parameters — ApproveRequest

    FieldTypeDescription
    instrumentIdInstrumentIdToken to approve.
    spenderstringWho may spend after this succeeds — same address you used in getAllowance (where it comes from).
    amountstringMax amount to approve (display decimal).
    deadlinenumberOptional. Unix time in milliseconds — do not proceed after this.

    Returns — ExecutionHandle

    Same ExecutionHandle as other writes. Poll settlement.track until confirmed or failed if still running.

    Example response:

    {
  "id": "exec_01HZZ…",
  "status": "confirmed",
  "ledger": "evm:421018",
  "txRef": "0xdef…"
}

    Errors

    READ_ONLY_MODE, CAPABILITY_NOT_AVAILABLE, WALLET_REQUIRED, USER_REJECTED, INSTRUMENT_NOT_FOUND, LEDGER_NOT_SUPPORTED.

    → Whose wallet (owner) · Positions · Staking · Write operations

    LiquidityPositions