@stable_sea/sdk 0.2.24 → 0.2.26

package/README.md

@@ -340,6 +340,23 @@ const valid = verifyWebhookSignature(
 );
 ```
 
+Subscribe to the lifecycle events you need when creating or updating a webhook
+endpoint:
+
+| Event | Meaning |
+| --- | --- |
+| `transfer_approval.created` | A request is pending human approval. |
+| `transfer_approval.updated` | The request reached a terminal approval state. Partial votes do not emit this event. |
+| `withdrawal.created` | A withdrawal request was accepted. |
+| `withdrawal.updated` | The withdrawal completed, failed or was canceled. A later bank return can produce another update. |
+
+Events contain resource pointers. Retrieve a withdrawal with
+`GET /v1/withdrawals/{id}`; its current state is authoritative. To read an approval,
+use an authenticated member session and query `/money/transfer_approvals` with
+`request_id`, or `/money/test_transfer_approvals` for Test events. Existing member
+visibility applies. API keys cannot cast human votes. Delivery is asynchronous;
+handle duplicate event IDs and changes that arrive out of order.
+
 API request, response, pagination, and error types are generated from
 `services/backend/api/openapi.public.json` and exported as `paths`, `operations`,
 and `components`.
@@ -575,3 +592,43 @@ adopt new/reclassified assets, review `fund_catalog_changes`, then use the curre
 Preview checks saved settings and does not authorize execution. API keys do not
 act as the key owner's member; machine `/v1/policies` remains business controls
 and tiers, without member-policy administration.
+
+
+## Withdraw funds
+
+Create a key with **Withdraw funds** (`money:withdrawals_write`) and **Read money**
+(`money:read`) in Terminal's existing API keys pane. Test keys use the same
+workflow with simulated funds and do not require a two-factor code.
+
+For on-chain withdrawals, list `/v1/external_wallets` and select an enabled saved
+destination. Its `symbol` identifies the withdrawal asset and `payment_rail` the
+network; holdings can contain other assets. Submit `/v1/withdrawals` with
+`method: "onchain"`, `external_wallet` and an amount in that asset's units.
+
+For US ACH or domestic wire, create `/v1/withdrawal_quotes` with `method: "ach"`
+or `"wire"`, the saved `bank_account` ID and a USD decimal amount with at most two fractional digits.
+Retrieve the quote until `status` is `ready`, review `pricing`, then submit
+`/v1/withdrawals` with the same method, bank and amount plus `quote_id`. Quotes
+expire after five minutes and serve one withdrawal. Acceptance queues work without
+booking funds. Processing must begin before `expires_ts`; queue delay or retries
+can produce `quote_invalid`. Pending human approval preserves those fee terms
+after quote expiry.
+
+Use a stable `Idempotency-Key` for each write. Retrieve the withdrawal to follow
+its status. `pending_approval` requires a human decision through the existing
+approval workflow; it reserves no funds. Once booked, `transaction_id` links to
+the native transaction and its settlement details. Request cancellation with
+`POST /v1/withdrawals/{id}/cancel` while pending; `canceling` is not confirmation.
+Wait for `canceled`, or follow the transaction if booking already won the race.
+Cancellation requires the credential that created the withdrawal. A replacement
+key can read the business's withdrawals but cannot cancel its predecessor's requests.
+
+A failed bank payout can require recovery after conversion. `failed` does not
+mean the principal has been refunded or is available to spend. A confirmed ACH
+return also makes the original operation `failed` while preserving its settled
+ledger entries. Read the transaction's `financial_details` for fee recovery;
+a queued fee refund is separate from both principal recovery and a settled refund.
+
+The [Sandbox test project](consumer-test/README.md#test-a-withdrawal) includes
+`npm run test:withdrawal` for a saved Test destination. It preserves request keys
+and receipts so an interrupted run can resume without creating a new withdrawal.

package/dist/gen/schema.d.ts

@@ -1105,6 +1105,114 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/v1/withdrawal_quotes": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Create a withdrawal quote
+         * @description Quotes an ACH or US domestic wire withdrawal to a saved US bank account. No money moves. Poll until ready, then submit the exact method, bank and amount with its quote_id before expiry. One quote serves one withdrawal; retries do not extend expiry. On-chain withdrawals use their saved wallet directly and do not require a bank quote.
+         */
+        post: operations["withdrawal_quotes.create"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/v1/withdrawal_quotes/{id}": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * Retrieve a withdrawal quote
+         * @description Returns a bank withdrawal quote belonging to this business and API mode. Expiry remains fixed even when a ready quote is retrieved again.
+         */
+        get: operations["withdrawal_quotes.get"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/v1/withdrawals": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * List withdrawals
+         * @description Lists this business's API withdrawals, newest first. Filter by method or paginate with one withdrawal ID cursor at a time. Native transaction history remains available separately.
+         */
+        get: operations["withdrawals.list"];
+        put?: never;
+        /**
+         * Create a withdrawal
+         * @description Queues a withdrawal to a saved external wallet or US bank account. Requires money:withdrawals_write and an Idempotency-Key. Reuse the same key and body after a lost response to recover the original request.
+         *
+         *     Eligibility, funds, fees, limits and approval rules are enforced before booking. Pending human approval does not reserve funds; use the member client or Terminal to decide it. Follow status and transaction_id through settlement.
+         *
+         *     For ACH and wire, processing must start before the quote's expires_ts. Queue delay or retries can produce quote_invalid after acceptance. Once human approval is pending, its agreed fees remain valid after quote expiry.
+         */
+        post: operations["withdrawals.create"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/v1/withdrawals/{id}": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * Retrieve a withdrawal
+         * @description Returns one withdrawal, its retained approval reference and its native transaction outcome. A withdrawal belonging to another business or API mode is not found.
+         */
+        get: operations["withdrawals.get"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/v1/withdrawals/{id}/cancel": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Cancel a withdrawal
+         * @description Requests cancellation of an unbooked withdrawal created by this credential. Poll until canceled or another final outcome. Cancellation is asynchronous: a concurrent final approval or booking can win, in which case the withdrawal continues and its transaction remains visible. A booked withdrawal cannot be canceled.
+         */
+        post: operations["withdrawals.cancel"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
 }
 export type webhooks = Record<string, never>;
 export interface components {
@@ -1463,7 +1571,7 @@ export interface components {
             object: "list";
         };
         /** @enum {string} */
-        EventTypeName: "bank_account.created" | "bank_account.removed" | "bank_account_operation.updated" | "deposit.updated" | "deposit_quote.updated" | "external_wallet.created" | "external_wallet.updated" | "external_wallet_operation.updated" | "notification.created" | "order.updated" | "source_wallet_declaration.updated" | "statement_generation.updated" | "transaction.created" | "transaction.updated";
+        EventTypeName: "bank_account.created" | "bank_account.removed" | "bank_account_operation.updated" | "deposit.updated" | "deposit_quote.updated" | "external_wallet.created" | "external_wallet.updated" | "external_wallet_operation.updated" | "notification.created" | "order.updated" | "source_wallet_declaration.updated" | "statement_generation.updated" | "transaction.created" | "transaction.updated" | "transfer_approval.created" | "transfer_approval.updated" | "withdrawal.created" | "withdrawal.updated";
         ExternalWallet: {
             /** @description True when a Stable Sea operator registered this wallet for the business; false when the business added it itself. */
             added_by_stable_sea: boolean;
@@ -1508,6 +1616,8 @@ export interface components {
              * @enum {string}
              */
             status: "enabled" | "disabled";
+            /** @description The asset this saved destination accepts for withdrawals. Address-level holdings can contain other assets. */
+            symbol: string;
         };
         ExternalWalletCreateInput: {
             address: string;
@@ -2793,6 +2903,82 @@ export interface components {
             enabled_events?: components["schemas"]["EventTypeName"][];
             url?: string | null;
         };
+        Withdrawal: {
+            amount: string;
+            approval_request_id: string | null;
+            bank_account: string | null;
+            /** Format: date-time */
+            created_ts: string;
+            external_wallet: string | null;
+            failure_code?: string;
+            id: string;
+            livemode: boolean;
+            /** @enum {string} */
+            method: "onchain" | "ach" | "wire";
+            /** @enum {string} */
+            object: "withdrawal";
+            quote_id: string | null;
+            /** @enum {string} */
+            status: "pending" | "pending_approval" | "canceling" | "processing" | "completed" | "failed" | "canceled";
+            transaction_id: string | null;
+        };
+        WithdrawalFeeTerms: {
+            bank_fee_usd: string;
+            /** Format: int64 */
+            bps: number;
+            caps_at_par: boolean;
+            conversion_input: string;
+            estimated_conversion_rate?: string | null;
+            estimated_proceeds?: string | null;
+            platform_fee_usdc: string;
+            /** @enum {string} */
+            settlement_asset: "USD";
+            settles_at_par: boolean;
+            /** @enum {string} */
+            source_symbol: "USDC";
+            total_source_debit: string;
+        };
+        WithdrawalInput: {
+            /** @description Principal excluding fees: USD for ACH/wire, or units of the saved wallet's asset for on-chain withdrawals. */
+            amount: string;
+            bank_account?: string;
+            external_wallet?: string;
+            /** @enum {string} */
+            method: "onchain" | "ach" | "wire";
+            /** @description A ready, unexpired quote for this exact bank, method and amount. Required for ACH/wire; omit for on-chain withdrawals. */
+            quote_id?: string | null;
+        };
+        WithdrawalList: {
+            data: components["schemas"]["Withdrawal"][];
+            has_more: boolean;
+            /** @enum {string} */
+            object: "list";
+        };
+        WithdrawalQuote: {
+            amount: string;
+            bank_account: string;
+            /** Format: date-time */
+            created_ts: string;
+            /** Format: date-time */
+            expires_ts: string;
+            failure_code?: string;
+            id: string;
+            livemode: boolean;
+            /** @enum {string} */
+            method: "ach" | "wire";
+            /** @enum {string} */
+            object: "withdrawal_quote";
+            pricing: components["schemas"]["WithdrawalFeeTerms"] | null;
+            /** @enum {string} */
+            status: "pending" | "ready" | "failed";
+        };
+        WithdrawalQuoteInput: {
+            /** @description USD principal in whole cents, excluding fees. */
+            amount: string;
+            bank_account: string;
+            /** @enum {string} */
+            method: "ach" | "wire";
+        };
     };
     responses: {
         /** @description Invalid input, version, account directive, or idempotency header. Correct the request before retrying. */
@@ -5070,4 +5256,248 @@ export interface operations {
             };
         };
     };
+    "withdrawal_quotes.create": {
+        parameters: {
+            query?: never;
+            header: {
+                "Idempotency-Key": components["parameters"]["Idempotency-Key"];
+            };
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: {
+            content: {
+                "application/json": components["schemas"]["WithdrawalQuoteInput"];
+            };
+        };
+        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"]["WithdrawalQuote"];
+                };
+            };
+            400: components["responses"]["Error400"];
+            401: components["responses"]["Error401"];
+            403: components["responses"]["Error403"];
+            409: components["responses"]["Error409"];
+            429: components["responses"]["Error429"];
+            /** @description Error response. */
+            default: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Error"];
+                };
+            };
+        };
+    };
+    "withdrawal_quotes.get": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                id: string;
+            };
+            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"]["WithdrawalQuote"];
+                };
+            };
+            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"];
+                };
+            };
+        };
+    };
+    "withdrawals.list": {
+        parameters: {
+            query?: {
+                limit?: number;
+                starting_after?: string;
+                ending_before?: string;
+                method?: "onchain" | "ach" | "wire";
+            };
+            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"]["WithdrawalList"];
+                };
+            };
+            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"];
+                };
+            };
+        };
+    };
+    "withdrawals.create": {
+        parameters: {
+            query?: never;
+            header: {
+                "Idempotency-Key": components["parameters"]["Idempotency-Key"];
+            };
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: {
+            content: {
+                "application/json": components["schemas"]["WithdrawalInput"];
+            };
+        };
+        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"]["Withdrawal"];
+                };
+            };
+            400: components["responses"]["Error400"];
+            401: components["responses"]["Error401"];
+            403: components["responses"]["Error403"];
+            409: components["responses"]["Error409"];
+            429: components["responses"]["Error429"];
+            /** @description Error response. */
+            default: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Error"];
+                };
+            };
+        };
+    };
+    "withdrawals.get": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                id: string;
+            };
+            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"]["Withdrawal"];
+                };
+            };
+            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"];
+                };
+            };
+        };
+    };
+    "withdrawals.cancel": {
+        parameters: {
+            query?: never;
+            header: {
+                "Idempotency-Key": components["parameters"]["Idempotency-Key"];
+            };
+            path: {
+                id: string;
+            };
+            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"]["Withdrawal"];
+                };
+            };
+            400: components["responses"]["Error400"];
+            401: components["responses"]["Error401"];
+            403: components["responses"]["Error403"];
+            409: components["responses"]["Error409"];
+            429: components["responses"]["Error429"];
+            /** @description Error response. */
+            default: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Error"];
+                };
+            };
+        };
+    };
 }