REST API›Wallet & Transact›Wallet

GET

List a wallet's shielded notes

Serves the ZEC/TZEC Ironwood pool — the ZIP-229 successor to Orchard; the indexer extracts Ironwood actions only, so notes received via legacy Orchard are not listed. By default only UNSPENT notes are returned; request PENDING_SPEND or SPENT explicitly to observe the indexer's recorded pending or spent notes. The page reflects the indexer's persisted on-chain state only: a note locked by one of the wallet's in-flight transactions (pending transaction requests, signed or unconfirmed transfers) still appears UNSPENT here until its spend is indexed — spend selection applies its own in-flight reservation, so treat the listing as observed value, not a spendability guarantee. The response proxies one page of the indexer's shielded-unspents listing — nextBatchPrevId is present only when the page came back full; feed it back as prevId for the next page. Coin-generic: any coin without shielded capability answers 400.

the shielded unspents listing; the request/response codecs here are the OpenAPI source of truth

Path Params

  • coin string required
    Coin or token identifier (e.g. zec, tzec)
  • walletId string required
    Wallet ID to list shielded unspents for

Query Params

  • limit string number
    Limit the number of results. Values above 2000 are clamped at the wallet-platform boundary (mirroring the transparent unspents endpoint), not rejected; values below 1 or non-integers are rejected with a 400.

    >= 1 · <= 2000

    Defaults to 500

  • prevId string
    Continuation cursor: the nextBatchPrevId value from a previous response — the note commitment (cmx) of the last note on that page. Values that are not hex-shaped are rejected with a 400 at the wallet-platform boundary before the indexer is called.

    at least 1 characters

  • spendState string enum
    Spend state of the notes to list, as persisted by the indexer. This is the indexer's on-chain state only: unlike the transparent unspents endpoint, which excludes outputs locked in the send queue, this listing cannot exclude notes already selected by the wallet's in-flight transactions — such a note still appears UNSPENT until its spend is indexed (spend selection applies its own reservation). A PENDING_SPEND note is excluded from the default listing even if its spending transaction later fails; request that state explicitly to see it.

    Defaults to UNSPENT

    UNSPENTPENDING_SPENDSPENT
  • minValue string
    The minimum value of notes to return (in zatoshi). Must be a non-negative integer string (/^\d+$/); anything else is rejected with a 400 at the wallet-platform boundary before the indexer is called.

    at least 1 characters

Responses

200
OK

Response Body

object

  • notes array of objects required
    notes object
    • id string required
      The note commitment — the note's stable natural id.
    • address string required
      The shielded address that received the note.
    • valueString string required
      Note value in zatoshi as a decimal string (never a JSON number).
    • blockHeight number required
      Height of the block containing the note's action.
    • date string required
      ISO-8601 UTC timestamp. Always present, including for unconfirmed notes (hasLeafPosition=false): the indexer derives it from createdAt, which its ZECShieldedNote schema marks required (indexerdb-microservice-utxo#405) — so t.string (not nullable) matches the wire contract.
    • spendState string enum required
      The note's spend state — the indexer's persisted on-chain state, not wallet-platform's in-flight transaction state (see ShieldedSpendState).
      UNSPENTPENDING_SPENDSPENT
    • hasLeafPosition boolean required
      True once the indexer has assigned the note a note-commitment-tree position — a position indicator, not a standalone spendability signal: actual spendability also depends on the note's anchor height and on in-flight spends (pending nullifiers).
    • txid string required
      The transaction that created the note.
    • direction string enum required
      Whether the note was received by the wallet (incoming) or created by a wallet spend (outgoing) — an outgoing note's value belongs to its recipient, not to the wallet the note is listed under.
      incomingoutgoing
  • nextBatchPrevId string
    The ID from where the results can continue; absent means end of results.
400
Bad Request

Response Body

object

  • name string
    Error code
  • context map of objects required
    Properties that apply to a specific error name
    context object
    • <key> object
  • error string required
    Human-readable error message
  • requestId string required
    Client request id