Scope: the documented onchain product

This lesson concerns the onchain Stock Token data described in the Chain developer documentation. EU Classic Stock Tokens are a separate product with their own account and corporate-action rules. Do not apply this calculation to a Classic position merely because the names look similar.

Ask what the number is measuring

A price is incomplete without its unit and timestamp. A Stock Token display can involve the raw token balance, the economic exposure represented by each token and a price describing either the underlying asset or the token. Mixing these surfaces can produce an incorrect portfolio value.

The current API documentation distinguishes raw underlying bid/ask data from multiplier-adjusted onchain pricing. Its wording and examples should be reviewed together; an application must not silently assume that all price surfaces have the same units.

A hypothetical multiplier example

Suppose an invented example has 3 tokens, an underlying reference price of 20 units and a shares-per-token multiplier of 2. Under those assumptions, the reference exposure would be 3 × 2 × 20 = 120 units. If the input price is already adjusted for the multiplier, applying it again would double-count the adjustment.

This is arithmetic for understanding units. It is not a live quote, an executed trade, a promised redemption value or evidence that a particular token can be sold for that amount. Bid/ask, costs, timing and the instrument’s terms still matter.

Price fields, trading status and corporate-action timing

The Stock Token API documentation reviewed 26 October 2026 says `/prices/{symbol}` returns raw underlying-equity bid/ask, not multiplier-adjusted prices. `/assets` provides `currentMultiplier` as an 18-decimal shares-per-token value; the onchain Chainlink feed is multiplier-adjusted. Apply the multiplier once when converting raw underlying price to token-equivalent reference value. The documented `/prices` cache window is 15 seconds; a cache interval is not proof that a quote is current, that an asset is available, or that an order can execute.

Fictional fixture P-01; no endpoint was called: Synthetic capture time (a teaching label, not an API field or response): 2026-10-26T14:00:00Z. Assumed session window: fictional regular US market session, for arithmetic only. The invented `/prices`-shaped fields are `bid: "40.00"`, `ask: "40.20"`, `currency: "USD"`, `isTradingHalt: false`; bid and ask are USD per underlying share to two decimals. The invented `/assets`-shaped values are `currentMultiplier: "0.500000000000000000"` (shares per token, 18 decimal places), `pendingMultiplier: ""` (the docs define empty string as no multiplier change pending), and a holding of `4.000000000000000000` DEMO tokens. DEMO and every value are fictional, not a listed instrument or observed response.

Answer the unit question: raw underlying bid/ask multiplied once by shares per token gives the token-equivalent reference bid/ask: 40.00 × 0.5 = 20.00 USD per token; 40.20 × 0.5 = 20.10 USD per token. For the fictional four-token balance, the corresponding reference values are 80.00 and 80.40 USD before costs. These are not executable quotes or guaranteed proceeds.

Now imagine a separate, later fictional 2-for-1 forward split. The shares-per-token multiplier doubles from 0.500000000000000000 to 1.000000000000000000 while the raw token quantity stays fixed. If the underlying share price halves at the same time, the hypothetical bid/ask become 20.00/20.10 USD per share. The token-equivalent reference remains 20.00/20.10 per token (20.00 × 1.0 and 20.10 × 1.0), and the four-token references remain 80.00/80.40 before costs. This isolates the split arithmetic; it is not a prediction, trade, or guarantee that market prices move exactly this way. The Chainlink value is already multiplier-adjusted, so do not multiply it again.

In this separate later scenario, an in-progress forward-split record could show `oldRate: "0.500000000000000000"`, `newRate: "1.000000000000000000"`, a documented effective time and `pendingMultiplier` while the change is pending; after it takes effect, compare against `currentMultiplier`. Do not combine that later pending state with P-01’s empty `pendingMultiplier`, which says the P-01 snapshot has no pending multiplier change.

Separate unavailable-data case P-02: if a record you are reviewing has a missing or unavailable bid or ask, mark the calculation unavailable; do not substitute zero, reuse an old value, or borrow the multiplier-adjusted Chainlink price as if it were the raw bid/ask. This is a reasoning example, not a claim about the API’s missing-response format.

Show the P-01 and P-02 answer key

P-01: the raw bid and ask are per underlying share; multiply each by the 0.5 shares-per-token value once. At the later hypothetical 2-for-1 split, multiplier 1.0 times a halved underlying bid/ask leaves those token-equivalent references unchanged before costs. The unchanged token quantity does not mean underlying exposure is unchanged. P-02: no usable pair of raw bid/ask values means no calculation. In both cases the fixture cannot establish a real contract, current multiplier, live quote, trading session, halt/availability, fees, liquidity or exit price. The endpoint was not called.

Read metadata before combining values

  1. Identify the asset and its exact deployment on the intended chain.
  2. Determine whether the input describes the underlying security or a token-equivalent value.
  3. Record the multiplier definition and effective time.
  4. Check the quote timestamp, halt/tradability state and whether fields may be missing.
  5. Keep decimal precision and avoid a second multiplier adjustment.

“No data” is different from zero and from “not tradable”. If the data is ambiguous, present the limitation instead of fabricating a price.

Corporate actions can change interpretation

A raw token balance need not move when the represented exposure changes. Use the documented multiplier and corporate-action semantics when reconciling a display. A change in a UI number is not necessarily evidence that tokens were transferred.

API field names or cache behavior can change. Read the current API documentation and test your own consumer before relying on it. This lesson reviewed documentation only: it made no API request and recorded no actual corporate action.

A calculation does not establish ownership rights

Even correct arithmetic cannot turn a tokenized debt security into direct ownership of the underlying share. Keep the instrument’s legal structure, eligibility and redemption conditions alongside any computed display. Numbers answer a valuation question under assumptions; they do not answer every rights question.