@chipi-stack/backend 13.13.0 → 14.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024-2026 Chipi Pay
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,52 @@
 # @chipi-stack/backend
 
-Utilities for Chipi SDKs
+Server-side SDK for Chipi Pay. Handles wallet creation, transactions, SKU purchases, and exchanges.
+
+## Install
+
+```bash
+npm install @chipi-stack/backend
+```
+
+## Quick Start
+
+```typescript
+import { ChipiSDK } from "@chipi-stack/backend";
+
+const sdk = new ChipiSDK({
+  apiPublicKey: process.env.CHIPI_API_PUBLIC_KEY!,
+  apiSecretKey: process.env.CHIPI_API_SECRET_KEY!,
+});
+
+const bearerToken = "your-bearer-token"; // From your auth provider (e.g., Clerk)
+
+// Create a wallet
+const wallet = await sdk.createWallet({
+  params: {
+    externalUserId: "user-123",
+    chain: "STARKNET",
+    encryptKey: "user-pin-or-passkey",
+  },
+  bearerToken,
+});
+
+// Transfer USDC
+const tx = await sdk.transfer({
+  params: {
+    wallet: wallet.wallet,
+    token: "USDC",
+    recipient: "0x...",
+    amount: 10,
+    encryptKey: "user-pin-or-passkey",
+  },
+  bearerToken,
+});
+```
+
+## Documentation
+
+Full docs at [docs.chipipay.com](https://docs.chipipay.com)
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -1,5 +1,5 @@
 import * as _chipi_stack_types from '@chipi-stack/types';
-import { CreateSessionKeyParams, SessionKeyData, AddSessionKeyParams, RevokeSessionKeyParams, GetSessionDataParams, SessionDataResponse, ExecuteWithSessionParams, Currency, ChipiSDKConfig, ExecuteTransactionParams, TransferParams, ApproveParams, CallAnyContractParams, CreateWalletParams, CreateWalletResponse, RecordSendTransactionParams, Transaction, GetTransactionListQuery, PaginatedResponse, GetWalletParams, GetTokenBalanceParams, GetTokenBalanceResponse, CreateSkuPurchaseParams, GetSkuListQuery, Sku, ChipiServerSDKConfig, ChipiBrowserSDKConfig } from '@chipi-stack/types';
+import { CreateSessionKeyParams, SessionKeyData, AddSessionKeyParams, RevokeSessionKeyParams, GetSessionDataParams, SessionDataResponse, ExecuteWithSessionParams, Currency, PaymasterAdapter, PaymasterAccount, X402FacilitatorConfig, NonceStore, PaymentPayload, VerifyResponse, SettleResponse, ChipiSDKConfig, ExecuteTransactionParams, SignTypedDataParams, SignTypedDataResult, TransferParams, ApproveParams, CallAnyContractParams, CreateWalletParams, CreateWalletResponse, RecordSendTransactionParams, Transaction, GetTransactionListQuery, PaginatedResponse, GetWalletParams, GetTokenBalanceParams, GetTokenBalanceResponse, CreateSkuPurchaseParams, GetSkuListQuery, Sku, TransactionStatusResponse, PrepareWalletUpgradeParams, PrepareWalletUpgradeResponse, ExecuteWalletUpgradeParams, ExecuteWalletUpgradeResponse, ChipiServerSDKConfig, ChipiBrowserSDKConfig, X402PaymentConfig } from '@chipi-stack/types';
 export * from '@chipi-stack/types';
 export { Chain, ChainToken } from '@chipi-stack/types';
 import { ChipiWallets } from './wallets.mjs';
@@ -7,6 +7,7 @@ import { ChipiTransactions } from './transactions.mjs';
 import { ChipiSkuPurchases } from './skuPurchases.mjs';
 import { ChipiSkus } from './skus.mjs';
 import { C as ChipiClient } from './client-CqD_yGH0.mjs';
+import { Call } from 'starknet';
 
 /**
  * Session key management for CHIPI wallets (SNIP-9 compatible).
@@ -175,6 +176,94 @@ declare class ChipiExchanges {
     getUsdAmount(currencyAmount: number, currency: Currency, bearerToken: string): Promise<number>;
 }
 
+/**
+ * PaymasterAdapter implementation that uses Chipi's backend API for gasless transactions.
+ *
+ * Flow:
+ * 1. Detect wallet type from on-chain class hash
+ * 2. Call /transactions/prepare-typed-data to get TypedData
+ * 3. Call account.signMessage(typedData) — triggers wallet popup for external wallets
+ * 4. Call /transactions/execute-sponsored-transaction with signature
+ * 5. Return transaction hash
+ */
+declare class ChipiPaymasterAdapter implements PaymasterAdapter {
+    private readonly client;
+    private readonly bearerToken;
+    constructor(client: ChipiClient, bearerToken: string);
+    execute({ account, calls }: {
+        account: PaymasterAccount;
+        calls: Call[];
+    }): Promise<string>;
+}
+
+/** Options for the static X402Facilitator.create() factory */
+interface X402FacilitatorCreateOptions {
+    /** API public key for ChipiClient */
+    apiKey: string;
+    /** Bearer token for paymaster API calls */
+    bearerToken: string;
+    /** Custom nonce store (default: in-memory) */
+    nonceStore?: NonceStore;
+    /** RPC provider for on-chain signature verification */
+    provider?: X402FacilitatorConfig["provider"];
+}
+/**
+ * x402 Payment Facilitator for Starknet.
+ *
+ * Implements the "facilitator" role in the x402 protocol:
+ * - verify(): Validate payment signature, amount, asset, nonce replay
+ * - settle(): Execute the USDC transfer via Chipi's paymaster
+ *
+ * Settlement reuses Chipi's existing gasless infrastructure
+ * (prepare-typed-data → sign → execute-sponsored-transaction).
+ */
+declare class X402Facilitator {
+    private readonly client;
+    private readonly bearerToken;
+    private readonly nonceStore;
+    private readonly provider;
+    constructor(client: ChipiClient, bearerToken: string, config?: X402FacilitatorConfig);
+    /**
+     * Factory method for simpler instantiation.
+     *
+     * @example
+     * ```typescript
+     * const facilitator = X402Facilitator.create({
+     *   apiKey: process.env.CHIPI_API_KEY!,
+     *   bearerToken: process.env.CHIPI_BEARER_TOKEN!,
+     * });
+     * ```
+     */
+    static create(options: X402FacilitatorCreateOptions): X402Facilitator;
+    /**
+     * Verify a payment signature is valid (doesn't execute the transfer).
+     *
+     * Checks:
+     * 1. Nonce has not been used (replay protection)
+     * 2. Payment has not expired (validUntil > now)
+     * 3. Asset is USDC mainnet
+     * 4. Amount is positive
+     * 5. Addresses are non-empty
+     */
+    verify(payment: PaymentPayload): Promise<VerifyResponse>;
+    /**
+     * Verify the SNIP-12 signature on a payment payload.
+     *
+     * If an RPC provider is configured, reconstructs the typed data, computes the
+     * message hash, and calls `is_valid_signature()` on the sender's account contract.
+     * Otherwise falls back to a presence-only check (backwards compatible).
+     */
+    private verifySignature;
+    /**
+     * Settle a verified payment by executing the USDC transfer via paymaster.
+     *
+     * IMPORTANT: Mark nonce as consumed BEFORE executing to prevent concurrent replays.
+     * If the transfer fails after nonce consumption, the nonce is still burned
+     * (caller should implement idempotency at a higher level if needed).
+     */
+    settle(payment: PaymentPayload): Promise<SettleResponse>;
+}
+
 /**
  * Main Chipi SDK class
  */
@@ -193,6 +282,37 @@ declare class ChipiSDK {
      * Resolve bearer token - uses provided token or falls back to apiSecretKey
      */
     private resolveBearerToken;
+    /**
+     * Create a PaymasterAdapter for use with TxBuilder.sendSponsored().
+     *
+     * @example
+     * ```typescript
+     * const sdk = new ChipiServerSDK({ apiPublicKey: "pk_...", apiSecretKey: "sk_..." });
+     * const paymaster = sdk.createPaymasterAdapter();
+     *
+     * const txHash = await new TxBuilder(account, { paymaster })
+     *   .transfer(USDC, [{ to, amount }])
+     *   .sendSponsored(); // gasless!
+     * ```
+     */
+    createPaymasterAdapter(bearerToken?: string): ChipiPaymasterAdapter;
+    /**
+     * Create an X402Facilitator for verifying and settling x402 payments.
+     *
+     * @example
+     * ```typescript
+     * const facilitator = sdk.createX402Facilitator();
+     *
+     * // With custom nonce store (Redis)
+     * const facilitator = sdk.createX402Facilitator(bearerToken, {
+     *   nonceStore: {
+     *     has: async (nonce) => (await redis.sismember("x402:nonces", nonce)) === 1,
+     *     consume: async (nonce) => (await redis.sadd("x402:nonces", nonce)) === 1,
+     *   },
+     * });
+     * ```
+     */
+    createX402Facilitator(bearerToken?: string, config?: X402FacilitatorConfig): X402Facilitator;
     /**
      * Execute a gasless transaction
      */
@@ -238,6 +358,27 @@ declare class ChipiSDK {
         params: ExecuteWithSessionParams;
         bearerToken?: string;
     }): Promise<string>;
+    /**
+     * Sign SNIP-12 typed data without executing a transaction.
+     *
+     * Purely local operation: decrypt private key → sign → return { r, s }.
+     * No API calls are made. Useful for x402 payment signatures and other
+     * off-chain signing flows.
+     *
+     * @example
+     * ```typescript
+     * const { r, s } = await sdk.signTypedData({
+     *   params: {
+     *     encryptKey: pin,
+     *     wallet,
+     *     typedData: snip12TypedData,
+     *   },
+     * });
+     * ```
+     */
+    signTypedData({ params, }: {
+        params: SignTypedDataParams;
+    }): Promise<SignTypedDataResult>;
     /**
      * Transfer tokens
      */
@@ -286,6 +427,25 @@ declare class ChipiSDK {
     getSkuPurchase(id: string, bearerToken?: string): Promise<Transaction>;
     getSkuList(params: GetSkuListQuery, bearerToken?: string): Promise<PaginatedResponse<Sku>>;
     getSku(id: string, bearerToken?: string): Promise<Sku>;
+    /**
+     * Get a single transaction by hash or internal ID
+     */
+    getTransaction(hashOrId: string, bearerToken?: string): Promise<Transaction>;
+    /**
+     * Get on-chain transaction status (supports polling for confirmation)
+     */
+    getTransactionStatus(hash: string, bearerToken?: string): Promise<TransactionStatusResponse>;
+    /**
+     * Prepare a wallet upgrade (e.g., READY → CHIPI or CHIPI v29 → v33).
+     * Returns typed data that must be signed by the wallet owner.
+     * Server-only: requires API secret key.
+     */
+    prepareWalletUpgrade(params: PrepareWalletUpgradeParams, bearerToken?: string): Promise<PrepareWalletUpgradeResponse>;
+    /**
+     * Execute a wallet upgrade after signing.
+     * Server-only: requires API secret key.
+     */
+    executeWalletUpgrade(params: ExecuteWalletUpgradeParams, bearerToken?: string): Promise<ExecuteWalletUpgradeResponse>;
     getUsdAmount(currencyAmount: number, currency: Currency, bearerToken?: string): Promise<number>;
 }
 
@@ -362,7 +522,73 @@ declare class ChipiBrowserSDK extends ChipiSDK {
     constructor(config: ChipiBrowserSDKConfig);
 }
 
+/**
+ * Sign SNIP-12 typed data without executing a transaction.
+ *
+ * This is a purely local operation:
+ * 1. Decrypt the private key using the encryption key (PIN)
+ * 2. Create a starknet Account
+ * 3. Sign the typed data with account.signMessage()
+ * 4. Normalize and return { r, s }
+ *
+ * No API calls are made. Useful for x402 payment signatures and other
+ * off-chain signing flows where you need a SNIP-12 signature but don't
+ * want to execute a transaction.
+ */
+declare const signTypedData: ({ params, }: {
+    params: SignTypedDataParams;
+}) => Promise<SignTypedDataResult>;
+
 declare const encryptPrivateKey: (privateKey: string, password: string) => string;
 declare const decryptPrivateKey: (encryptedPrivateKey: string, password: string) => string;
 
-export { ChipiBrowserSDK, ChipiClient, ChipiSDK, ChipiServerSDK, ChipiSessions, ChipiSkuPurchases, ChipiSkus, ChipiTransactions, ChipiWallets, decryptPrivateKey, encryptPrivateKey };
+interface X402MiddlewareConfig {
+    /** x402 facilitator instance for verify + settle */
+    facilitator: X402Facilitator;
+    /** Payment configuration for this endpoint */
+    paymentConfig: X402PaymentConfig;
+    /** Verify-only mode: verify payment but don't settle (default: false) */
+    verifyOnly?: boolean;
+}
+/**
+ * Flat convenience config — detected when `amount` + `recipient` are present.
+ * Avoids nesting paymentConfig.
+ */
+interface X402MiddlewareFlatConfig {
+    /** x402 facilitator instance */
+    facilitator: X402Facilitator;
+    /** Amount in human-readable USDC (e.g. "0.01") */
+    amount: string;
+    /** Recipient (merchant) address */
+    recipient: string;
+    /** Human-readable description */
+    description?: string;
+    /** Verify-only mode (default: false) */
+    verifyOnly?: boolean;
+}
+/**
+ * Express-compatible middleware for monetizing API endpoints with x402.
+ *
+ * When no X-PAYMENT header is present, returns 402 with payment requirement.
+ * When a valid payment is present, verifies and settles it, then calls next().
+ * The settled transaction info is attached to `req.x402`.
+ *
+ * @example
+ * ```typescript
+ * // Nested config (original)
+ * x402Middleware({
+ *   facilitator,
+ *   paymentConfig: { amount: "0.01", payTo: "0xYOUR_ADDRESS" },
+ * })
+ *
+ * // Flat config (convenience)
+ * x402Middleware({
+ *   facilitator,
+ *   amount: "0.01",
+ *   recipient: "0xYOUR_ADDRESS",
+ * })
+ * ```
+ */
+declare function x402Middleware(config: X402MiddlewareConfig | X402MiddlewareFlatConfig): (req: any, res: any, next: any) => Promise<any>;
+
+export { ChipiBrowserSDK, ChipiClient, ChipiPaymasterAdapter, ChipiSDK, ChipiServerSDK, ChipiSessions, ChipiSkuPurchases, ChipiSkus, ChipiTransactions, ChipiWallets, X402Facilitator, type X402FacilitatorCreateOptions, type X402MiddlewareConfig, type X402MiddlewareFlatConfig, decryptPrivateKey, encryptPrivateKey, signTypedData, x402Middleware };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import * as _chipi_stack_types from '@chipi-stack/types';
-import { CreateSessionKeyParams, SessionKeyData, AddSessionKeyParams, RevokeSessionKeyParams, GetSessionDataParams, SessionDataResponse, ExecuteWithSessionParams, Currency, ChipiSDKConfig, ExecuteTransactionParams, TransferParams, ApproveParams, CallAnyContractParams, CreateWalletParams, CreateWalletResponse, RecordSendTransactionParams, Transaction, GetTransactionListQuery, PaginatedResponse, GetWalletParams, GetTokenBalanceParams, GetTokenBalanceResponse, CreateSkuPurchaseParams, GetSkuListQuery, Sku, ChipiServerSDKConfig, ChipiBrowserSDKConfig } from '@chipi-stack/types';
+import { CreateSessionKeyParams, SessionKeyData, AddSessionKeyParams, RevokeSessionKeyParams, GetSessionDataParams, SessionDataResponse, ExecuteWithSessionParams, Currency, PaymasterAdapter, PaymasterAccount, X402FacilitatorConfig, NonceStore, PaymentPayload, VerifyResponse, SettleResponse, ChipiSDKConfig, ExecuteTransactionParams, SignTypedDataParams, SignTypedDataResult, TransferParams, ApproveParams, CallAnyContractParams, CreateWalletParams, CreateWalletResponse, RecordSendTransactionParams, Transaction, GetTransactionListQuery, PaginatedResponse, GetWalletParams, GetTokenBalanceParams, GetTokenBalanceResponse, CreateSkuPurchaseParams, GetSkuListQuery, Sku, TransactionStatusResponse, PrepareWalletUpgradeParams, PrepareWalletUpgradeResponse, ExecuteWalletUpgradeParams, ExecuteWalletUpgradeResponse, ChipiServerSDKConfig, ChipiBrowserSDKConfig, X402PaymentConfig } from '@chipi-stack/types';
 export * from '@chipi-stack/types';
 export { Chain, ChainToken } from '@chipi-stack/types';
 import { ChipiWallets } from './wallets.js';
@@ -7,6 +7,7 @@ import { ChipiTransactions } from './transactions.js';
 import { ChipiSkuPurchases } from './skuPurchases.js';
 import { ChipiSkus } from './skus.js';
 import { C as ChipiClient } from './client-CqD_yGH0.js';
+import { Call } from 'starknet';
 
 /**
  * Session key management for CHIPI wallets (SNIP-9 compatible).
@@ -175,6 +176,94 @@ declare class ChipiExchanges {
     getUsdAmount(currencyAmount: number, currency: Currency, bearerToken: string): Promise<number>;
 }
 
+/**
+ * PaymasterAdapter implementation that uses Chipi's backend API for gasless transactions.
+ *
+ * Flow:
+ * 1. Detect wallet type from on-chain class hash
+ * 2. Call /transactions/prepare-typed-data to get TypedData
+ * 3. Call account.signMessage(typedData) — triggers wallet popup for external wallets
+ * 4. Call /transactions/execute-sponsored-transaction with signature
+ * 5. Return transaction hash
+ */
+declare class ChipiPaymasterAdapter implements PaymasterAdapter {
+    private readonly client;
+    private readonly bearerToken;
+    constructor(client: ChipiClient, bearerToken: string);
+    execute({ account, calls }: {
+        account: PaymasterAccount;
+        calls: Call[];
+    }): Promise<string>;
+}
+
+/** Options for the static X402Facilitator.create() factory */
+interface X402FacilitatorCreateOptions {
+    /** API public key for ChipiClient */
+    apiKey: string;
+    /** Bearer token for paymaster API calls */
+    bearerToken: string;
+    /** Custom nonce store (default: in-memory) */
+    nonceStore?: NonceStore;
+    /** RPC provider for on-chain signature verification */
+    provider?: X402FacilitatorConfig["provider"];
+}
+/**
+ * x402 Payment Facilitator for Starknet.
+ *
+ * Implements the "facilitator" role in the x402 protocol:
+ * - verify(): Validate payment signature, amount, asset, nonce replay
+ * - settle(): Execute the USDC transfer via Chipi's paymaster
+ *
+ * Settlement reuses Chipi's existing gasless infrastructure
+ * (prepare-typed-data → sign → execute-sponsored-transaction).
+ */
+declare class X402Facilitator {
+    private readonly client;
+    private readonly bearerToken;
+    private readonly nonceStore;
+    private readonly provider;
+    constructor(client: ChipiClient, bearerToken: string, config?: X402FacilitatorConfig);
+    /**
+     * Factory method for simpler instantiation.
+     *
+     * @example
+     * ```typescript
+     * const facilitator = X402Facilitator.create({
+     *   apiKey: process.env.CHIPI_API_KEY!,
+     *   bearerToken: process.env.CHIPI_BEARER_TOKEN!,
+     * });
+     * ```
+     */
+    static create(options: X402FacilitatorCreateOptions): X402Facilitator;
+    /**
+     * Verify a payment signature is valid (doesn't execute the transfer).
+     *
+     * Checks:
+     * 1. Nonce has not been used (replay protection)
+     * 2. Payment has not expired (validUntil > now)
+     * 3. Asset is USDC mainnet
+     * 4. Amount is positive
+     * 5. Addresses are non-empty
+     */
+    verify(payment: PaymentPayload): Promise<VerifyResponse>;
+    /**
+     * Verify the SNIP-12 signature on a payment payload.
+     *
+     * If an RPC provider is configured, reconstructs the typed data, computes the
+     * message hash, and calls `is_valid_signature()` on the sender's account contract.
+     * Otherwise falls back to a presence-only check (backwards compatible).
+     */
+    private verifySignature;
+    /**
+     * Settle a verified payment by executing the USDC transfer via paymaster.
+     *
+     * IMPORTANT: Mark nonce as consumed BEFORE executing to prevent concurrent replays.
+     * If the transfer fails after nonce consumption, the nonce is still burned
+     * (caller should implement idempotency at a higher level if needed).
+     */
+    settle(payment: PaymentPayload): Promise<SettleResponse>;
+}
+
 /**
  * Main Chipi SDK class
  */
@@ -193,6 +282,37 @@ declare class ChipiSDK {
      * Resolve bearer token - uses provided token or falls back to apiSecretKey
      */
     private resolveBearerToken;
+    /**
+     * Create a PaymasterAdapter for use with TxBuilder.sendSponsored().
+     *
+     * @example
+     * ```typescript
+     * const sdk = new ChipiServerSDK({ apiPublicKey: "pk_...", apiSecretKey: "sk_..." });
+     * const paymaster = sdk.createPaymasterAdapter();
+     *
+     * const txHash = await new TxBuilder(account, { paymaster })
+     *   .transfer(USDC, [{ to, amount }])
+     *   .sendSponsored(); // gasless!
+     * ```
+     */
+    createPaymasterAdapter(bearerToken?: string): ChipiPaymasterAdapter;
+    /**
+     * Create an X402Facilitator for verifying and settling x402 payments.
+     *
+     * @example
+     * ```typescript
+     * const facilitator = sdk.createX402Facilitator();
+     *
+     * // With custom nonce store (Redis)
+     * const facilitator = sdk.createX402Facilitator(bearerToken, {
+     *   nonceStore: {
+     *     has: async (nonce) => (await redis.sismember("x402:nonces", nonce)) === 1,
+     *     consume: async (nonce) => (await redis.sadd("x402:nonces", nonce)) === 1,
+     *   },
+     * });
+     * ```
+     */
+    createX402Facilitator(bearerToken?: string, config?: X402FacilitatorConfig): X402Facilitator;
     /**
      * Execute a gasless transaction
      */
@@ -238,6 +358,27 @@ declare class ChipiSDK {
         params: ExecuteWithSessionParams;
         bearerToken?: string;
     }): Promise<string>;
+    /**
+     * Sign SNIP-12 typed data without executing a transaction.
+     *
+     * Purely local operation: decrypt private key → sign → return { r, s }.
+     * No API calls are made. Useful for x402 payment signatures and other
+     * off-chain signing flows.
+     *
+     * @example
+     * ```typescript
+     * const { r, s } = await sdk.signTypedData({
+     *   params: {
+     *     encryptKey: pin,
+     *     wallet,
+     *     typedData: snip12TypedData,
+     *   },
+     * });
+     * ```
+     */
+    signTypedData({ params, }: {
+        params: SignTypedDataParams;
+    }): Promise<SignTypedDataResult>;
     /**
      * Transfer tokens
      */
@@ -286,6 +427,25 @@ declare class ChipiSDK {
     getSkuPurchase(id: string, bearerToken?: string): Promise<Transaction>;
     getSkuList(params: GetSkuListQuery, bearerToken?: string): Promise<PaginatedResponse<Sku>>;
     getSku(id: string, bearerToken?: string): Promise<Sku>;
+    /**
+     * Get a single transaction by hash or internal ID
+     */
+    getTransaction(hashOrId: string, bearerToken?: string): Promise<Transaction>;
+    /**
+     * Get on-chain transaction status (supports polling for confirmation)
+     */
+    getTransactionStatus(hash: string, bearerToken?: string): Promise<TransactionStatusResponse>;
+    /**
+     * Prepare a wallet upgrade (e.g., READY → CHIPI or CHIPI v29 → v33).
+     * Returns typed data that must be signed by the wallet owner.
+     * Server-only: requires API secret key.
+     */
+    prepareWalletUpgrade(params: PrepareWalletUpgradeParams, bearerToken?: string): Promise<PrepareWalletUpgradeResponse>;
+    /**
+     * Execute a wallet upgrade after signing.
+     * Server-only: requires API secret key.
+     */
+    executeWalletUpgrade(params: ExecuteWalletUpgradeParams, bearerToken?: string): Promise<ExecuteWalletUpgradeResponse>;
     getUsdAmount(currencyAmount: number, currency: Currency, bearerToken?: string): Promise<number>;
 }
 
@@ -362,7 +522,73 @@ declare class ChipiBrowserSDK extends ChipiSDK {
     constructor(config: ChipiBrowserSDKConfig);
 }
 
+/**
+ * Sign SNIP-12 typed data without executing a transaction.
+ *
+ * This is a purely local operation:
+ * 1. Decrypt the private key using the encryption key (PIN)
+ * 2. Create a starknet Account
+ * 3. Sign the typed data with account.signMessage()
+ * 4. Normalize and return { r, s }
+ *
+ * No API calls are made. Useful for x402 payment signatures and other
+ * off-chain signing flows where you need a SNIP-12 signature but don't
+ * want to execute a transaction.
+ */
+declare const signTypedData: ({ params, }: {
+    params: SignTypedDataParams;
+}) => Promise<SignTypedDataResult>;
+
 declare const encryptPrivateKey: (privateKey: string, password: string) => string;
 declare const decryptPrivateKey: (encryptedPrivateKey: string, password: string) => string;
 
-export { ChipiBrowserSDK, ChipiClient, ChipiSDK, ChipiServerSDK, ChipiSessions, ChipiSkuPurchases, ChipiSkus, ChipiTransactions, ChipiWallets, decryptPrivateKey, encryptPrivateKey };
+interface X402MiddlewareConfig {
+    /** x402 facilitator instance for verify + settle */
+    facilitator: X402Facilitator;
+    /** Payment configuration for this endpoint */
+    paymentConfig: X402PaymentConfig;
+    /** Verify-only mode: verify payment but don't settle (default: false) */
+    verifyOnly?: boolean;
+}
+/**
+ * Flat convenience config — detected when `amount` + `recipient` are present.
+ * Avoids nesting paymentConfig.
+ */
+interface X402MiddlewareFlatConfig {
+    /** x402 facilitator instance */
+    facilitator: X402Facilitator;
+    /** Amount in human-readable USDC (e.g. "0.01") */
+    amount: string;
+    /** Recipient (merchant) address */
+    recipient: string;
+    /** Human-readable description */
+    description?: string;
+    /** Verify-only mode (default: false) */
+    verifyOnly?: boolean;
+}
+/**
+ * Express-compatible middleware for monetizing API endpoints with x402.
+ *
+ * When no X-PAYMENT header is present, returns 402 with payment requirement.
+ * When a valid payment is present, verifies and settles it, then calls next().
+ * The settled transaction info is attached to `req.x402`.
+ *
+ * @example
+ * ```typescript
+ * // Nested config (original)
+ * x402Middleware({
+ *   facilitator,
+ *   paymentConfig: { amount: "0.01", payTo: "0xYOUR_ADDRESS" },
+ * })
+ *
+ * // Flat config (convenience)
+ * x402Middleware({
+ *   facilitator,
+ *   amount: "0.01",
+ *   recipient: "0xYOUR_ADDRESS",
+ * })
+ * ```
+ */
+declare function x402Middleware(config: X402MiddlewareConfig | X402MiddlewareFlatConfig): (req: any, res: any, next: any) => Promise<any>;
+
+export { ChipiBrowserSDK, ChipiClient, ChipiPaymasterAdapter, ChipiSDK, ChipiServerSDK, ChipiSessions, ChipiSkuPurchases, ChipiSkus, ChipiTransactions, ChipiWallets, X402Facilitator, type X402FacilitatorCreateOptions, type X402MiddlewareConfig, type X402MiddlewareFlatConfig, decryptPrivateKey, encryptPrivateKey, signTypedData, x402Middleware };