@stable_sea/sdk 0.2.8 → 0.2.10

package/README.md

@@ -207,7 +207,24 @@ 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
+## Transaction receipts and settlement references
+
+Retrieve `GET /v1/transactions/{id}` with `money:read` for `financial_details`:
+the same input/output, fee, net trade value, fund price and commission figures
+as Terminal. Values use decimal strings. `estimated: true` means a figure can
+change; false does not prove settlement. Optional `quoted` values are the native
+receipt's comparison figures, with the currently disclosed fee held constant
+for net trade comparisons. They are not necessarily the original order quote.
+Deposit and withdrawal sections separate principal, fees, collection and
+delivery. Fee refunds preserve their original collection history.
+
+Input and output identify their `chain` and your `bank_account_id` or
+`external_wallet_id` when applicable. Use `accounts:read` to retrieve linked
+account details. Removed, internal and other businesses' accounts have no resource link.
+
+Missing figures are omitted. A movement initiated by another business may affect
+your balances without exposing its financial details. List responses omit receipt
+enrichment; use `asset_changes` to reconcile settled balance effects.
 
 Retrieve `GET /v1/transactions/{id}` with `money:read` to see
 `onchain_transactions`. Each observed reference includes its `hash` and, when

package/dist/gen/schema.d.ts

@@ -534,10 +534,10 @@ export interface paths {
         get: operations["orders.list"];
         put?: never;
         /**
-         * Place a fund order
-         * @description Creates a fund order for the authenticated business and returns it as `pending`. Execution is asynchronous and uses the same authorization checks and trading engine as Terminal. Retrieve the order to follow it through `executing` to `filled` or `failed`.
+         * Place an order
+         * @description Creates an order for the authenticated business and returns it as `pending`. BTC orders require both `investments:write` and `investments:btc_write` and use standard settlement. The BTC quote is indicative; execution uses the current native price and fees. Execution is asynchronous and uses the same authorization checks and trading engine as Terminal. Retrieve the order to follow it through `executing` to `filled` or `failed`.
          *
-         *     The quoted price is checked against the NAV at execution. Price changes and insufficient express liquidity can cause execution to fail. The failed order includes a reason. While the quote remains valid, an express refusal can be submitted as a new standard order.
+         *     Fund orders check the quoted NAV at execution. Price changes and insufficient express liquidity can cause execution to fail. The failed order includes a reason. While the quote remains valid, an express refusal can be submitted as a new standard order.
          *
          *     Use a Live key with the production URL or a Test key with the sandbox URL. A credential environment this host does not serve returns `environment_not_served` before an order or idempotency record is created.
          */
@@ -628,8 +628,8 @@ export interface paths {
             cookie?: never;
         };
         /**
-         * Price a fund trade
-         * @description Returns a price to include when placing a fund order. Quotes are calculated on request, have no ID and cannot be retrieved later.
+         * Price a trade
+         * @description Returns an indicative price for BTC or a fund. Quotes have no ID and cannot be retrieved later. BTC prices use the latest unexpired native quote; reading one does not extend its expiry. Calculated BTC quote amounts are rounded to at most 18 decimal places. Actual trade amounts are determined at execution. BTC quotes include `platform_fee_usdc`, `fee_bps`, `net_usdc` and the `net_estimated_quantity` after the buy fee. `minimum_amount_usd` states the BTC order minimum. A BTC quote does not guarantee the execution price. Fund orders include the quoted NAV.
          *
          *     `express` describes the commission, order limit, estimated quantity and settlement estimate for express settlement. These terms do not guarantee available liquidity. An express order may fail at execution; while the quote remains valid, you can submit a new standard order using the same quoted price. Standard settlement changes the commission and delivered quantity, not the quoted price.
          */
@@ -894,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.
          *
+         *     `financial_details` contains Terminal's receipt amounts, fees and trade figures for a movement initiated by your business. Input and output identify their blockchain and link to your bank account or external wallet when applicable; retrieve linked account details with `accounts:read`. Internal and other businesses' accounts have no resource link. Missing figures are omitted. Amounts are decimal strings; `estimated: true` means a figure can change, while false does not prove settlement. Optional `quoted` figures follow Terminal's comparison precision; a net trade comparison holds the currently disclosed fee constant and is not necessarily the original order quote. Status, settled changes and financial details share one read snapshot. Refund totals describe the assessed movement; a fee-refund transaction links to it in `original_transaction_id`.
+         *
          *     `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.
@@ -1359,7 +1361,7 @@ export interface components {
                 }[];
                 /** @description Human-readable explanation. Use code or type for programmatic handling. */
                 message?: string;
-                /** @description RFC 6901 JSON Pointer to the first offending field (validation errors). */
+                /** @description RFC 6901 JSON Pointer to the first offending field, on a validation error or a coded error about one field. */
                 param?: string;
                 /** @description Correlates with the Request-Id response header. */
                 request_id?: string;
@@ -1666,23 +1668,25 @@ export interface components {
             /** @enum {string} */
             state: "pending" | "executing" | "filled" | "failed";
             symbol: string;
+            /** @description The booked transaction, or null before a movement is committed. Retrieve it with money:read to follow settlement. A filled order means booked, not settled. */
+            transaction_id: string | null;
         };
         OrderCreateInput: {
-            /** @description The trade size as a decimal string: USD on a buy, shares on a sell. Must be positive. */
+            /** @description The trade size as a decimal string: USD on a buy, asset units on a sell. Must be positive. */
             amount: string;
             /**
              * @description Which side to trade.
              * @enum {string}
              */
             direction: "buy" | "sell";
-            /** @description The price_per_unit from GET /v1/quotes. Execution verifies it against the NAV the trade runs at, so a stale echo is refused rather than filled. */
+            /** @description The price_per_unit from GET /v1/quotes. Fund execution checks the NAV; BTC uses an indicative price and executes at the current native price. */
             quoted_price: string;
             /**
              * @description Settlement mode. Express (instant) carries a commission the standard path does not; see the express terms on GET /v1/quotes. Express draws on a shared reserve, so an express order can be refused at execution and the order reaches a failed state naming why — re-place it as standard against the same unexpired quote.
              * @enum {string}
              */
             settlement: "standard" | "instant";
-            /** @description The fund ticker to trade, e.g. WTGXX. */
+            /** @description The asset ticker, such as BTC or WTGXX. BTC also requires investments:btc_write. */
             symbol: string;
         };
         OrderList: {
@@ -1818,9 +1822,19 @@ export interface components {
             /** Format: date-time */
             expires_ts: string;
             express?: components["schemas"]["QuoteExpress"];
+            /** @description Native BTC platform fee rate, in basis points. */
+            fee_bps?: number | null;
             livemode: boolean;
+            /** @description Minimum BTC order notional in USD, before the platform fee. */
+            minimum_amount_usd?: string;
+            /** @description Estimated BTC received after the buy fee. Omitted on sells. */
+            net_estimated_quantity?: string | null;
+            /** @description USDC allocated to a BTC buy, or estimated sell proceeds, after the fee. */
+            net_usdc?: string;
             /** @enum {string} */
             object: "quote";
+            /** @description Estimated native BTC platform fee in USDC. */
+            platform_fee_usdc?: string;
             price_per_unit: string;
             symbol: string;
         };
@@ -2249,6 +2263,22 @@ export interface components {
             /** @description The asset symbol, in the ledger's own casing (USDC, WTGXX, SOL:USDC). */
             asset: string;
         };
+        TransactionDepositAmounts: {
+            available: boolean;
+            collected_platform_fee_usdc: string;
+            /** @enum {string} */
+            collection_status: "not_needed" | "pending" | "collected" | "failed" | "insufficient_proceeds";
+            estimated: boolean;
+            /** Format: date-time */
+            first_observed_ts: string | null;
+            gross_deposit_usd: string;
+            gross_proceeds_usdc: string;
+            net_usdc: string;
+            platform_fee_usdc: string;
+            pricing_basis: string | null;
+            /** Format: date-time */
+            pricing_ts: string | null;
+        };
         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"][];
@@ -2267,6 +2297,7 @@ export interface components {
              * @description When the movement terminated as failed. Present only when status is failed, and never alongside completed_ts.
              */
             failed_ts?: string;
+            financial_details?: components["schemas"]["TransactionFinancialDetail"];
             /** @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. */
@@ -2286,6 +2317,43 @@ export interface components {
              */
             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";
         };
+        TransactionFeeReturns: {
+            original_transaction_id: string | null;
+            refund_transaction_ids: (string | null)[] | null;
+            refunded: boolean;
+            /** @description Total fee refunds recorded against this movement's assessment. A fee-refund transaction links to the original assessed transaction instead. */
+            refunded_usdc: string;
+            waived: boolean;
+        };
+        TransactionFigure: {
+            amount: string;
+            asset: string;
+            /** @description Whether this figure can still change. False also covers terminal failure and a fund-trade amount fixed at placement; it does not prove settlement. */
+            estimated: boolean;
+            quoted?: components["schemas"]["TransactionValue"];
+        };
+        TransactionFinancialDetail: {
+            automation_id: string | null;
+            deposit?: components["schemas"]["TransactionDepositAmounts"];
+            /**
+             * Format: date-time
+             * @description Pending fund settlement estimate. Null after the native receipt no longer reports an estimate.
+             */
+            estimated_settlement_ts: string | null;
+            fee?: components["schemas"]["TransactionValue"];
+            fee_returns?: components["schemas"]["TransactionFeeReturns"];
+            input?: components["schemas"]["TransactionSide"];
+            net_amount?: components["schemas"]["TransactionFigure"];
+            output?: components["schemas"]["TransactionSide"];
+            price_per_unit?: components["schemas"]["TransactionFigure"];
+            settlement_commission?: components["schemas"]["TransactionValue"];
+            /**
+             * @description Recorded fund settlement choice; null when none was recorded.
+             * @enum {string|null}
+             */
+            settlement_pathway: "standard" | "express" | null;
+            withdrawal?: components["schemas"]["TransactionWithdrawalAmounts"];
+        };
         TransactionList: {
             data: components["schemas"]["Transaction"][];
             has_more: boolean;
@@ -2303,6 +2371,34 @@ export interface components {
             /** @description Observed transaction hash. */
             hash: string;
         };
+        TransactionSide: {
+            amount: string;
+            asset: string;
+            /** @description Your bank-account resource, omitted after removal. Retrieve it with accounts:read for account details. */
+            bank_account_id?: string;
+            /** @description Blockchain used by this ledger leg, when it names one. Internal conversions and bank legs have no chain. */
+            chain?: string;
+            /** @description Whether this figure can still change. False also covers terminal failure and a fund-trade amount fixed at placement; it does not prove settlement. */
+            estimated: boolean;
+            /** @description Your external-wallet resource, omitted after removal. Retrieve it with accounts:read for wallet details. */
+            external_wallet_id?: string;
+            quoted?: components["schemas"]["TransactionValue"];
+        };
+        TransactionValue: {
+            amount: string;
+            asset: string;
+        };
+        TransactionWithdrawalAmounts: {
+            bank_fee_usd: string;
+            collected_platform_fee_usdc: string;
+            /** @enum {string} */
+            collection_status: "not_needed" | "pending" | "collected" | "failed";
+            delivered: boolean;
+            estimated: boolean;
+            paid_to_bank_usd: string;
+            platform_fee_usdc: string;
+            total_debit_usdc: string;
+        };
         USBankAccountCreateDetails: {
             account_number: string;
             /** @enum {string} */
@@ -3750,11 +3846,11 @@ export interface operations {
     "quotes.quote": {
         parameters: {
             query: {
-                /** @description The fund ticker to price, e.g. WTGXX. */
+                /** @description The asset ticker to price, such as BTC or WTGXX. */
                 symbol: string;
                 /** @description Which side to price. */
                 direction: "buy" | "sell";
-                /** @description The trade size as a decimal string: USD on a buy, shares on a sell. Must be positive. */
+                /** @description The trade size as a decimal string: USD on a buy, asset units on a sell. Must be positive. */
                 amount: string;
             };
             header?: never;

package/package.json

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