@capxul/sdk 2.3.1 → 2.4.0

package/README.md

@@ -43,6 +43,28 @@ if ("kind" in amount) {
 `parseMoney` returns validation errors as values. `formatMoney` rejects a
 malformed `Money` record with `INVALID_INPUT`.
 
+## The asset a screen shows
+
+`holdings.primary` picks the one asset a hero balance or a summary total
+should show. It returns the renderable holding with the largest available
+balance. A chain row that carries no `decimals`, no `symbol`, or a symbol that
+stands for no supported currency is skipped, because it cannot be rendered.
+
+```ts
+import { formatMoney, type Holding } from "@capxul/sdk";
+
+const result = await client.holdings.primary();
+
+if (result.ok && result.value !== null) {
+  const holding: Holding = result.value;
+  console.log(holding.symbol); // "USDX" — the token symbol the chain reported
+  console.log(formatMoney(holding.available, { grammar: "code" })); // e.g. "1,250.50 USD"
+}
+```
+
+`null` means no row is renderable. It is a value, not an error, so give the
+screen its own rule for showing nothing.
+
 ## Observability
 
 Hosts can attach the PostHog client they already initialized through one