Skip to content
CTRL K
    Reference
    Positions

    Positions

    Use this module for a portfolio / “my positions” screen: one list of liquidity, product-token stake, and farm deposits.

    This is read-only. Layout, refresh, and which write to run next are yours (Liquidity, Staking, Farming). Nutrimatic does not auto-compound or run strategies.

    Position kinds

    kindWhat it meansNext write module
    lpLiquidity in a poolLiquidity
    stakeProduct-token stake (catalog instrument) — not native chain / validator delegationStaking
    farmDeposit in a farm / liquidity-mining programFarming

    Rules

    • Prefer listPositions for a mixed portfolio. Use staking / farming reads when the screen is only stake or only farm.
    • Pass owner only when you need a specific address; omit it when a wallet is configured — Whose wallet (owner).
    • Optional fields (instrumentId, venueId, farmId, claimableReward) appear when they apply to that kind. Missing claimableReward means none to show — not "0".
    • After a write that changes a position, call listPositions or getPosition again. The write handle confirms the operation; the position list is what you show in the portfolio UI.

    positions.listPositions

    Load the rows for a portfolio table. Filter by kind or ledger when the screen only shows one slice.

    const rows = await sdk.positions.listPositions({
  kinds: ['lp', 'stake', 'farm'],
  ledgers: ['infinite-mainnet'],
})

    Parameters — ListPositionsQuery

    FieldTypeDescription
    ownerstringOptional. Whose positions to list. Omit to use the connected wallet — Whose wallet (owner).
    ledgersLedgerScope[]Optional. Limit to these ledgers (id or alias, e.g. infinite-mainnet).
    kindsPositionKind[]Optional. Only these kinds. Omit for every kind returned for this owner.

    Returns — Position[]

    FieldTypeDescription
    idPositionIdOpaque id — pass to getPosition or use as your row key.
    kindPositionKindlp, stake, or farm — which detail screen or write module to open.
    ledgerLedgerIdCanonical ledger for this row.
    ownerstringAddress that owns the position.
    amountstringPrincipal / shares as a display decimal.
    instrumentIdInstrumentIdOptional. Main asset (staked token, LP share, …).
    venueIdVenueIdOptional. Pool when kind is lp.
    farmIdFarmIdOptional. Farm when kind is farm.
    claimableRewardobjectOptional. Pending reward: instrumentId + display amount. Hide claim when absent or "0".

    Example response:

    [
  {
    "id": "pos_lp_01…",
    "kind": "lp",
    "ledger": "evm:421018",
    "owner": "0xabc…",
    "amount": "1000",
    "venueId": "evm:421018:amm:v2:0xabc123",
    "instrumentId": "evm:421018:instrument:lp-42-usdt"
  },
  {
    "id": "pos_stake_01…",
    "kind": "stake",
    "ledger": "evm:421018",
    "owner": "0xabc…",
    "amount": "250",
    "instrumentId": "evm:421018:instrument:42",
    "claimableReward": {
      "instrumentId": "evm:421018:instrument:42",
      "amount": "1.25"
    }
  },
  {
    "id": "pos_farm_01…",
    "kind": "farm",
    "ledger": "evm:421018",
    "owner": "0xabc…",
    "amount": "10",
    "farmId": "farm_01H…",
    "claimableReward": {
      "instrumentId": "evm:421018:instrument:42",
      "amount": "0.4"
    }
  }
]

    positions.getPosition

    Fetch one row by id (detail page or refresh after a write).

    const position = await sdk.positions.getPosition('pos_stake_01…')

    Parameters

    FieldTypeDescription
    idPositionIdPosition id from a previous listPositions (or another Nutrimatic response).

    Returns — Position

    Same fields as each element in listPositions.

    Example response:

    {
  "id": "pos_stake_01…",
  "kind": "stake",
  "ledger": "evm:421018",
  "owner": "0xabc…",
  "amount": "250",
  "instrumentId": "evm:421018:instrument:42",
  "claimableReward": {
    "instrumentId": "evm:421018:instrument:42",
    "amount": "1.25"
  }
}

    Errors

    CAPABILITY_NOT_AVAILABLE, WALLET_REQUIRED, LEDGER_NOT_SUPPORTED.

    → Whose wallet (owner) · Balances · Staking · Farming

    BalancesStaking