@stable_sea/sdk 0.2.23 → 0.2.25

package/README.md

@@ -61,6 +61,44 @@ fails with `network_required`, and a BTC order with one fails with
 `network_not_applicable`. Sandbox settles on `ethereum`. Instant settlement is
 available on `ethereum` only.
 
+## Check trading pathways
+
+Use `investments:read` to retrieve your business's observed pathway availability,
+limits, express-buy commission rate and settlement estimates. Test keys read their
+sandbox business. Observations include `observed_ts` and expire within one minute;
+missing or expired observations return 503. Availability is advisory and independent
+of order size. Orders recheck current eligibility and liquidity. Use a quote for
+amount-specific prices and fees.
+
+```ts
+const pathways = await client.GET("/v1/trading_pathways", {
+  params: { query: { symbol: "WTGXX", direction: "buy" } },
+});
+if (pathways.error) throw new Error(pathways.error.error.message);
+console.log(pathways.data.data[0]?.cash_subscription);
+```
+
+## Subscribe to WTGXX with a wire
+
+Eligible businesses can use the existing order resource with
+`funding_method: "wire"`, `symbol: "WTGXX"`, `direction: "buy"`,
+`settlement: "standard"`, `network: "ethereum"` and `quoted_price: "1"`.
+`amount` is the USD subscription amount. Use the existing `investments:write`
+permission to submit, `investments:read` to retrieve the order and `money:read`
+to read its transaction. Omitted `funding_method` continues to use USDC balances.
+
+Save a mutation object and reuse its exact body and key after a lost response.
+Retrieve the order until `transaction_id` is available, then read
+`GET /v1/transactions/{id}`. `financial_details.cash_subscription` carries progress,
+the amount and recorded wire instructions. Send funds only when the stage is
+`awaiting_funds` and instructions are available. A `filled` order means the
+instruction was booked; use the transaction's status to confirm settlement.
+
+An uncertain provider outcome stays `processing`. Keep reading the same transaction;
+do not place another subscription to resolve it. Instructions can lag the native
+state: retry a 503 read. Sandbox instructions are synthetic and must never be used
+to send real funds. Existing native eligibility, agreements and controls apply.
+
 ## Member administration and personal actions
 
 Use `createStableSeaSessionClient` for onboarding, legal documents, your profile
@@ -68,7 +106,9 @@ and security, team and API-key administration, notifications, preferences and
 business support messages. It uses
 the native sign-in, MFA and business-selection flow,
 not a Live or Test API key. Use `https://api.stablesea.com`; the isolated
-Test-key Sandbox does not serve member sessions.
+Test-key Sandbox does not serve member sessions. Test approval review and
+business-rule management use this same business client and session. Your existing
+member permissions apply.
 
 ```ts
 import { createStableSeaSessionClient } from "@stable_sea/sdk";
@@ -89,6 +129,12 @@ does not perform authentication, cookie storage or retries automatically.
 Existing login MFA, business membership, locks and permissions remain in force.
 Member requests do not use the dated financial API contract header.
 
+Read `GET /money/trades/pathways` with the member client and query parameters
+`symbol` and `direction` before entering a trade amount. It returns the same
+pathway availability and settlement estimates shown in Terminal. WTGXX buys
+include cash-subscription availability and the minimum USD amount. These reads
+are advisory; quotes and submissions apply current eligibility and controls.
+
 Member writes use `member.POST`, with each native operation's retry behavior.
 They have no financial `mutation()` helper. Key creation and rotation require
 an `Idempotency-Key`; other operations retain their documented native retry
@@ -115,6 +161,12 @@ invitee's email-link token; administrators cannot accept on their behalf.
 Member grants and activation use existing business permissions. Policy settings
 retain their separate launch gate.
 
+Before suspending or removing a member, read
+`GET /identity/members/{individual_id}/approval_dependencies` to see which rules,
+approver choices and pending requests need their sign-off. Your session must be
+allowed to manage permissions. Counts remain available when it cannot read the
+corresponding details.
+
 Read a member's active keys at
 `GET /identity/members/{individual_id}/api_keys`, selecting `environment: "live"`
 or `"test"`. Suspending or removing the member leaves those business keys working;
@@ -136,6 +188,90 @@ advisory, not proof of authentication.
 Generated types are exported as `SessionPaths`, `SessionOperations` and
 `SessionComponents`; internal operator and excluded product operations are omitted.
 
+## Approval policies
+
+Use the member client with the same permissions as Terminal. Read business rules
+and the current approver roster at `/money/approval_rules`. Permission managers
+can save a complete replacement `rules` array with `POST` while `writes_enabled`
+is true. Every accepted save creates a version; an empty array clears the rules.
+Send an `Idempotency-Key` to prevent duplicate versions and notices: a repeated
+key returns 409, and reusing it with a different body returns 400. Read the current
+version after an uncertain response. This also applies to Test rule saves. The legacy
+Terminal `PUT` is outside the supported member contract.
+
+Read a member's `/identity/members/{id}/action_settings`, then save its current
+`revision` as `expected_revision` with the intended permission/action patch.
+Grants and member policy save atomically. Omitted fields stay unchanged; a null
+action clears its override while preserving business rules. Reload and review a
+revision conflict. The `/action_settings/preview` read evaluates current server
+valuation and requirements; it does not authorize execution.
+
+These operations retain native deployment availability and require no additional
+action-specific MFA. An API key cannot act as a permission manager. See the
+[policy guide](https://docs.stablesea.com/api/#approval-policies) for examples.
+
+## Submit and review member trades
+
+Use the member client to quote `GET /money/trades/quote`, then submit
+`POST /money/trades/buy` or `/money/trades/sell`. Buy amounts are USDC; sell
+amounts are asset units. A fund submission echoes the quote's `price_per_unit`
+as `quoted_price_per_unit` for immediate execution. A pending request uses a
+fresh checker quote when approved. The optional quote flag `include_approval_preview`
+returns current member requirements and any known submission refusal; it grants
+no authority. BTC fee estimates are at `/money/trades/btc/fee_preview`.
+
+Save and supply an `Idempotency-Key` for each intended submission. Native
+submission returns 409 for duplicate keys, rather than replaying a cached
+response. After an uncertain response, use `GET /money/trade_submissions` with
+`direction` and the original `idempotency_key`. With transaction-view permission,
+you can read your own current approval and any booked transaction. A booked
+transaction can accompany a pending approval when its final decision is unresolved. A 404 is
+inconclusive: the request may still be in flight or its lookup may have expired.
+Keep the original key and reconcile history before using another one. The member
+client does not automatically retry or use the financial mutation helper.
+Current member permissions, business eligibility and financial controls still
+apply. `outcome=approval_pending` includes the saved `transfer_approval` without
+booking a movement; `outcome=created` includes the movement and transaction.
+These are human-session submissions, not API-key human identities.
+
+## Review approval requests
+
+Use the member client to read `GET /money/transfer_approvals`. Transfer approvers
+see the business queue; other eligible business members see their own requests.
+Filter by `status`, paginate with `next_cursor` as `cursor`, or use `request_id`
+alone to retrieve one request of any age. An empty result can mean the request
+does not exist or is outside your visibility.
+
+Review the saved instruction, expiry and current approval requirements before
+voting. For a fund request, create a checker-bound quote with
+`POST /money/transfer_approvals/{id}/quotes`, then submit its `quote_key` to
+`POST /money/transfer_approvals/{id}/approve` before the quote expires. Withdrawal
+approvals use the same approve route with an empty body. A successful vote can
+leave the request pending until its remaining requirements are met.
+
+Use the corresponding `/deny` action to refuse an eligible request; `/cancel`
+is reserved for its requester. These actions use the current signed-in member
+and native controls, with no additional factor code. An API key cannot vote.
+After an uncertain response or a duplicate-vote conflict, read the request before
+deciding what to do next. Member operations do not use the financial mutation
+helper. See the [approval guide](https://docs.stablesea.com/api/#approval-requests)
+for examples and retry behavior.
+
+For Test requests, use `/money/test_transfer_approvals` and the corresponding
+`/{id}/quotes`, `/{id}/approve`, `/{id}/deny` and `/{id}/cancel` actions.
+Read or replace Test business rules at `/money/test_approval_rules`; retrieve
+versions at `/money/test_approval_rules/history`. Keep the business API URL and
+signed-in session. Requests and rules use your business's isolated Test data.
+In Terminal, select **Test** in Approvals or Approval rules.
+
+For a member's isolated Test financial policies, use
+`/identity/test_members/{id}/action_settings` (GET/POST) and
+`/identity/test_members/{id}/action_settings/preview` (GET). Test saves accept
+`actions`, `expected_revision` and `policy_schema_version`; they cannot change
+permission grants. Membership and permissions stay shared with Live. The current
+source permissions are shown in the read response and remain the ceiling for
+Test actions. In Terminal, select **Test** on the member's settings page.
+
 ## Business onboarding and documents
 
 Use the member client before issuing an API key. Signup uses the existing

package/dist/gen/schema.d.ts

@@ -860,6 +860,28 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/v1/trading_pathways": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * Read trading pathways
+         * @description Returns the authenticated business's observed trading pathways, published limits, express-buy commission rate and settlement estimates. Requires `investments:read`. The `data` array contains the selected symbol and direction.
+         *
+         *     Observations are refreshed in the background and are served for at most one minute. Availability is advisory and independent of order size. It does not authorize a trade: current permissions, agreements, network settings, limits and liquidity are checked when an order executes. Express, instant and cash-subscription pathways use Ethereum. Test keys read their isolated sandbox business. Missing or expired observations return 503. Use a quote for amount-specific pricing and fees.
+         */
+        get: operations["trading_pathways.snapshot"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/v1/transactions": {
         parameters: {
             query?: never;
@@ -1283,6 +1305,12 @@ export interface components {
             /** @enum {string} */
             status: "pending" | "succeeded" | "failed";
         };
+        CashSubscriptionPathway: {
+            available: boolean;
+            min_order_usd: string;
+            /** @enum {string} */
+            network: "ethereum";
+        };
         Decimal: string;
         Deposit: {
             /** Format: date-time */
@@ -1666,11 +1694,18 @@ export interface components {
         };
         Order: {
             amount: string;
+            /** @description The linked human approval request, or null before a request is created. Use the member client's approval operations to review it. API keys cannot cast human votes. The reference remains available after the order finishes. */
+            approval_request_id: string | null;
             /** Format: date-time */
             created_ts: string;
             /** @enum {string} */
             direction: "buy" | "sell";
             failure_code?: string;
+            /**
+             * @description How the purchase is funded: balance uses available USDC; wire uses the fund's cash-subscription instructions.
+             * @enum {string}
+             */
+            funding_method?: "balance" | "wire";
             /** @description The order id. Stable for the life of the order and safe to store. */
             id: string;
             livemode: boolean;
@@ -1685,7 +1720,7 @@ export interface components {
             /** @enum {string} */
             settlement: "standard" | "instant";
             /** @enum {string} */
-            state: "pending" | "executing" | "filled" | "failed";
+            state: "pending" | "pending_approval" | "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;
@@ -1698,6 +1733,11 @@ export interface components {
              * @enum {string}
              */
             direction: "buy" | "sell";
+            /**
+             * @description Defaults to balance, using available USDC. Wire opens a cash subscription and is supported only for a standard WTGXX buy on ethereum; retrieve its transaction for funding instructions.
+             * @enum {string}
+             */
+            funding_method?: "balance" | "wire";
             /**
              * @description The network a fund order settles on. Required for a fund order and refused for BTC, which settles on no network. The API never applies a business's default network.
              * @enum {string}
@@ -2405,6 +2445,42 @@ export interface components {
             fee: string;
             paid_to_bank: string;
         };
+        TradingPathwayAvailability: {
+            /** @description Advisory availability at observed_ts. Execution rechecks eligibility and liquidity. */
+            available: boolean;
+            /** @description Published express-buy commission rate. Omitted when no rate is configured. */
+            fee_bps?: number | null;
+            max_order_usd?: string;
+            /** @enum {string} */
+            network: "ethereum";
+        };
+        TradingPathwayOptions: {
+            cash_subscription?: components["schemas"]["CashSubscriptionPathway"];
+            /** @enum {string} */
+            direction: "buy" | "sell";
+            express_buy?: components["schemas"]["TradingPathwayAvailability"];
+            express_settlement?: components["schemas"]["TradingPathwaySettlement"];
+            instant_sell?: components["schemas"]["TradingPathwayAvailability"];
+            /** @enum {string} */
+            object: "trading_pathway";
+            standard_settlement?: components["schemas"]["TradingPathwaySettlement"];
+            /** @enum {string} */
+            symbol: "BTC" | "WTGXX" | "FLTTX" | "WTSIX";
+        };
+        TradingPathwaySettlement: {
+            settlement_duration_minutes?: number | null;
+            settlement_trading_days?: number | null;
+            /** Format: date-time */
+            settlement_ts: string;
+        };
+        TradingPathways: {
+            data: components["schemas"]["TradingPathwayOptions"][];
+            livemode: boolean;
+            /** @enum {string} */
+            object: "trading_pathways";
+            /** Format: date-time */
+            observed_ts: string;
+        };
         Transaction: {
             /** @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"][];
@@ -2446,6 +2522,28 @@ export interface components {
             /** @description The asset symbol, in the ledger's own casing (USDC, WTGXX, SOL:USDC). */
             asset: string;
         };
+        TransactionCashSubscription: {
+            /** @description The USD amount recorded for the subscription. */
+            amount_usd: string;
+            /** @description True when an order exists without recorded receiving-bank instructions. */
+            instructions_pending: boolean;
+            /**
+             * @description Subscription progress. Send funds only while this is awaiting_funds.
+             * @enum {string}
+             */
+            stage: "processing" | "awaiting_funds" | "shares_delivered" | "order_not_completed" | "funds_returned" | "expired";
+            wire_instructions?: components["schemas"]["TransactionCashWireInstructions"];
+        };
+        TransactionCashWireInstructions: {
+            bank_name?: string | null;
+            beneficiary_account_number?: string | null;
+            beneficiary_name?: string | null;
+            funding_account_last_four?: string | null;
+            funding_bank_name?: string | null;
+            reference_note: string;
+            routing_number?: string | null;
+            swift_or_bic?: string | null;
+        };
         TransactionDepositAmounts: {
             available: boolean;
             collected_platform_fee_usdc: string;
@@ -2517,6 +2615,7 @@ export interface components {
         };
         TransactionFinancialDetail: {
             automation_id: string | null;
+            cash_subscription?: components["schemas"]["TransactionCashSubscription"];
             deposit?: components["schemas"]["TransactionDepositAmounts"];
             /**
              * Format: date-time
@@ -4464,6 +4563,45 @@ export interface operations {
             };
         };
     };
+    "trading_pathways.snapshot": {
+        parameters: {
+            query: {
+                symbol: "BTC" | "WTGXX" | "FLTTX" | "WTSIX";
+                direction: "buy" | "sell";
+            };
+            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"]["TradingPathways"];
+                };
+            };
+            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"];
+                };
+            };
+        };
+    };
     "transactions.list": {
         parameters: {
             query?: {