@stable_sea/sdk 0.2.4 → 0.2.7

package/README.md

@@ -182,16 +182,52 @@ and wire transfers use the instructions returned by funding.
 See [the funding guide](../../docs/api/funding.md) for the complete sequence,
 permissions and retry behavior.
 
+## Read fund details
+
+Use `investments:read` with `GET /v1/securities` to read each listed fund's
+profile, NAV, returns, holdings and issuer information.
+
+```ts
+const funds = await client.GET("/v1/securities");
+if (funds.error) throw new Error(funds.error.error.message);
+const fund = funds.data.data.find((item) => item.ticker === "WTGXX");
+console.log(fund?.details?.nav);
+console.log(fund?.details?.month_end_returns);
+```
+
+Figures preserve Terminal's display formatting. Each section has its own source
+dates; missing figures and sections are empty or null, never estimated. Returns
+keep the fund and benchmark series separate, with independent cumulative and
+annual-return dates. Fund token addresses identify the issuer's token, not a
+customer deposit destination.
+
+Check `details_observed_ts`: references refresh every five minutes. Missing,
+failed or older-than-ten-minutes observations return `details: null`; the fund's
+registry metadata remains available. These figures are informational. Use a
+quote to obtain the price for a trade. See the
+[securities reference](https://docs.stablesea.com/api/reference/#GET/v1/securities).
+
 ## Statement previews
 
 Read the current month's interim document with
 `client.GET("/v1/statements/preview")` and `money:read`. Its display-ready
-balances, transactions and fees use the same native calculation as Terminal.
+balances, captured charts, transactions and fees use the same native calculation as Terminal.
 Values refresh about once a minute. Check `observed_ts`; missing,
 stale or previous-month previews return 503. Opening balances remain provisional
 until the previous month's statement is issued. Issued documents continue to use
 `GET /v1/statements/{id}`.
 
+## Statement charts
+
+Issued statements and current-month previews include `chart`. Each daily point
+has `sampled_ts`, `total_usd`, `formatted` and an `assets` list containing
+`symbol`, `usd` and `formatted`. USD values are decimal strings from the stored
+plotting figures; display labels are preserved. These figures are for the
+statement chart, not exact ledger calculations. Issued charts are immutable;
+preview charts update with the document. An empty array means no captured series
+was stored. A null chart is unavailable, including a fresh older preview awaiting
+its first chart refresh. The document's captured financial figures remain readable.
+
 ## Contract changes
 
 - `GET /v1/balances`: `chain` gains the value `solana`. A USDC balance held on

package/dist/gen/schema.d.ts

@@ -596,6 +596,30 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/v1/price_history": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * Read market price history
+         * @description Returns the BTC/USD market-price chart used by Terminal for the last thirty days, ninety days or current UTC year. Prices are decimal strings and do not depend on your holdings. The series contains about fifty samples, carrying forward the latest cached close at or before each sample. The underlying market-data cache retains ninety days, so a year-to-date request can contain a shorter available history.
+         *
+         *     Inspect `source`: `historical` means normalized historical prices, `spot` means a flat two-point line at the current price because history was unavailable, and `unavailable` means no prices were available. A spot fallback does not describe past prices.
+         *
+         *     The worker refreshes this observation about once a minute. `observed_ts` is the calculation start; the reads are not an atomic market snapshot. Missing, failed or older-than-two-minutes observations return HTTP 503. Requires `investments:read`.
+         */
+        get: operations["price_history.snapshot"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/v1/quotes": {
         parameters: {
             query?: never;
@@ -627,7 +651,11 @@ export interface paths {
         };
         /**
          * List securities
-         * @description Returns every fund available on this API. The list is identical for every caller and is not paged. A fund appearing here is not by itself an assurance that a given account may trade it.
+         * @description Lists supported funds and their profile, NAV, returns, holdings and issuer information. The catalog is the same for all businesses and does not use pagination. Trading remains subject to your business's eligibility and controls.
+         *
+         *     Figures use Terminal's display formatting. Each section has its own source dates and may have been read at a different time. Null sections and empty values mean unavailable data, not zero. Use `/v1/quotes` for a tradable price.
+         *
+         *     Details refresh every five minutes. `details_observed_ts` records when the latest refresh began. Details are null if unavailable, if the latest refresh failed, or if the last refresh began more than ten minutes ago. Basic fund metadata remains available.
          */
         get: operations["securities.catalog"];
         put?: never;
@@ -793,7 +821,9 @@ export interface paths {
         };
         /**
          * Retrieve a statement
-         * @description Returns the immutable issued statement values as display-ready JSON. Corrected statements remain retrievable and name their replacement. Pay-ins and payouts are not served on this API, so they are not listed in transactions; the balances and totals are the printed ones and still include their effect, which means a statement for a period in which the business made a payment does not reconcile from its transactions alone.
+         * @description Returns the immutable issued statement values as display-ready JSON. Corrected statements remain retrievable and name their replacement. `chart` contains the document's captured daily USD series and display labels. Plotting values are decimal strings, not exact ledger amounts. Older documents without a stored chart return an empty array.
+         *
+         *     Pay-ins and payouts are not served on this API, so they are not listed in transactions; the balances and totals are the printed ones and still include their effect, which means a statement for a period in which the business made a payment does not reconcile from its transactions alone.
          */
         get: operations["statements.retrieve"];
         put?: never;
@@ -1567,6 +1597,25 @@ export interface components {
             holder_identifier?: string;
             legal_entity_name: string;
         };
+        MarketPricePoint: {
+            close_usd: string;
+            /** Format: date-time */
+            sampled_ts: string;
+        };
+        MarketPriceSeries: {
+            /** @enum {string} */
+            asset: "BTC";
+            /** @enum {string} */
+            object: "market_price_series";
+            points: components["schemas"]["MarketPricePoint"][];
+            /** @enum {string} */
+            quote_asset: "USD";
+            /**
+             * @description historical is the normalized market series. spot is a flat current-price fallback, not historical observations. unavailable carries no points.
+             * @enum {string}
+             */
+            source: "historical" | "spot" | "unavailable";
+        };
         /** @description Customer metadata. Sensitive data is forbidden. */
         Metadata: {
             [key: string]: string;
@@ -1746,6 +1795,19 @@ export interface components {
         };
         /** @enum {string} */
         PolicyWindowKind: "calendar_day" | "calendar_week" | "rolling_24h" | "rolling_72h";
+        PriceHistorySnapshot: {
+            data: components["schemas"]["MarketPriceSeries"][];
+            /** Format: date-time */
+            end_ts: string;
+            livemode: boolean;
+            /** @enum {string} */
+            object: "price_history";
+            /** Format: date-time */
+            observed_ts: string;
+            /** Format: date-time */
+            start_ts: string;
+            window: components["schemas"]["BalanceHistoryWindow"];
+        };
         Quote: {
             amount_usd: string;
             /** @enum {string} */
@@ -1792,20 +1854,147 @@ export interface components {
         };
         Security: {
             asset_class: string;
+            details: components["schemas"]["SecurityDetails"];
+            /**
+             * Format: date-time
+             * @description When the latest fund details began refreshing. Each section has its own source date; this is not a quote timestamp.
+             */
+            details_observed_ts: string | null;
+            /** @description Native headline percent string, without a percent sign; empty when unavailable. */
+            expense_ratio_percent: string;
             is_money_market: boolean;
             minimum_investment: string;
+            /** @description Display name from current issuer data, or the fund registry when issuer data is unavailable. Use ticker as the identifier. */
             name: string;
             /** @enum {string} */
             object: "security";
             provider: string;
             /** @description The fund ticker, e.g. WTGXX. */
             ticker: string;
+            /** @description The headline yield's source date (YYYY-MM-DD), or empty when unavailable. */
+            yield_as_of: string;
+            /** @description Native headline percent string, without a percent sign; empty when unavailable. */
+            yield_percent: string;
+        };
+        SecurityAccrual: {
+            accrual_per_share: string;
+            daily_accrued: string;
+            /** Format: date-time */
+            date_ts: string | null;
+            shares_outstanding: string;
+            total_unpaid_accrued: string;
         };
         SecurityCatalog: {
             data: components["schemas"]["Security"][];
             /** @enum {string} */
             object: "list";
         };
+        SecurityContent: {
+            description_html: string;
+            disclosures: components["schemas"]["SecurityDisclosure"][];
+            why_fund_html: string;
+        };
+        SecurityDetails: {
+            accrued_income: components["schemas"]["SecurityAccrual"][];
+            characteristics: components["schemas"]["SecurityFacts"];
+            content: components["schemas"]["SecurityContent"];
+            distributions: components["schemas"]["SecurityDistribution"][];
+            holdings: components["schemas"]["SecurityHoldings"];
+            liquidity: components["schemas"]["SecurityLiquidity"][];
+            month_end_returns: components["schemas"]["SecurityReturns"];
+            nav: components["schemas"]["SecurityNAV"];
+            profile: components["schemas"]["SecurityFacts"];
+            quarter_end_returns: components["schemas"]["SecurityReturns"];
+            token_addresses: components["schemas"]["SecurityTokenAddress"][];
+        } | null;
+        SecurityDisclosure: {
+            /** @description Native sanitized, issuer-approved disclosure HTML. */
+            html: string;
+            title: string;
+        };
+        SecurityDistribution: {
+            /** Format: date-time */
+            ex_ts: string | null;
+            /** Format: date-time */
+            payable_ts: string | null;
+            per_share: string;
+            /** Format: date-time */
+            record_ts: string | null;
+        };
+        SecurityFact: {
+            /** @description Stable fact identifier, such as expense_ratio or minimum_investment. Select facts by key rather than display label. */
+            key: string;
+            label: string;
+            /** @description Native display value, including units and formatting. */
+            value: string;
+        };
+        SecurityFacts: {
+            /**
+             * Format: date-time
+             * @description This section's own source date. Null means no date was published.
+             */
+            as_of_ts: string | null;
+            data: components["schemas"]["SecurityFact"][];
+        };
+        SecurityHolding: {
+            name: string;
+            weight_percent: string;
+        };
+        SecurityHoldings: {
+            /** Format: date-time */
+            as_of_ts: string | null;
+            data: components["schemas"]["SecurityHolding"][];
+        } | null;
+        SecurityLiquidity: {
+            amortized_nav: string;
+            daily_liquid_percent: string;
+            /** Format: date-time */
+            date_ts: string | null;
+            market_nav: string;
+            net_cash_flow: string;
+            weekly_liquid_percent: string;
+        };
+        SecurityNAV: {
+            /** Format: date-time */
+            as_of_ts: string | null;
+            change: string;
+            change_percent: string;
+            value: string;
+        } | null;
+        SecurityReturn: {
+            five_year: string;
+            name: string;
+            one_month: string;
+            one_year: string;
+            /** @description Source series kind, normally NAV for the fund or Benchmark for its index. Name is a display label. */
+            related_type: string;
+            since_inception_annualized: string;
+            since_inception_cumulative: string;
+            ten_year: string;
+            three_month: string;
+            three_year: string;
+            ytd: string;
+        };
+        SecurityReturns: {
+            /**
+             * Format: date-time
+             * @description Independent source date for average annual returns.
+             */
+            as_of_avg_annual_ts: string | null;
+            /**
+             * Format: date-time
+             * @description Source date for cumulative returns.
+             */
+            as_of_ts: string | null;
+            /** @description Percent display strings. Empty values were not published; they are not zero. */
+            data: components["schemas"]["SecurityReturn"][];
+        } | null;
+        SecurityTokenAddress: {
+            /** @description The fund token's contract or issuer address, not a customer deposit destination. */
+            address: string;
+            /** @description Issuer's network label for this fund token. */
+            chain: string;
+        };
         SourceWalletDeclaration: {
             /** @description Recorded screening outcome, once processed. Recheck funding for current eligibility; retries do not renew clearance. */
             cleared: boolean | null;
@@ -1839,6 +2028,23 @@ export interface components {
             period_start_ts: string;
             superseded_by?: string;
         };
+        StatementChartAsset: {
+            /** @description The asset's original display label. */
+            formatted: string;
+            symbol: string;
+            /** @description Stored USD plotting value as a decimal string. */
+            usd: string;
+        };
+        StatementChartPoint: {
+            /** @description Captured USD values by symbol, sorted by symbol. A missing asset was absent from this sample; it is not a new valuation. */
+            assets: components["schemas"]["StatementChartAsset"][];
+            /** @description The total's original display label. */
+            formatted: string;
+            /** Format: date-time */
+            sampled_ts: string;
+            /** @description Stored USD plotting value as a decimal string. This is a display figure, not an exact ledger amount. */
+            total_usd: string;
+        };
         StatementCommission: {
             amount: string;
             label: string;
@@ -1846,6 +2052,8 @@ export interface components {
         };
         StatementDetail: {
             balances: components["schemas"]["StatementLine"][];
+            /** @description Captured daily USD chart, including the closing point. Values and display labels come from this document; they are not recomputed from current balances. An empty array means no chart was stored; null means the captured chart is unavailable. */
+            chart: components["schemas"]["StatementChartPoint"][] | null;
             /** Format: date-time */
             created_ts: string;
             id: string;
@@ -1950,6 +2158,8 @@ export interface components {
         };
         StatementPreview: {
             balances: components["schemas"]["StatementLine"][];
+            /** @description Daily USD chart captured with this preview, including its closing point. Plotting values are decimal strings; display labels match the native document. Null means the chart is unavailable; an empty array means no series was captured. */
+            chart: components["schemas"]["StatementChartPoint"][] | null;
             livemode: boolean;
             /** @enum {string} */
             object: "statement_preview";
@@ -3448,6 +3658,45 @@ export interface operations {
             };
         };
     };
+    "price_history.snapshot": {
+        parameters: {
+            query?: {
+                /** @description Thirty days, ninety days, or the current UTC year to date. */
+                window?: components["schemas"]["BalanceHistoryWindow"];
+            };
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description OK */
+            200: {
+                headers: {
+                    "X-RateLimit-Limit": components["headers"]["X-RateLimit-Limit"];
+                    "X-RateLimit-Remaining": components["headers"]["X-RateLimit-Remaining"];
+                    "X-RateLimit-Reset": components["headers"]["X-RateLimit-Reset"];
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["PriceHistorySnapshot"];
+                };
+            };
+            400: components["responses"]["Error400"];
+            401: components["responses"]["Error401"];
+            403: components["responses"]["Error403"];
+            429: components["responses"]["Error429"];
+            /** @description Error response. */
+            default: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Error"];
+                };
+            };
+        };
+    };
     "quotes.quote": {
         parameters: {
             query: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stable_sea/sdk",
-  "version": "0.2.4",
+  "version": "0.2.7",
   "type": "module",
   "sideEffects": false,
   "files": [