squarefi-bff-api-module 1.36.28 → 1.36.30

package/dist/api/types/autogen/apiV1External.types.d.ts

@@ -830,7 +830,8 @@ export interface paths {
                                 postcode?: string;
                                 street1?: string;
                                 street2?: string;
-                                state_id?: number;
+                                /** @description Required when the selected country has states; countries without states may omit it */
+                                state_id?: number | null;
                             };
                         };
                         /** @description Required for crypto types (CRYPTO_EXTERNAL, CRYPTO_INTERNAL) */
@@ -3870,13 +3871,14 @@ export interface paths {
         put?: never;
         /**
          * Exchange
-         * @description Exchange between currencies within the wallet bound to the API key.
+         * @description Crypto-to-crypto exchange within the wallet bound to the API key.
          *
-         *     **Crypto-to-crypto** exchanges complete instantly (status `COMPLETE`).
-         *     **Fiat-to-crypto** and **crypto-to-fiat** exchanges create a `PENDING` order
-         *     and trigger an asynchronous Rail workflow.
+         *     Two-phase, like the banking withdrawals: the order is created in status
+         *     `NEW` with the source funds blocked. Call `POST /api/orders/{order_id}/approve`
+         *     to execute the swap (the order lands in `COMPLETE` synchronously), or
+         *     `POST /api/orders/{order_id}/cancel` to release the blocked funds.
          *
-         *     Requires an active virtual account for the fiat currency when fiat is involved.
+         *     Fiat legs are not supported — only crypto-to-crypto pairs are accepted.
          *
          */
         post: {
@@ -3892,7 +3894,7 @@ export interface paths {
                 };
             };
             responses: {
-                /** @description Exchange order created */
+                /** @description Exchange order created (status NEW, funds blocked — approve to execute) */
                 200: {
                     headers: {
                         [name: string]: unknown;
@@ -4219,6 +4221,8 @@ export interface paths {
         /**
          * Approve order
          * @description Transitions the order from NEW to PROCESSING and triggers the order execution pipeline.
+         *     Exchange orders (EXCHANGE_OMNI) and internal transfers (TRANSFER_INTERNAL /
+         *     OMNIBUS_INTERNAL_TRANSFER) settle synchronously and land in COMPLETE.
          *     Only orders with status NEW can be approved.
          *
          */
@@ -4366,7 +4370,12 @@ export interface paths {
         put?: never;
         /**
          * Internal
-         * @description Transfers funds between wallets within the platform.
+         * @description Transfers funds between wallets within the platform. Two-phase: the
+         *     order is created in `NEW` status with the sender's funds blocked;
+         *     call `POST /api/orders/{id}/approve` to execute the transfer — it
+         *     settles synchronously (receiver credited, order `COMPLETE`). A `NEW`
+         *     order can be canceled via `POST /api/orders/{id}/cancel` to refund
+         *     the blocked funds.
          *     Wallet ID is automatically resolved from the API key — do **not** pass `wallet_id`.
          *
          *     `request_id` is used for idempotency: re-posting the same `request_id`
@@ -4406,7 +4415,7 @@ export interface paths {
                 };
             };
             responses: {
-                /** @description Transfer created */
+                /** @description Transfer created in NEW status (funds blocked, awaiting approve) */
                 200: {
                     headers: {
                         [name: string]: unknown;
@@ -4478,6 +4487,12 @@ export interface paths {
          *     address (or another internal wallet) via a previously-created counterparty
          *     destination.
          *
+         *     Two-phase: the order is created in `NEW` status with funds blocked;
+         *     `POST /api/orders/{id}/approve` dispatches the on-chain send. If the
+         *     destination address belongs to a wallet in the same tenant, the order is
+         *     created as `OMNIBUS_INTERNAL_TRANSFER` (no on-chain transaction) — still
+         *     `NEW` at create, settled synchronously to `COMPLETE` at approve.
+         *
          *     **Prerequisites:**
          *     - A counterparty destination of type `CRYPTO_EXTERNAL` or `CRYPTO_INTERNAL`
          *       created via `POST /api/counterparty/destinations`.
@@ -7430,6 +7445,12 @@ export interface components {
              * @example 7c8d4a2b-1e3f-4d59-9b6a-2c0e5f7d8a90
              */
             to_currency_id: string;
+            /**
+             * Format: uuid
+             * @description Idempotency key (UUID v4 recommended).
+             * @example 550e8400-e29b-41d4-a716-446655440000
+             */
+            request_id: string;
         };
         /** @description Virtual bank account */
         VirtualAccount: {

package/dist/api/types/autogen/apiV1Frontend.types.d.ts

@@ -891,21 +891,90 @@ export interface paths {
             };
             requestBody?: never;
             responses: {
-                /** @description Bank data resolved successfully */
+                /** @description Bank data resolved. `data` is null ONLY when the bank-data lookup subsystem is
+                 *     disabled on the environment; with lookups enabled a failed resolution is
+                 *     reported as 400, never as a null `data`.
+                 *      */
                 200: {
                     headers: {
                         [name: string]: unknown;
                     };
-                    content?: never;
+                    content: {
+                        "application/json": {
+                            /** @example true */
+                            success: boolean;
+                            data: components["schemas"]["BankData"] | null;
+                        };
+                    };
                 };
-                /** @description Missing/unsupported code */
+                /** @description Bad request — one of:
+                 *     - `VALIDATION_ERROR` — query parameter `code` is missing/empty, or longer than 64 characters
+                 *     - `UNSUPPORTED_BANK_CODE` — `code` does not match any supported format (IBAN, SWIFT/BIC, US RTN)
+                 *     - `BANK_DATA_LOOKUP_FAILED` — the code is well-formed but could not be resolved
+                 *       (unknown code or a transient lookup failure); always reported as this single
+                 *       400, never as 404/502
+                 *     - `EXTERNAL_SERVICE_ERROR` — the bank-data lookup is temporarily unavailable
+                 *
+                 *     The body also carries a top-level `correlationId` (added by the error handler to
+                 *     every 4xx/5xx it formats).
+                 *      */
                 400: {
                     headers: {
                         [name: string]: unknown;
                     };
-                    content?: never;
+                    content: {
+                        "application/json": components["schemas"]["ErrorResponse"];
+                    };
                 };
                 401: components["responses"]["UnauthorizedError"];
+                /** @description Per-user bank-data lookup rate limit exceeded (stricter than the general frontend
+                 *     rate limit). The body is sent directly by the rate-limit middleware, bypassing
+                 *     the group error handler, so it carries no `correlationId` and no `details` field.
+                 *
+                 *     The platform-wide per-user and per-IP limiters can also answer 429 on this
+                 *     endpoint — same envelope, code and headers, but with the generic message
+                 *     "Too many requests. Please try again later.".
+                 *      */
+                429: {
+                    headers: {
+                        /** @description Maximum number of lookups allowed in the current window */
+                        "X-RateLimit-Limit"?: string;
+                        /** @description Lookups remaining in the current window */
+                        "X-RateLimit-Remaining"?: string;
+                        /** @description Unix timestamp (ms) at which the current window resets */
+                        "X-RateLimit-Reset"?: string;
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        /** @example {
+                         *       "success": false,
+                         *       "error": {
+                         *         "code": "RATE_LIMIT_EXCEEDED",
+                         *         "message": "Too many bank data lookups. Please slow down."
+                         *       }
+                         *     } */
+                        "application/json": components["schemas"]["ErrorResponse"];
+                    };
+                };
+                /** @description Unexpected internal error, handled by the catch-all error handler; the body
+                 *     carries a `correlationId`.
+                 *      */
+                500: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        /** @example {
+                         *       "success": false,
+                         *       "error": {
+                         *         "code": "INTERNAL_ERROR",
+                         *         "message": "Internal server error"
+                         *       },
+                         *       "correlationId": "3f7f2f9a-8f0e-4a3b-9a3d-2f1c9d6a1b2c"
+                         *     } */
+                        "application/json": components["schemas"]["ErrorResponse"];
+                    };
+                };
             };
         };
         put?: never;
@@ -1425,11 +1494,11 @@ export interface paths {
          * Check internal-transfer availability for a destination
          * @description Read-only check (writes nothing). Resolves the destination's payment
          *     details to an on-platform wallet within the tenant and reports whether an
-         *     instant internal transfer is available.
+         *     internal (off-chain) transfer is available.
          *
          *     A `true` answer means the caller can create an INTERNAL destination to
          *     `target_wallet_id` and transfer to it. Any recipient that cannot receive
-         *     an instant internal transfer is uniformly reported as `available:false`
+         *     an internal transfer is uniformly reported as `available:false`
          *     with `target_wallet_id:null` — the check does not disclose the reason.
          *
          *     Detects crypto (address), INTERNAL (stored target wallet) and banking
@@ -4582,6 +4651,269 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/frontend/kyc_verification/{wallet_id}/init": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Initialize KYC verification for a wallet
+         * @description Starts a provider-agnostic KYC data-collection flow for the wallet via
+         *     the Auth API. The KYC provider (Persona, Sumsub, …) is resolved
+         *     internally per tenant — the caller does not choose it. Returns the
+         *     provider verification id plus an optional short-lived SDK token the
+         *     client uses to launch the verification. The caller's Bearer token is
+         *     forwarded to the Auth API.
+         *
+         *     Provider-agnostic replacement for the deprecated
+         *     `GET /frontend/kyc_persona/{wallet_id}/init`.
+         *
+         *     **Authentication**: Bearer token with x-tenant-id header required
+         *
+         *     **Access Control**: Any user with access to the wallet (scoped card-users excluded)
+         *
+         */
+        post: {
+            parameters: {
+                query?: never;
+                header?: never;
+                path: {
+                    /** @description Wallet UUID */
+                    wallet_id: string;
+                };
+                cookie?: never;
+            };
+            requestBody: {
+                content: {
+                    "application/json": {
+                        /**
+                         * @description KYC entity type
+                         * @enum {string}
+                         */
+                        type: "individual" | "business";
+                    };
+                };
+            };
+            responses: {
+                /** @description KYC verification initialized */
+                200: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": {
+                            /** @example true */
+                            success: boolean;
+                            data: {
+                                /**
+                                 * Format: uuid
+                                 * @description Echo of the wallet from the path
+                                 */
+                                wallet_id: string;
+                                /**
+                                 * @description Provider that handled the flow (e.g. persona, sumsub)
+                                 * @example persona
+                                 */
+                                provider_type: string;
+                                /**
+                                 * @description Provider verification id — Persona: inquiryId, Sumsub: applicantId
+                                 * @example inq_ABDNxhp9ZzD3yehivCbMVvmjwh5g5r
+                                 */
+                                verification_id: string;
+                                /** @description Short-lived SDK/session token when the provider mints one — otherwise null */
+                                verification_token?: string | null;
+                            };
+                        };
+                    };
+                };
+                /** @description Validation error (`type` missing or not in [individual, business]) */
+                400: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["ErrorResponse"];
+                    };
+                };
+                /** @description Missing or invalid Bearer token */
+                401: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["ErrorResponse"];
+                    };
+                };
+                /** @description Caller has no access to this wallet */
+                403: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["ErrorResponse"];
+                    };
+                };
+                /** @description Wallet not found upstream */
+                404: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["ErrorResponse"];
+                    };
+                };
+                /** @description Auth API unavailable, timed out, or returned a malformed payload */
+                502: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["ErrorResponse"];
+                    };
+                };
+            };
+        };
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/frontend/kyc_verification/{wallet_id}/resume": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Resume KYC verification for a wallet
+         * @description Resumes an existing provider-agnostic KYC data-collection flow for the
+         *     wallet via the Auth API. The provider is resolved internally per tenant.
+         *     `verification_ref` is the provider reference returned by init (Persona:
+         *     `inquiry_id`, Sumsub: `applicant_id`). The caller's Bearer token is
+         *     forwarded to the Auth API.
+         *
+         *     Provider-agnostic replacement for the deprecated
+         *     `GET /frontend/kyc_persona/{wallet_id}/resume`.
+         *
+         *     **Authentication**: Bearer token with x-tenant-id header required
+         *
+         *     **Access Control**: Any user with access to the wallet (scoped card-users excluded)
+         *
+         */
+        post: {
+            parameters: {
+                query?: never;
+                header?: never;
+                path: {
+                    /** @description Wallet UUID */
+                    wallet_id: string;
+                };
+                cookie?: never;
+            };
+            requestBody: {
+                content: {
+                    "application/json": {
+                        /**
+                         * @description Provider verification reference (Persona: inquiry_id, Sumsub: applicant_id)
+                         * @example inq_ABDNxhp9ZzD3yehivCbMVvmjwh5g5r
+                         */
+                        verification_ref: string;
+                    };
+                };
+            };
+            responses: {
+                /** @description KYC verification resumed */
+                200: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": {
+                            /** @example true */
+                            success: boolean;
+                            data: {
+                                /**
+                                 * Format: uuid
+                                 * @description Echo of the wallet from the path
+                                 */
+                                wallet_id: string;
+                                /**
+                                 * @description Provider that handled the flow (e.g. persona, sumsub)
+                                 * @example persona
+                                 */
+                                provider_type: string;
+                                /**
+                                 * @description Provider verification id — Persona: inquiryId, Sumsub: applicantId
+                                 * @example inq_ABDNxhp9ZzD3yehivCbMVvmjwh5g5r
+                                 */
+                                verification_id: string;
+                                /** @description Short-lived SDK/session token when the provider mints one — otherwise null */
+                                verification_token?: string | null;
+                            };
+                        };
+                    };
+                };
+                /** @description Validation error (`verification_ref` missing or empty) */
+                400: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["ErrorResponse"];
+                    };
+                };
+                /** @description Missing or invalid Bearer token */
+                401: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["ErrorResponse"];
+                    };
+                };
+                /** @description Caller has no access to this wallet */
+                403: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["ErrorResponse"];
+                    };
+                };
+                /** @description No such verification to resume upstream */
+                404: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["ErrorResponse"];
+                    };
+                };
+                /** @description Auth API unavailable, timed out, or returned a malformed payload */
+                502: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["ErrorResponse"];
+                    };
+                };
+            };
+        };
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/frontend/orders/deposit/ach": {
         parameters: {
             query?: never;
@@ -4830,13 +5162,17 @@ export interface paths {
         put?: never;
         /**
          * Exchange
-         * @description Exchange between currencies within a wallet.
+         * @description Currency exchange within a wallet — a pure ledger swap for any enabled
+         *     currency pair (crypto and fiat alike). Pair availability is governed by
+         *     the exchange calculation config: a disabled pair is rejected at create.
          *
-         *     **Crypto-to-crypto** exchanges complete instantly (status `COMPLETE`).
-         *     **Fiat-to-crypto** and **crypto-to-fiat** exchanges create a `PENDING` order
-         *     and trigger an asynchronous Rail workflow.
+         *     Two-phase, like the banking withdrawals: the order is created in status
+         *     `NEW` without touching the balance. Call `POST /frontend/orders/{order_id}/approve`
+         *     (OTP-gated, keyed on the order id) to check the balance, debit the
+         *     source funds and execute the swap — the order lands in `COMPLETE`
+         *     synchronously — or `POST /frontend/orders/{order_id}/cancel` to
+         *     discard the order.
          *
-         *     Requires an active virtual account for the fiat currency when fiat is involved.
          *     Caller must be `admin` of the wallet.
          *
          */
@@ -4853,7 +5189,7 @@ export interface paths {
                 };
             };
             responses: {
-                /** @description Exchange order created */
+                /** @description Exchange order created (status NEW — approve to debit and execute) */
                 200: {
                     headers: {
                         [name: string]: unknown;
@@ -4921,7 +5257,12 @@ export interface paths {
         put?: never;
         /**
          * Internal
-         * @description Transfers funds between two wallets within the platform.
+         * @description Transfers funds between two wallets within the platform. Two-phase:
+         *     the order is created in `NEW` status without touching the balance;
+         *     `POST /frontend/orders/{id}/approve` (OTP-gated, keyed on the order
+         *     id) checks the balance, debits the sender and executes the transfer
+         *     synchronously — receiver credited, order `COMPLETE`. A `NEW` order
+         *     can simply be canceled (no funds are held).
          *     Caller must be `admin` of the source wallet.
          *
          */
@@ -4948,15 +5289,13 @@ export interface paths {
                          */
                         counterparty_destination_id: string;
                         amount: number;
-                        /** @description Idempotency key (UUID) */
-                        request_id: string;
                         /** @description Optional supporting documents persisted with the order. */
                         documents?: components["schemas"]["OrderDocumentInput"][];
                     };
                 };
             };
             responses: {
-                /** @description Transfer created */
+                /** @description Transfer created in NEW status (awaiting approve; no funds held) */
                 200: {
                     headers: {
                         [name: string]: unknown;
@@ -5024,10 +5363,14 @@ export interface paths {
         put?: never;
         /**
          * Crypto
-         * @description Sends crypto from an omnibus wallet to an external address.
-         *     If the destination address belongs to a wallet in the same tenant,
-         *     the order is created as `OMNIBUS_INTERNAL_TRANSFER` with instant completion
-         *     (no on-chain transaction).
+         * @description Sends crypto from an omnibus wallet to an external address. Two-phase:
+         *     the order is created in `NEW` status without touching the balance;
+         *     `POST /frontend/orders/{id}/approve` (OTP-gated, keyed on the order
+         *     id) checks the balance, debits the funds and dispatches the on-chain
+         *     send. If the destination address belongs to a wallet in the same
+         *     tenant, the order is created as `OMNIBUS_INTERNAL_TRANSFER` (no
+         *     on-chain transaction) — still `NEW` at create, debited + settled
+         *     synchronously to `COMPLETE` at approve.
          *
          */
         post: {
@@ -5697,7 +6040,14 @@ export interface paths {
         put?: never;
         /**
          * Approve an order
-         * @description Moves a NEW order to PROCESSING, triggering its workflow. Validates the order's request_id via OTP.
+         * @description Moves a NEW order to PROCESSING: checks the balance, debits the funds
+         *     (transaction written as `complete`) and triggers its workflow.
+         *     Exchange orders (EXCHANGE_OMNI) and internal transfers
+         *     (TRANSFER_INTERNAL / OMNIBUS_INTERNAL_TRANSFER) settle synchronously
+         *     and land in COMPLETE. An insufficient balance fails the order
+         *     (FAILED). OTP verification is mandatory and keyed on the order id
+         *     (request the OTP for the order being approved).
+         *
          */
         post: {
             parameters: {
@@ -5758,7 +6108,7 @@ export interface paths {
         put?: never;
         /**
          * Cancel an order
-         * @description Cancels a NEW/FAILED order, cancels its workflow run, and refunds the blocked funds.
+         * @description Cancels a NEW/FAILED order, cancels its workflow run, and refunds the debited funds (if the order was ever approved).
          */
         post: {
             parameters: {
@@ -5779,7 +6129,7 @@ export interface paths {
                 };
             };
             responses: {
-                /** @description Order canceled and funds refunded */
+                /** @description Order canceled (debited funds refunded when applicable) */
                 200: {
                     headers: {
                         [name: string]: unknown;
@@ -8080,6 +8430,16 @@ export interface paths {
                          * @example true
                          */
                         empty_name?: boolean;
+                        /**
+                         * Format: uuid
+                         * @description Optional KYC entity to link (entity-first KYC model). Must be
+                         *     an entity of the current user (`GET /kyc/entities`); its type
+                         *     must be enabled for the tenant. The link is set once at
+                         *     creation and is immutable. Omitted → wallet is created
+                         *     without a linked entity (legacy behaviour).
+                         *
+                         */
+                        kyc_entity_id?: string;
                     };
                 };
             };
@@ -8128,14 +8488,14 @@ export interface paths {
                         };
                     };
                 };
-                /** @description Bad request - invalid type */
+                /** @description Bad request — invalid name, or `kyc_entity_id` is malformed / not an entity of the current user / belongs to another tenant */
                 400: {
                     headers: {
                         [name: string]: unknown;
                     };
                     content?: never;
                 };
-                /** @description Forbidden - no permission to create wallets */
+                /** @description Forbidden — no permission to create wallets, or the entity type is not enabled for the tenant */
                 403: {
                     headers: {
                         [name: string]: unknown;
@@ -8869,7 +9229,7 @@ export interface paths {
          *
          *     **Access Control**: User must own the wallet
          *
-         *     **Note**: The system will automatically use the appropriate provider (Utila or Processing) based on tenant configuration.
+         *     **Note**: New addresses are always provisioned via Utila. The legacy Processing (Accepta) provider was decommissioned; existing `processing` addresses remain readable.
          *
          */
         post: {
@@ -9859,6 +10219,8 @@ export interface paths {
          *     - Cannot invite yourself
          *     - Cannot invite a current owner of this wallet
          *     - Cannot invite a user who is already a member (active or deactivated)
+         *     - When the tenant has KYC enabled, the wallet's entity must be `APPROVED`;
+         *       otherwise the invite is rejected with 403 `KYC_REQUIREMENTS_NOT_MET`
          *
          *     **Authentication**: Bearer token with x-tenant-id header required
          *
@@ -9912,7 +10274,7 @@ export interface paths {
                     };
                     content?: never;
                 };
-                /** @description Access denied (insufficient wallet role) */
+                /** @description Access denied (insufficient wallet role) or KYC not approved for the wallet entity */
                 403: {
                     headers: {
                         [name: string]: unknown;
@@ -10218,6 +10580,12 @@ export interface components {
             memo?: string | null;
             /** Format: uuid */
             currency_id?: string;
+            /**
+             * @description Hosting classification of the address. Defaults to unknown.
+             * @default unknown
+             * @enum {string}
+             */
+            wallet_custody_type: "custodial" | "selfhosted" | "unknown";
             currency: components["schemas"]["CounterpartyCurrencyRef"];
             /** Format: date-time */
             created_at: string;
@@ -10261,6 +10629,60 @@ export interface components {
              */
             target_wallet_id: string | null;
         };
+        /** @description Bank postal address resolved from the bank identifier. Intentionally mirrors the CounterpartyBankingAddress shape so the payload can prefill a counterparty form as-is. */
+        BankDataAddress: {
+            /** @description Resolved `countries.id` of the bank’s country; null when it could not be resolved */
+            country_id: number | null;
+            /** @description Always null today (reserved for future enrichment) */
+            state_id: number | null;
+            city: string | null;
+            postcode: string | null;
+            /** @description Bank street address line */
+            street1: string | null;
+            /** @description Always null today (reserved) */
+            street2: string | null;
+            /** @description Always null today (reserved) */
+            description: string | null;
+        };
+        /**
+         * @description Normalised bank data resolved from a bank identifier. Which identifier fields are populated depends on the looked-up code type: IBAN → `iban` + `swift_bic` (plus `account_number`/`sort_code` for GB IBANs), SWIFT/BIC → `swift_bic`, US RTN → `routing_number`; identifier fields not applicable to the code type are null. `bank_name` and `address` are populated for every code type whenever they are available.
+         * @example {
+         *       "account_number": "31926819",
+         *       "bank_name": "NATIONAL WESTMINSTER BANK PLC",
+         *       "note": null,
+         *       "routing_number": null,
+         *       "swift_bic": "NWBKGB2LXXX",
+         *       "iban": "GB29NWBK60161331926819",
+         *       "sort_code": "601613",
+         *       "address": {
+         *         "country_id": 230,
+         *         "state_id": null,
+         *         "city": "London",
+         *         "postcode": null,
+         *         "street1": null,
+         *         "street2": null,
+         *         "description": null
+         *       }
+         *     }
+         */
+        BankData: {
+            /** @description Populated only for GB IBANs (22 chars): the embedded 8-digit account number (IBAN positions 14-22); null otherwise */
+            account_number: string | null;
+            /** @description Registered bank name; null when unavailable */
+            bank_name: string | null;
+            /** @description Always null today (reserved) */
+            note: string | null;
+            /** @description Populated only when the looked-up code is a US routing number (echoes the RTN); null otherwise */
+            routing_number: string | null;
+            /** @description SWIFT/BIC (ISO 9362); populated for SWIFT lookups and for IBAN lookups when the IBAN resolves to a BIC */
+            swift_bic: string | null;
+            /** @description Populated only for IBAN lookups (the normalised IBAN itself) */
+            iban: string | null;
+            /** @description Populated only for GB IBANs: the embedded 6-digit sort code (IBAN positions 8-14); null otherwise */
+            sort_code: string | null;
+            /** @description Bank postal address (always present) */
+            address: components["schemas"]["BankDataAddress"];
+        };
         /** @description Bank / rail account coordinates for a sub-account. Rail-dependent — some rails return only a subset of these. */
         BankAccountDetails: {
             swift?: string;
@@ -10721,7 +11143,7 @@ export interface components {
         };
         /** @description Public order metadata fields */
         OrderMeta: {
-            /** @description Idempotency key passed at creation time */
+            /** @description Legacy idempotency key — null on orders created by the current flow */
             request_id?: string | null;
             note?: string | null;
             reference?: string | null;
@@ -10791,8 +11213,6 @@ export interface components {
             counterparty_destination_id: string;
             /** Format: uuid */
             wallet_account_id?: string;
-            /** @description Idempotency key (UUID) */
-            request_id: string;
             reference?: string;
             note?: string;
             /** @description Optional supporting documents persisted with the order. */
@@ -10813,8 +11233,6 @@ export interface components {
             virtual_account_id: string;
             /** Format: uuid */
             counterparty_destination_id: string;
-            /** @description Idempotency key (UUID) */
-            request_id: string;
             reference?: string;
             note?: string;
             /** @description Optional supporting documents persisted with the order. */

package/dist/api/types/autogen/apiV1Legacy.types.d.ts

@@ -364,7 +364,7 @@ export interface paths {
         put?: never;
         /**
          * Create a new wallet address
-         * @description Create a new blockchain address for a wallet with Utila or Processing integration
+         * @description Create a new blockchain address for a wallet with Utila integration
          */
         post: {
             parameters: {
@@ -8977,6 +8977,108 @@ export interface components {
              */
             has_more?: boolean;
         };
+        /** @description Profile information of the payment sender */
+        L2FOriginatorProfile: {
+            /**
+             * @description Name of the sender
+             * @example FS AI, A SERIES OF FINSIGHT SPECI
+             */
+            name?: string;
+            /** @description Sender's address information */
+            address?: {
+                address_line1?: string | null;
+                city?: string | null;
+                state?: string | null;
+                postal_code?: string | null;
+                country?: string | null;
+            };
+        };
+        /** @description Bank account information of the sender */
+        L2FOriginatorAccountInfo: {
+            /**
+             * @description Bank account number
+             * @example 202504243736
+             */
+            account_number?: string;
+            /**
+             * @description Routing number (for US payments)
+             * @example 91311229
+             */
+            routing_number?: string | null;
+            /** @description SWIFT BIC code (for international transfers) */
+            swift_bic?: string | null;
+            /** @description Name of the bank/institution */
+            institution_name?: string | null;
+        };
+        /**
+         * @description Standardized originator (sender) information for L2F ONRAMP orders.
+         *     Available for order types: L2F_ACH_ONRAMP, L2F_WIRE_ONRAMP, L2F_SEPA_ONRAMP, L2F_SWIFT_ONRAMP.
+         *     This field appears in order.meta.originator
+         *
+         * @example {
+         *       "profile": {
+         *         "name": "FS AI, A SERIES OF FINSIGHT SPECI",
+         *         "address": {
+         *           "address_line1": "",
+         *           "city": "",
+         *           "state": "",
+         *           "postal_code": "",
+         *           "country": ""
+         *         }
+         *       },
+         *       "account_information": {
+         *         "account_number": "202504243736",
+         *         "routing_number": "91311229",
+         *         "swift_bic": "",
+         *         "institution_name": ""
+         *       },
+         *       "reference": "20251016MMQFMP2U004005",
+         *       "memo": "bfgkp5w"
+         *     }
+         */
+        L2FOriginator: {
+            profile?: components["schemas"]["L2FOriginatorProfile"];
+            account_information?: components["schemas"]["L2FOriginatorAccountInfo"];
+            /**
+             * @description Payment reference number (rail_reference from Railio)
+             * @example 20251016MMQFMP2U004005
+             */
+            reference?: string | null;
+            /**
+             * @description Payment memo/note (rail_originator_memo from Railio)
+             * @example bfgkp5w
+             */
+            memo?: string | null;
+        } | null;
+        /**
+         * @description Optional array of document objects to attach to the order.
+         *     Documents should be uploaded to a storage service beforehand and only URLs should be provided.
+         *     Maximum 50 documents per order.
+         *
+         * @example [
+         *       {
+         *         "url": "https://storage.example.com/documents/invoice-001.pdf",
+         *         "description": "Invoice for payment #001"
+         *       },
+         *       {
+         *         "url": "https://storage.example.com/documents/contract-signed.pdf",
+         *         "description": "Signed contract"
+         *       }
+         *     ]
+         */
+        OrderDocuments: {
+            /**
+             * Format: uri
+             * @description URL of the uploaded document
+             * @example https://storage.example.com/documents/invoice-123.pdf
+             */
+            url: string;
+            /**
+             * @description Optional description of the document
+             * @example Invoice for payment #12345
+             */
+            description?: string | null;
+        }[];
         VirtualAccount: {
             /**
              * Format: uuid
@@ -9261,8 +9363,6 @@ export interface components {
         CardUpdateRequest: unknown;
         IssuingProgram: unknown;
         IssuingTransactionList: unknown;
-        L2FOriginator: unknown;
-        OrderDocuments: unknown;
     };
     responses: never;
     parameters: never;

package/dist/api/types/autogen/apiV1Tenant.types.d.ts

@@ -615,7 +615,8 @@ export interface paths {
                                 postcode?: string;
                                 street1?: string;
                                 street2?: string;
-                                state_id?: number;
+                                /** @description Required when the selected country has states; countries without states may omit it */
+                                state_id?: number | null;
                             };
                         };
                         crypto_data?: {
@@ -2517,13 +2518,14 @@ export interface paths {
         put?: never;
         /**
          * Exchange
-         * @description Exchange between currencies within a wallet.
+         * @description Crypto-to-crypto exchange within a wallet.
          *
-         *     **Crypto-to-crypto** exchanges complete instantly (status `COMPLETE`).
-         *     **Fiat-to-crypto** and **crypto-to-fiat** exchanges create a `PENDING` order
-         *     and trigger an asynchronous Rail workflow.
+         *     Two-phase, like the banking withdrawals: the order is created in status
+         *     `NEW` with the source funds blocked. Call `POST /admin/orders/{order_id}/approve`
+         *     to execute the swap (the order lands in `COMPLETE` synchronously), or
+         *     `POST /admin/orders/{order_id}/cancel` to release the blocked funds.
          *
-         *     Requires an active virtual account for the fiat currency when fiat is involved.
+         *     Fiat legs are not supported — only crypto-to-crypto pairs are accepted.
          *
          */
         post: {
@@ -2542,7 +2544,7 @@ export interface paths {
                 };
             };
             responses: {
-                /** @description Exchange order created */
+                /** @description Exchange order created (status NEW, funds blocked — approve to execute) */
                 200: {
                     headers: {
                         [name: string]: unknown;
@@ -2608,7 +2610,15 @@ export interface paths {
         };
         get?: never;
         put?: never;
-        /** Internal */
+        /**
+         * Internal
+         * @description Transfers funds between two wallets within the platform. Two-phase:
+         *     the order is created in `NEW` status with the sender's funds blocked;
+         *     `POST /admin/orders/{id}/approve` executes the transfer synchronously —
+         *     receiver credited, order `COMPLETE`. A `NEW` order can be canceled to
+         *     refund the blocked funds.
+         *
+         */
         post: {
             parameters: {
                 query?: never;
@@ -2636,7 +2646,7 @@ export interface paths {
                 };
             };
             responses: {
-                /** @description Transfer created */
+                /** @description Transfer created in NEW status (funds blocked, awaiting approve) */
                 200: {
                     headers: {
                         [name: string]: unknown;
@@ -2693,7 +2703,16 @@ export interface paths {
         };
         get?: never;
         put?: never;
-        /** Crypto */
+        /**
+         * Crypto
+         * @description Sends crypto from the wallet's omnibus balance via a counterparty
+         *     destination. Two-phase: created `NEW` with funds blocked;
+         *     `POST /admin/orders/{id}/approve` dispatches the on-chain send. A
+         *     destination address internal to the tenant downgrades the order to
+         *     `OMNIBUS_INTERNAL_TRANSFER` — still `NEW` at create, settled
+         *     synchronously to `COMPLETE` at approve.
+         *
+         */
         post: {
             parameters: {
                 query?: never;
@@ -3538,6 +3557,8 @@ export interface paths {
         /**
          * Approve order
          * @description Transitions the order from NEW to PROCESSING and triggers the order execution pipeline.
+         *     Exchange orders (EXCHANGE_OMNI) and internal transfers (TRANSFER_INTERNAL /
+         *     OMNIBUS_INTERNAL_TRANSFER) settle synchronously and land in COMPLETE.
          *     Only orders with status NEW can be approved.
          *
          */
@@ -8176,6 +8197,11 @@ export interface components {
              * @description Destination currency UUID
              */
             to_currency_id: string;
+            /**
+             * Format: uuid
+             * @description Idempotency key (UUID v4 recommended)
+             */
+            request_id: string;
         };
         TenantOrder: {
             /** Format: uuid */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "squarefi-bff-api-module",
-  "version": "1.36.28",
+  "version": "1.36.30",
   "description": "Squarefi BFF API client module",
   "type": "module",
   "main": "./dist/index.js",