Coins paired with a stock

Each is a Token-2022 mint. The key is what tells pairs apart: pair.key on a coin, key in the issuer status and on a trade's stock, and the stock filter. A stock listed here is not always open for new money: open says which are now (Open or closed).

GET /v1/stocks/issuers

Each pinned stock's issuer controls, read on chain and compared with the ones Sapling reviewed: its authorities, whether it is paused, its default account state, its transfer hook, its share multiplier, and the issuer's own keys behind them. A read request (the reads tier), cached for 15 seconds. A 404 while stock pairs are off.

{
  "data": [
    {
      "key": "nvdax",
      "symbol": "NVDAx",
      "mint": "Xsc9qvGR1efVDFGLrVsmkzv3qi45LTBjeUKSPmx9qEh",
      "issuer": "Backed (xStocks)",
      "status": "unchanged",
      "open": true,
      "closed": null,
      "paused": null,
      "changes": [],
      "notices": [
        {
          "what": "scaled UI multiplier step",
          "pinned": "1",
          "now": "1.004 from 2026-11-03 14:30 UTC"
        }
      ],
      "slot": 455760788
    },
    {
      "key": "spyx",
      "symbol": "SPYx",
      "mint": "XsoCS1TfEyfFhfvj8EtZ528L3CaKBDBRqRapnBbDF2W",
      "issuer": "Backed (xStocks)",
      "status": "changed",
      "open": false,
      "closed": {
        "reason": "issuer-changed"
      },
      "paused": "Backed (xStocks) changed SPYx's issuer controls. New SPYx pairs and buys are paused until it is reviewed. Selling stays open.",
      "changes": [
        {
          "what": "paused",
          "pinned": "false",
          "now": "true"
        }
      ],
      "notices": [],
      "slot": 455760788
    },
    {
      "key": "spcx",
      "symbol": "SPCX",
      "mint": "SPCXxcqXj6e5dJDVNovHN8744zkbhM2bYudU45BimGb",
      "issuer": "Backpack Securities",
      "status": "unchanged",
      "open": false,
      "closed": {
        "reason": "stock-switch-off"
      },
      "paused": null,
      "changes": [],
      "notices": [],
      "slot": 455760788
    }
  ],
  "readable": true
}

• status: "unchanged" or "changed".
• open and closed: whether new money can go into the stock now, and if not why (Open or closed).
• paused: the line Sapling shows while the stock is paused, or null while it is unchanged.
• changes: what differs from the review, each as what, pinned (what the review holds) and now (what the chain holds). Empty while unchanged.
• notices: what moved without pausing anything, in the same shape.
• slot: the slot the chain was read at.
• readable: false when the chain could not be read; data is then empty. Treat every stock as paused until it reads again, as sapling.cash does.

What a change can name

• A role: mint authority, freeze authority, permanent delegate, transfer hook authority, transfer hook program, pause authority, scaled UI multiplier authority, metadata pointer authority, metadata update authority, confidential transfer authority, group member pointer authority, mint close authority, transfer fee config authority, withheld withdraw authority.
• The mint's state: paused, default account state, scaled UI multiplier (a move outside the normal step), the mint (it no longer reads as the reviewed Token-2022 mint).
• One of the issuer's own keys behind a role: a wallet that is no longer a plain wallet, a multisig's threshold, time lock, config authority or members, a program's upgrade authority or a redeploy. Its what names the address.

What a notice can name

• scaled UI multiplier step: a normal step of the share multiplier (as for a dividend): one increase of at most 2%, taking effect within 2 days. Anything else is a change. pinned is the multiplier in force, now reads "<next> from YYYY-MM-DD HH:MM UTC".
• confidential transfer auto approve: the flag turned "on" or "off".

A coin paired with a stock carries pair on every coin answer: GET /v1/coins, /v1/coins/search, /v1/coins/{mint}, /v1/graduations, and a Zcash account's holdings on GET /v1/accounts/{W} (read only there: the account's orders do not trade it; its valueZec is null while the coin has no ZEC value). Its kind is "stock"; its key is the stock's.

"pair": {
  "key": "nvdax",
  "kind": "stock",
  "symbol": "NVDAx",
  "name": "tokenized Nvidia",
  "issuer": "Backed (xStocks)",
  "quoteMint": "Xsc9qvGR1efVDFGLrVsmkzv3qi45LTBjeUKSPmx9qEh",
  "decimals": 8,
  "tokenProgram": "TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb",
  "open": true,
  "closed": null,
  "controls": {
    "freeze": true,
    "permanentDelegate": true,
    "pause": true,
    "scaledUi": true,
    "hook": true
  },
  "disclosure": [
    "NVDAx is issued by Backed.",
    "Its issuer can pause it, freeze an account that holds it, and move or burn it from any account.",
    "If that happens, this coin cannot be bought or sold until it stops, and any NVDAx in its liquidity can be taken by the issuer.",
    "Sapling turns its own NVDAx fees into ZEC every few minutes."
  ],
  "multiplier": "1",
  "raw": {
    "priceE9": "…",
    "marketCap": "…",
    "volume24h": "…"
  },
  "display": {
    "price": "…",
    "marketCap": "…",
    "volume24h": "…"
  },
  "zec": {
    "available": true,
    "source": "reference",
    "zatPerWholeRawE12": "…"
  }
}

Only the coins paired with a stock

GET /v1/coins?quote=stocks lists only coins paired with a stock, and ?stock=<key> (?stock=nvdax) only those paired with that stock, alone or with quote=stocks; a stock not open yet is taken too. quote is zec, sapling or stocks; stock is one of the keys above, exactly as written. Anything else answers 400 invalid_param, as a wrong sort or stage does. GET /v1/trades takes the same two.

Units

• pair.raw: the stock's raw base units, as the chain holds them, the multiplier not applied. priceE9 is per whole token × 1e9. /v1/coins/{mint} adds volumeTotal and creatorFees.
• pair.display: the same amounts × the multiplier in force ÷ 10^decimals, rounded down, for showing only. null when the mint could not be read (multiplier is then null too).
• Every field named …Zec is the raw amount valued at the stock's ZEC value now. pair.zec says how: zatPerWholeRawE12 (zat per whole raw unit × 10^12) from the vault's own rate memory ("reference") or, when that cannot be read, the last conversion the vault made ("realised").
• When neither exists, pair.zec.available is false and the coin's ZEC-named fields are null. Nothing is guessed.
• Sorting by market cap or volume values a stock coin in ZEC the same way, at 0 while it has no ZEC value.
• open and closed: as in the issuer status, for the coin's stock (Open or closed).
• disclosure is the stock's plain disclosure, one sentence per line, exactly as sapling.cash shows it.

On GET /v1/coins/{mint}/trades and GET /v1/trades, a stock coin's trade keeps zec, creatorFeeZec and priceZecE9, valued at the stock's ZEC value now (null while there is none), and adds stock: the stock's key and what the chain moved, raw and for display.

"stock": {
  "key": "nvdax",
  "symbol": "NVDAx",
  "decimals": 8,
  "raw": {
    "amount": "…",
    "creatorFee": "…",
    "priceE9": "…"
  },
  "display": {
    "amount": "…",
    "creatorFee": "…",
    "price": "…"
  }
}

On GET /v1/coins/{mint}/candles a stock coin's o, h, l, c and volumeZec are valued the same way, and each candle adds raw: o, h, l, c and volume in the stock's raw base units.

Every stock pair block and every issuer status row carries open: true while new money (a planting, a buy) can go into the stock now. When it is false, closed.reason says why; closed is null while open. Whatever the reason, a holder can always leave: the coin's reads (the coin, its trades, candles and holders) answer as ever, and selling stays open.

Answers that carry open are cached for at most 15 seconds and never served stale.

• GET /v1/coins/{mint}/quote and /v1/coins/{mint}/fees answer 404 not_found for a stock coin, and its holder-reward runs are not listed.
• A Sapling Wallet buy order of a stock coin (POST /v1/zcash/quote, /v1/zcash/orders) answers 404 coin_unknown.
• The plant, trade and swap builds have no stock route, and GET /v1/params names no stock.

Plant and trade stock coins on sapling.cash.

The SDK reads stock coins only, as the API does: coins.list and trades take quote and stock (a StockKey, the 44 keys above), stocks.issuers() reads GET /v1/stocks/issuers, Coin.pair is a StockCoinPair with open and closed, and STOCK_PINS holds each stock's mint, decimals and issuer keys; it quotes, builds and verifies no stock coin trade.