@circle-fin/app-kit 1.12.1 → 1.13.0

package/unifiedBalance.d.cts

@@ -717,6 +717,8 @@ declare enum Blockchain {
     Optimism_Sepolia = "Optimism_Sepolia",
     Pharos = "Pharos",
     Pharos_Testnet = "Pharos_Testnet",
+    Plasma = "Plasma",
+    Plasma_Testnet = "Plasma_Testnet",
     Polkadot_Asset_Hub = "Polkadot_Asset_Hub",
     Polkadot_Westmint = "Polkadot_Westmint",
     Plume = "Plume",
@@ -2299,7 +2301,7 @@ interface ExecuteParams {
  *   fromAddress: '0x...',
  *   toAddress: '0x...',
  *   amount: '1000000',
- *   apiKey: 'KIT_KEY:...',
+ *   apiKey: 'TEST_API_KEY:...',
  * })
  *
  * // Build token inputs with permit
@@ -2443,7 +2445,7 @@ interface ExecuteSwapEVMParams extends ActionParameters {
  *   fromAddress: 'YubQzu18FDqJRyNfG8JqHmsdbxhnoQqcKUHBdUkN6tP',
  *   toAddress: 'YubQzu18FDqJRyNfG8JqHmsdbxhnoQqcKUHBdUkN6tP',
  *   amount: '1000000',
- *   apiKey: 'KIT_KEY:...',
+ *   apiKey: 'TEST_API_KEY:...',
  * })
  *
  * // Prepare action parameters
@@ -3917,6 +3919,49 @@ interface ErrorInfo {
     type?: string;
 }
 
+/**
+ * Configuration options for the API polling utility.
+ *
+ * @remarks
+ * These settings control the behavior of the API polling process:
+ * - timeout: Maximum time (ms) to wait for each request before aborting
+ * - maxRetries: Maximum number of retry attempts for failed requests
+ * - retryDelay: Base delay (ms); constant wait for `'fixed'` or exponential seed for `'exponential'`
+ * - backoff: Retry-delay strategy, `'fixed'` (default) or `'exponential'`
+ * - maxRetryDelayMs: Optional ceiling (ms) for a single backoff wait
+ * - headers: Optional HTTP headers to include with each request
+ */
+interface ApiPollingConfig {
+    /** Maximum time in milliseconds to wait for each request */
+    timeout: number;
+    /** Maximum number of retry attempts for failed requests */
+    maxRetries: number;
+    /**
+     * Delay in milliseconds between retry attempts. With the default
+     * `backoff: 'fixed'` strategy this is the constant wait; with
+     * `backoff: 'exponential'` it is the base the exponential backoff grows
+     * from (see {@link pollApiWithValidation}).
+     */
+    retryDelay: number;
+    /**
+     * Retry-delay strategy. `'fixed'` (the default when omitted) waits a
+     * constant `retryDelay` between attempts; `'exponential'` grows the wait
+     * exponentially off `retryDelay` and randomizes it with full jitter, which
+     * spreads out retries so rate-limited (429) bursts do not retry in
+     * lockstep. Opt in per caller; existing callers keep the fixed delay.
+     */
+    backoff?: 'fixed' | 'exponential' | undefined;
+    /**
+     * Optional ceiling, in milliseconds, for a single backoff wait. Only
+     * applies when `backoff` is `'exponential'`: the exponential delay is
+     * capped at this value before jitter is applied. Defaults to
+     * {@link DEFAULT_MAX_RETRY_DELAY_MS} when omitted.
+     */
+    maxRetryDelayMs?: number | undefined;
+    /** Optional HTTP headers to include with requests */
+    headers?: Record<string, string> | undefined;
+}
+
 /**
  * A type-safe event emitter for managing action-based event subscriptions.
  *
@@ -4663,6 +4708,15 @@ interface SpendOptions {
      * @internal
      */
     onBroadcast?: (txHash: string) => void;
+    /**
+     * Partial polling config forwarded to every Gateway API request the spend
+     * makes (estimate, transfer, forwarder status, and the balance lookups on
+     * the auto-allocation path). The provider factory populates this from its
+     * `headers` config so a configured header reaches all spend-path calls.
+     *
+     * @internal
+     */
+    requestConfig?: Partial<ApiPollingConfig>;
 }
 /**
  * Result returned after a successful spend (mint) operation.
@@ -6494,6 +6548,26 @@ interface UnifiedBalanceKitConfig<TExtraProviders extends FlexibleGatewayProvide
      * @defaultValue false
      */
     excludeDefaultProviders?: boolean;
+    /**
+     * Custom HTTP headers forwarded with every Circle Gateway API request the
+     * default Gateway v1 provider makes (balances, deposits, spend estimate,
+     * transfer, forwarder status, and `/v1/info`).
+     *
+     * @remarks
+     * Headers are merged on top of the SDK defaults (such as `Content-Type`)
+     * rather than replacing them. Each header is forwarded as-is to Circle's
+     * API; the SDK does not interpret it. Only applies to the default provider —
+     * has no effect when `excludeDefaultProviders` is `true` or on custom
+     * providers supplied via `providers`.
+     *
+     * @example
+     * ```typescript
+     * const kit = new UnifiedBalanceKit({
+     *   headers: { 'X-Access-Key': process.env.GATEWAY_ACCESS_KEY! },
+     * })
+     * ```
+     */
+    headers?: Record<string, string>;
 }
 
 /**

package/unifiedBalance.d.mts

@@ -717,6 +717,8 @@ declare enum Blockchain {
     Optimism_Sepolia = "Optimism_Sepolia",
     Pharos = "Pharos",
     Pharos_Testnet = "Pharos_Testnet",
+    Plasma = "Plasma",
+    Plasma_Testnet = "Plasma_Testnet",
     Polkadot_Asset_Hub = "Polkadot_Asset_Hub",
     Polkadot_Westmint = "Polkadot_Westmint",
     Plume = "Plume",
@@ -2299,7 +2301,7 @@ interface ExecuteParams {
  *   fromAddress: '0x...',
  *   toAddress: '0x...',
  *   amount: '1000000',
- *   apiKey: 'KIT_KEY:...',
+ *   apiKey: 'TEST_API_KEY:...',
  * })
  *
  * // Build token inputs with permit
@@ -2443,7 +2445,7 @@ interface ExecuteSwapEVMParams extends ActionParameters {
  *   fromAddress: 'YubQzu18FDqJRyNfG8JqHmsdbxhnoQqcKUHBdUkN6tP',
  *   toAddress: 'YubQzu18FDqJRyNfG8JqHmsdbxhnoQqcKUHBdUkN6tP',
  *   amount: '1000000',
- *   apiKey: 'KIT_KEY:...',
+ *   apiKey: 'TEST_API_KEY:...',
  * })
  *
  * // Prepare action parameters
@@ -3917,6 +3919,49 @@ interface ErrorInfo {
     type?: string;
 }
 
+/**
+ * Configuration options for the API polling utility.
+ *
+ * @remarks
+ * These settings control the behavior of the API polling process:
+ * - timeout: Maximum time (ms) to wait for each request before aborting
+ * - maxRetries: Maximum number of retry attempts for failed requests
+ * - retryDelay: Base delay (ms); constant wait for `'fixed'` or exponential seed for `'exponential'`
+ * - backoff: Retry-delay strategy, `'fixed'` (default) or `'exponential'`
+ * - maxRetryDelayMs: Optional ceiling (ms) for a single backoff wait
+ * - headers: Optional HTTP headers to include with each request
+ */
+interface ApiPollingConfig {
+    /** Maximum time in milliseconds to wait for each request */
+    timeout: number;
+    /** Maximum number of retry attempts for failed requests */
+    maxRetries: number;
+    /**
+     * Delay in milliseconds between retry attempts. With the default
+     * `backoff: 'fixed'` strategy this is the constant wait; with
+     * `backoff: 'exponential'` it is the base the exponential backoff grows
+     * from (see {@link pollApiWithValidation}).
+     */
+    retryDelay: number;
+    /**
+     * Retry-delay strategy. `'fixed'` (the default when omitted) waits a
+     * constant `retryDelay` between attempts; `'exponential'` grows the wait
+     * exponentially off `retryDelay` and randomizes it with full jitter, which
+     * spreads out retries so rate-limited (429) bursts do not retry in
+     * lockstep. Opt in per caller; existing callers keep the fixed delay.
+     */
+    backoff?: 'fixed' | 'exponential' | undefined;
+    /**
+     * Optional ceiling, in milliseconds, for a single backoff wait. Only
+     * applies when `backoff` is `'exponential'`: the exponential delay is
+     * capped at this value before jitter is applied. Defaults to
+     * {@link DEFAULT_MAX_RETRY_DELAY_MS} when omitted.
+     */
+    maxRetryDelayMs?: number | undefined;
+    /** Optional HTTP headers to include with requests */
+    headers?: Record<string, string> | undefined;
+}
+
 /**
  * A type-safe event emitter for managing action-based event subscriptions.
  *
@@ -4663,6 +4708,15 @@ interface SpendOptions {
      * @internal
      */
     onBroadcast?: (txHash: string) => void;
+    /**
+     * Partial polling config forwarded to every Gateway API request the spend
+     * makes (estimate, transfer, forwarder status, and the balance lookups on
+     * the auto-allocation path). The provider factory populates this from its
+     * `headers` config so a configured header reaches all spend-path calls.
+     *
+     * @internal
+     */
+    requestConfig?: Partial<ApiPollingConfig>;
 }
 /**
  * Result returned after a successful spend (mint) operation.
@@ -6494,6 +6548,26 @@ interface UnifiedBalanceKitConfig<TExtraProviders extends FlexibleGatewayProvide
      * @defaultValue false
      */
     excludeDefaultProviders?: boolean;
+    /**
+     * Custom HTTP headers forwarded with every Circle Gateway API request the
+     * default Gateway v1 provider makes (balances, deposits, spend estimate,
+     * transfer, forwarder status, and `/v1/info`).
+     *
+     * @remarks
+     * Headers are merged on top of the SDK defaults (such as `Content-Type`)
+     * rather than replacing them. Each header is forwarded as-is to Circle's
+     * API; the SDK does not interpret it. Only applies to the default provider —
+     * has no effect when `excludeDefaultProviders` is `true` or on custom
+     * providers supplied via `providers`.
+     *
+     * @example
+     * ```typescript
+     * const kit = new UnifiedBalanceKit({
+     *   headers: { 'X-Access-Key': process.env.GATEWAY_ACCESS_KEY! },
+     * })
+     * ```
+     */
+    headers?: Record<string, string>;
 }
 
 /**

package/unifiedBalance.d.ts

@@ -717,6 +717,8 @@ declare enum Blockchain {
     Optimism_Sepolia = "Optimism_Sepolia",
     Pharos = "Pharos",
     Pharos_Testnet = "Pharos_Testnet",
+    Plasma = "Plasma",
+    Plasma_Testnet = "Plasma_Testnet",
     Polkadot_Asset_Hub = "Polkadot_Asset_Hub",
     Polkadot_Westmint = "Polkadot_Westmint",
     Plume = "Plume",
@@ -2299,7 +2301,7 @@ interface ExecuteParams {
  *   fromAddress: '0x...',
  *   toAddress: '0x...',
  *   amount: '1000000',
- *   apiKey: 'KIT_KEY:...',
+ *   apiKey: 'TEST_API_KEY:...',
  * })
  *
  * // Build token inputs with permit
@@ -2443,7 +2445,7 @@ interface ExecuteSwapEVMParams extends ActionParameters {
  *   fromAddress: 'YubQzu18FDqJRyNfG8JqHmsdbxhnoQqcKUHBdUkN6tP',
  *   toAddress: 'YubQzu18FDqJRyNfG8JqHmsdbxhnoQqcKUHBdUkN6tP',
  *   amount: '1000000',
- *   apiKey: 'KIT_KEY:...',
+ *   apiKey: 'TEST_API_KEY:...',
  * })
  *
  * // Prepare action parameters
@@ -3917,6 +3919,49 @@ interface ErrorInfo {
     type?: string;
 }
 
+/**
+ * Configuration options for the API polling utility.
+ *
+ * @remarks
+ * These settings control the behavior of the API polling process:
+ * - timeout: Maximum time (ms) to wait for each request before aborting
+ * - maxRetries: Maximum number of retry attempts for failed requests
+ * - retryDelay: Base delay (ms); constant wait for `'fixed'` or exponential seed for `'exponential'`
+ * - backoff: Retry-delay strategy, `'fixed'` (default) or `'exponential'`
+ * - maxRetryDelayMs: Optional ceiling (ms) for a single backoff wait
+ * - headers: Optional HTTP headers to include with each request
+ */
+interface ApiPollingConfig {
+    /** Maximum time in milliseconds to wait for each request */
+    timeout: number;
+    /** Maximum number of retry attempts for failed requests */
+    maxRetries: number;
+    /**
+     * Delay in milliseconds between retry attempts. With the default
+     * `backoff: 'fixed'` strategy this is the constant wait; with
+     * `backoff: 'exponential'` it is the base the exponential backoff grows
+     * from (see {@link pollApiWithValidation}).
+     */
+    retryDelay: number;
+    /**
+     * Retry-delay strategy. `'fixed'` (the default when omitted) waits a
+     * constant `retryDelay` between attempts; `'exponential'` grows the wait
+     * exponentially off `retryDelay` and randomizes it with full jitter, which
+     * spreads out retries so rate-limited (429) bursts do not retry in
+     * lockstep. Opt in per caller; existing callers keep the fixed delay.
+     */
+    backoff?: 'fixed' | 'exponential' | undefined;
+    /**
+     * Optional ceiling, in milliseconds, for a single backoff wait. Only
+     * applies when `backoff` is `'exponential'`: the exponential delay is
+     * capped at this value before jitter is applied. Defaults to
+     * {@link DEFAULT_MAX_RETRY_DELAY_MS} when omitted.
+     */
+    maxRetryDelayMs?: number | undefined;
+    /** Optional HTTP headers to include with requests */
+    headers?: Record<string, string> | undefined;
+}
+
 /**
  * A type-safe event emitter for managing action-based event subscriptions.
  *
@@ -4663,6 +4708,15 @@ interface SpendOptions {
      * @internal
      */
     onBroadcast?: (txHash: string) => void;
+    /**
+     * Partial polling config forwarded to every Gateway API request the spend
+     * makes (estimate, transfer, forwarder status, and the balance lookups on
+     * the auto-allocation path). The provider factory populates this from its
+     * `headers` config so a configured header reaches all spend-path calls.
+     *
+     * @internal
+     */
+    requestConfig?: Partial<ApiPollingConfig>;
 }
 /**
  * Result returned after a successful spend (mint) operation.
@@ -6494,6 +6548,26 @@ interface UnifiedBalanceKitConfig<TExtraProviders extends FlexibleGatewayProvide
      * @defaultValue false
      */
     excludeDefaultProviders?: boolean;
+    /**
+     * Custom HTTP headers forwarded with every Circle Gateway API request the
+     * default Gateway v1 provider makes (balances, deposits, spend estimate,
+     * transfer, forwarder status, and `/v1/info`).
+     *
+     * @remarks
+     * Headers are merged on top of the SDK defaults (such as `Content-Type`)
+     * rather than replacing them. Each header is forwarded as-is to Circle's
+     * API; the SDK does not interpret it. Only applies to the default provider —
+     * has no effect when `excludeDefaultProviders` is `true` or on custom
+     * providers supplied via `providers`.
+     *
+     * @example
+     * ```typescript
+     * const kit = new UnifiedBalanceKit({
+     *   headers: { 'X-Access-Key': process.env.GATEWAY_ACCESS_KEY! },
+     * })
+     * ```
+     */
+    headers?: Record<string, string>;
 }
 
 /**