@stable_sea/sdk 0.2.5 → 0.2.8

package/README.md

@@ -182,16 +182,64 @@ 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).
+
+## Transaction settlement references
+
+Retrieve `GET /v1/transactions/{id}` with `money:read` to see
+`onchain_transactions`. Each observed reference includes its `hash` and, when
+known, `chain` and `explorer_url`. An empty array means no references have been
+observed; null means the metadata is unavailable, including a receipt initiated
+by another business. List responses omit this detail.
+
+A hash is a settlement reference, not proof that the whole movement completed.
+Check the transaction's `status` and `asset_changes` for its lifecycle and effect
+on settled balances. Sandbox references use simulated partner data.
+
 ## 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

@@ -651,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;
@@ -817,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;
@@ -888,6 +894,8 @@ export interface paths {
          *
          *     The status is `pending`, `processing`, `completed` or `failed`. `completed_ts` and `failed_ts` are mutually exclusive and absent while execution is pending or processing.
          *
+         *     `onchain_transactions` includes observed hashes, their blockchain when known, and available explorer links for movements initiated by your business. An empty array means no hashes have been observed; null means references are unavailable for this read. Lists omit these details.
+         *
          *     Unknown and cross-business IDs return the same not-found response.
          */
         get: operations["transactions.get"];
@@ -1848,20 +1856,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;
@@ -1895,6 +2030,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;
@@ -1902,6 +2054,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;
@@ -2006,6 +2160,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";
@@ -2093,12 +2249,60 @@ export interface components {
             /** @description The asset symbol, in the ledger's own casing (USDC, WTGXX, SOL:USDC). */
             asset: string;
         };
+        TransactionDetail: {
+            /** @description Signed net changes to settled holdings, one entry per asset, ordered by asset. Empty when no part has settled. A failed movement includes any changes that settled before failure; pending or processing status alone does not determine whether this array is empty. */
+            asset_changes: components["schemas"]["TransactionAssetChange"][];
+            /**
+             * Format: date-time
+             * @description When the last leg settled. Present only when status is completed, and never alongside failed_ts.
+             */
+            completed_ts?: string;
+            /**
+             * Format: date-time
+             * @description When the movement was opened. Immutable, and the instant this list is ordered and paged on.
+             */
+            created_ts: string;
+            /**
+             * Format: date-time
+             * @description When the movement terminated as failed. Present only when status is failed, and never alongside completed_ts.
+             */
+            failed_ts?: string;
+            /** @description The transaction id. Stable for the life of the movement and safe to store. */
+            id: string;
+            /** @description Whether the resource represents live financial data. False for an isolated simulated ledger; independent of the reading credential. */
+            livemode: boolean;
+            /** @enum {string} */
+            object: "transaction";
+            /** @description Observed on-chain settlement references for a movement initiated by your business. Empty when none have been observed; null when unavailable. */
+            onchain_transactions: components["schemas"]["TransactionOnchainReference"][] | null;
+            /**
+             * @description The movement lifecycle: pending before execution starts; processing while at least one part is in flight; completed when all parts settle; failed when execution ends unsuccessfully. A failed movement can have settled changes, reported in asset_changes.
+             * @enum {string}
+             */
+            status: "pending" | "processing" | "completed" | "failed";
+            /**
+             * @description What the movement is. The whole vocabulary a transaction can carry is published; a business only ever sees the members its own activity produces. Pay-ins and payouts are never served on this API.
+             * @enum {string}
+             */
+            type: "ach_offramp" | "ach_onramp" | "adjustment" | "buy_fund_token" | "buy_fund_token_return" | "buy_fund_token_return_sweep" | "deposit_hold" | "deposit_return" | "deposit_reversal" | "fund_cash_subscription" | "fund_dividend_payout" | "fund_distribution_payout" | "fund_gas_tank" | "fund_xlm_reserve" | "gas_tank_refill" | "gas_wallet_funding" | "go_account_conversion" | "go_account_custodial_transfer" | "go_account_external_send" | "held_deposit_release" | "onchain_deposit" | "onchain_withdrawal" | "ramp_fee_refund" | "reclassification" | "sell_fund_token" | "sell_fund_token_return" | "trade_order" | "treasury_booking" | "treasury_wire_credit" | "wire_offramp" | "wire_onramp";
+        };
         TransactionList: {
             data: components["schemas"]["Transaction"][];
             has_more: boolean;
             /** @enum {string} */
             object: "list";
         };
+        TransactionOnchainReference: {
+            /** @description Blockchain identifier, such as ethereum or stellar. Omitted when the hash cannot be attributed to a blockchain. */
+            chain?: string;
+            /**
+             * Format: uri
+             * @description Block-explorer URL, when available. Otherwise use the hash as plain text.
+             */
+            explorer_url?: string;
+            /** @description Observed transaction hash. */
+            hash: string;
+        };
         USBankAccountCreateDetails: {
             account_number: string;
             /** @enum {string} */
@@ -4002,7 +4206,7 @@ export interface operations {
                     [name: string]: unknown;
                 };
                 content: {
-                    "application/json": components["schemas"]["Transaction"];
+                    "application/json": components["schemas"]["TransactionDetail"];
                 };
             };
             400: components["responses"]["Error400"];

package/package.json

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