uvd-x402-sdk 2.42.0 → 2.43.0

package/README.md

@@ -19,6 +19,7 @@ Users sign a message or transaction, and the Ultravioleta facilitator handles on
 - **Commerce Scheme**: `'commerce'` scheme alias for marketplace integrations (identical to `'escrow'` on-chain)
 - **`/accepts` Negotiation**: Discover facilitator capabilities before constructing payments
 - **Bazaar Discovery**: Register and discover paid resources across the x402 network
+- **Live Traffic Stream**: Subscribe to `GET /events` (SSE) for settlements as they happen — lossy live hint, not a ledger
 - **Facilitator Info**: Query version, supported networks, blacklist, and health
 
 ## Installation
@@ -1066,6 +1067,63 @@ console.log(stats.total, stats.visible, stats.byHealth.alive);
 
 Timestamps (`firstSeen`, `lastSeen`, `lastUpdated`, `health.lastChecked`) are Unix epoch **seconds**. Use `epochToDate()` to get a `Date`.
 
+## Live Traffic Stream (`GET /events`)
+
+The facilitator emits one Server-Sent Event per operation it handles, so you can
+render or react to live traffic without polling. Works in Node 18+ and browsers —
+it uses `fetch` and the response body stream rather than `EventSource`, so custom
+headers work too.
+
+```typescript
+import { streamTrafficEvents } from 'uvd-x402-sdk';
+
+for await (const event of streamTrafficEvents()) {
+  console.log(event.kind, event.network, event.ok, event.tx);
+}
+
+// Only settlements on the chains you care about. The facilitator has NO
+// server-side filter by network, so this runs client-side.
+const controller = new AbortController();
+const stream = streamTrafficEvents({
+  networks: ['base', 'polygon'],
+  kinds: ['settle'],
+  signal: controller.signal,
+});
+for await (const event of stream) console.log(event.tx, new Date(event.ts));
+```
+
+Three properties decide how you should use this:
+
+**It is lossy by design.** The facilitator will never slow down or fail a payment
+to keep an observer in sync, so an event you were not connected for is gone.
+Treat it as a live hint and use the chain as the source of truth — and note that
+*absence of events is not evidence that nothing happened*. On a quiet rail the
+only thing on the wire for minutes is a keepalive.
+
+**Failed operations are not published.** Only operations that resolved emit an
+event, so `ok: false` means "resolved and came back negative", never "blew up". A
+stream that looks healthy is not proof that the rail is.
+
+**Admission is bounded.** `/events` is public and unauthenticated, so it sheds
+with HTTP 503 + `Retry-After` at subscriber capacity, and returns 404 when the
+operator disabled it. Both throw `TrafficStreamError`, which carries `status` and
+`retryAfter`. Iteration does **not** reconnect on its own: reconnect policy
+belongs to you, because only you know whether a gap matters.
+
+> **Match the canonical network slug.** `network` is the name `/supported` uses,
+> which is not always the alias you may *send*. `skale` is accepted inbound, but
+> events always say `skale-base`. Keying on the alias silently drops every event
+> for that chain.
+
+| Field | Notes |
+|-------|-------|
+| `ts` | Unix epoch **milliseconds** (not seconds) |
+| `kind` | `'verify'` or `'settle'` |
+| `network` | Canonical slug, same as `/supported` |
+| `ok` | Resolved successfully? |
+| `payer` / `amount` / `asset` | Omitted in `minimal` detail mode |
+| `tx` | Present on `settle`, absent on `verify` — nothing settled yet |
+
 ## Facilitator Info
 
 Query the facilitator for version, supported networks, and compliance data.

package/dist/adapters/index.d.mts

@@ -1,4 +1,4 @@
-import { O as X402Version, k as PaymentResult } from '../index-DBCFd6mO.mjs';
+import { X as X402Version, b as PaymentResult } from '../index-NDRI_c7e.mjs';
 export { E as EnvKeyAdapter, O as OWSWallet, a as OWSWalletAdapter } from '../ows-CYIVd4xO.mjs';
 import '../wallet-0cX9Pw2F.mjs';
 

package/dist/adapters/index.d.ts

@@ -1,4 +1,4 @@
-import { O as X402Version, k as PaymentResult } from '../index-DBCFd6mO.js';
+import { X as X402Version, b as PaymentResult } from '../index-NDRI_c7e.js';
 export { E as EnvKeyAdapter, O as OWSWallet, a as OWSWalletAdapter } from '../ows-DTDixPzO.js';
 import '../wallet-0cX9Pw2F.js';
 

package/dist/backend/index.d.mts

@@ -1,5 +1,5 @@
 import { S as SigningWalletAdapter } from '../wallet-0cX9Pw2F.mjs';
-import { w as X402Header, O as X402Version } from '../index-DBCFd6mO.mjs';
+import { e as X402Header, X as X402Version } from '../index-NDRI_c7e.mjs';
 
 /**
  * Payment requirements sent to the facilitator

package/dist/backend/index.d.ts

@@ -1,5 +1,5 @@
 import { S as SigningWalletAdapter } from '../wallet-0cX9Pw2F.js';
-import { w as X402Header, O as X402Version } from '../index-DBCFd6mO.js';
+import { e as X402Header, X as X402Version } from '../index-NDRI_c7e.js';
 
 /**
  * Payment requirements sent to the facilitator

package/dist/{index-BJrBRC2u.d.mts → index-Bw4S80Ph.d.mts}

@@ -1,4 +1,4 @@
-import { p as X402ClientConfig, h as PaymentInfo, k as PaymentResult, o as WalletState, b as ChainConfig, t as X402Event, v as X402EventHandler, g as NetworkType, n as TokenType, T as TokenConfig } from './index-DBCFd6mO.mjs';
+import { a as X402ClientConfig, P as PaymentInfo, b as PaymentResult, d as WalletState, C as ChainConfig, v as X402Event, x as X402EventHandler, c as NetworkType, T as TokenType, q as TokenConfig } from './index-NDRI_c7e.mjs';
 
 /**
  * uvd-x402-sdk - Main Client
@@ -258,4 +258,4 @@ declare function isTokenSupported(chainName: string, tokenType: TokenType): bool
  */
 declare function getChainsByToken(tokenType: TokenType): ChainConfig[];
 
-export { DEFAULT_CHAIN as D, SUPPORTED_CHAINS as S, X402Client as X, DEFAULT_FACILITATOR_URL as a, getChainById as b, getChainByName as c, getChainsByNetworkType as d, getChainsByToken as e, getEVMChainIds as f, getAlgorandChains as g, getEnabledChains as h, getExplorerAddressUrl as i, getExplorerTxUrl as j, getNetworkType as k, getSVMChains as l, getSuiChains as m, getSupportedTokens as n, getTokenConfig as o, getXRPLChains as p, isAlgorandChain as q, isChainSupported as r, isSVMChain as s, isSuiChain as t, isTokenSupported as u, isXRPLChain as v };
+export { DEFAULT_CHAIN as D, SUPPORTED_CHAINS as S, X402Client as X, DEFAULT_FACILITATOR_URL as a, getAlgorandChains as b, getChainById as c, getChainsByNetworkType as d, getChainsByToken as e, getEVMChainIds as f, getChainByName as g, getEnabledChains as h, getExplorerAddressUrl as i, getExplorerTxUrl as j, getNetworkType as k, getSVMChains as l, getSuiChains as m, getSupportedTokens as n, getTokenConfig as o, getXRPLChains as p, isAlgorandChain as q, isChainSupported as r, isSVMChain as s, isSuiChain as t, isTokenSupported as u, isXRPLChain as v };

package/dist/{index-m2PwYmcQ.d.ts → index-Dgus5K-7.d.ts}

@@ -1,4 +1,4 @@
-import { p as X402ClientConfig, h as PaymentInfo, k as PaymentResult, o as WalletState, b as ChainConfig, t as X402Event, v as X402EventHandler, g as NetworkType, n as TokenType, T as TokenConfig } from './index-DBCFd6mO.js';
+import { a as X402ClientConfig, P as PaymentInfo, b as PaymentResult, d as WalletState, C as ChainConfig, v as X402Event, x as X402EventHandler, c as NetworkType, T as TokenType, q as TokenConfig } from './index-NDRI_c7e.js';
 
 /**
  * uvd-x402-sdk - Main Client
@@ -258,4 +258,4 @@ declare function isTokenSupported(chainName: string, tokenType: TokenType): bool
  */
 declare function getChainsByToken(tokenType: TokenType): ChainConfig[];
 
-export { DEFAULT_CHAIN as D, SUPPORTED_CHAINS as S, X402Client as X, DEFAULT_FACILITATOR_URL as a, getChainById as b, getChainByName as c, getChainsByNetworkType as d, getChainsByToken as e, getEVMChainIds as f, getAlgorandChains as g, getEnabledChains as h, getExplorerAddressUrl as i, getExplorerTxUrl as j, getNetworkType as k, getSVMChains as l, getSuiChains as m, getSupportedTokens as n, getTokenConfig as o, getXRPLChains as p, isAlgorandChain as q, isChainSupported as r, isSVMChain as s, isSuiChain as t, isTokenSupported as u, isXRPLChain as v };
+export { DEFAULT_CHAIN as D, SUPPORTED_CHAINS as S, X402Client as X, DEFAULT_FACILITATOR_URL as a, getAlgorandChains as b, getChainById as c, getChainsByNetworkType as d, getChainsByToken as e, getEVMChainIds as f, getChainByName as g, getEnabledChains as h, getExplorerAddressUrl as i, getExplorerTxUrl as j, getNetworkType as k, getSVMChains as l, getSuiChains as m, getSupportedTokens as n, getTokenConfig as o, getXRPLChains as p, isAlgorandChain as q, isChainSupported as r, isSVMChain as s, isSuiChain as t, isTokenSupported as u, isXRPLChain as v };

package/dist/{index-DBCFd6mO.d.mts → index-NDRI_c7e.d.mts}

@@ -648,4 +648,4 @@ declare class X402Error extends Error {
     constructor(message: string, code: X402ErrorCode, details?: unknown);
 }
 
-export { type AlgorandPaymentPayload as A, type X402NEARPayload as B, CAIP2_IDENTIFIERS as C, DEFAULT_CONFIG as D, type EIP712Domain as E, type X402PayloadData as F, type X402PaymentOption as G, type X402Scheme as H, type X402SettlementAccountPayload as I, type X402SolanaPayload as J, type X402StellarPayload as K, type X402SuiPayload as L, type MultiPaymentConfig as M, type NEARPaymentPayload as N, type X402Version as O, type PaymentHeaders as P, type X402XRPLPayload as Q, type XRPLPaymentPayload as R, type SolanaPaymentPayload as S, type TokenConfig as T, type USDCConfig as U, type WalletAdapter as W, type X402AlgorandPayload as X, CAIP2_TO_CHAIN as a, type ChainConfig as b, type EIP712Types as c, type EVMPaymentPayload as d, type NativeCurrency as e, type NetworkBalance as f, type NetworkType as g, type PaymentInfo as h, type PaymentPayload as i, type PaymentRequest as j, type PaymentResult as k, type StellarPaymentPayload as l, type SuiPaymentPayload as m, type TokenType as n, type WalletState as o, type X402ClientConfig as p, type X402EVMPayload as q, X402Error as r, type X402ErrorCode as s, type X402Event as t, type X402EventData as u, type X402EventHandler as v, type X402Header as w, type X402HeaderName as x, type X402HeaderV1 as y, type X402HeaderV2 as z };
+export { type AlgorandPaymentPayload as A, type X402HeaderV2 as B, type ChainConfig as C, DEFAULT_CONFIG as D, type EIP712Domain as E, type X402NEARPayload as F, type X402PayloadData as G, type X402PaymentOption as H, type X402Scheme as I, type X402SettlementAccountPayload as J, type X402SolanaPayload as K, type X402StellarPayload as L, type MultiPaymentConfig as M, type NetworkBalance as N, type X402SuiPayload as O, type PaymentInfo as P, type X402XRPLPayload as Q, type XRPLPaymentPayload as R, type SolanaPaymentPayload as S, type TokenType as T, type USDCConfig as U, type WalletAdapter as W, type X402Version as X, type X402ClientConfig as a, type PaymentResult as b, type NetworkType as c, type WalletState as d, type X402Header as e, CAIP2_IDENTIFIERS as f, CAIP2_TO_CHAIN as g, type EIP712Types as h, type EVMPaymentPayload as i, type NEARPaymentPayload as j, type NativeCurrency as k, type PaymentHeaders as l, type PaymentPayload as m, type PaymentRequest as n, type StellarPaymentPayload as o, type SuiPaymentPayload as p, type TokenConfig as q, type X402AlgorandPayload as r, type X402EVMPayload as s, X402Error as t, type X402ErrorCode as u, type X402Event as v, type X402EventData as w, type X402EventHandler as x, type X402HeaderName as y, type X402HeaderV1 as z };

package/dist/{index-DBCFd6mO.d.ts → index-NDRI_c7e.d.ts}

@@ -648,4 +648,4 @@ declare class X402Error extends Error {
     constructor(message: string, code: X402ErrorCode, details?: unknown);
 }
 
-export { type AlgorandPaymentPayload as A, type X402NEARPayload as B, CAIP2_IDENTIFIERS as C, DEFAULT_CONFIG as D, type EIP712Domain as E, type X402PayloadData as F, type X402PaymentOption as G, type X402Scheme as H, type X402SettlementAccountPayload as I, type X402SolanaPayload as J, type X402StellarPayload as K, type X402SuiPayload as L, type MultiPaymentConfig as M, type NEARPaymentPayload as N, type X402Version as O, type PaymentHeaders as P, type X402XRPLPayload as Q, type XRPLPaymentPayload as R, type SolanaPaymentPayload as S, type TokenConfig as T, type USDCConfig as U, type WalletAdapter as W, type X402AlgorandPayload as X, CAIP2_TO_CHAIN as a, type ChainConfig as b, type EIP712Types as c, type EVMPaymentPayload as d, type NativeCurrency as e, type NetworkBalance as f, type NetworkType as g, type PaymentInfo as h, type PaymentPayload as i, type PaymentRequest as j, type PaymentResult as k, type StellarPaymentPayload as l, type SuiPaymentPayload as m, type TokenType as n, type WalletState as o, type X402ClientConfig as p, type X402EVMPayload as q, X402Error as r, type X402ErrorCode as s, type X402Event as t, type X402EventData as u, type X402EventHandler as v, type X402Header as w, type X402HeaderName as x, type X402HeaderV1 as y, type X402HeaderV2 as z };
+export { type AlgorandPaymentPayload as A, type X402HeaderV2 as B, type ChainConfig as C, DEFAULT_CONFIG as D, type EIP712Domain as E, type X402NEARPayload as F, type X402PayloadData as G, type X402PaymentOption as H, type X402Scheme as I, type X402SettlementAccountPayload as J, type X402SolanaPayload as K, type X402StellarPayload as L, type MultiPaymentConfig as M, type NetworkBalance as N, type X402SuiPayload as O, type PaymentInfo as P, type X402XRPLPayload as Q, type XRPLPaymentPayload as R, type SolanaPaymentPayload as S, type TokenType as T, type USDCConfig as U, type WalletAdapter as W, type X402Version as X, type X402ClientConfig as a, type PaymentResult as b, type NetworkType as c, type WalletState as d, type X402Header as e, CAIP2_IDENTIFIERS as f, CAIP2_TO_CHAIN as g, type EIP712Types as h, type EVMPaymentPayload as i, type NEARPaymentPayload as j, type NativeCurrency as k, type PaymentHeaders as l, type PaymentPayload as m, type PaymentRequest as n, type StellarPaymentPayload as o, type SuiPaymentPayload as p, type TokenConfig as q, type X402AlgorandPayload as r, type X402EVMPayload as s, X402Error as t, type X402ErrorCode as u, type X402Event as v, type X402EventData as w, type X402EventHandler as x, type X402HeaderName as y, type X402HeaderV1 as z };

package/dist/index.d.mts

@@ -1,6 +1,6 @@
-export { D as DEFAULT_CHAIN, a as DEFAULT_FACILITATOR_URL, S as SUPPORTED_CHAINS, X as X402Client, g as getAlgorandChains, b as getChainById, c as getChainByName, d as getChainsByNetworkType, e as getChainsByToken, f as getEVMChainIds, h as getEnabledChains, i as getExplorerAddressUrl, j as getExplorerTxUrl, k as getNetworkType, l as getSVMChains, m as getSuiChains, n as getSupportedTokens, o as getTokenConfig, p as getXRPLChains, q as isAlgorandChain, r as isChainSupported, s as isSVMChain, t as isSuiChain, u as isTokenSupported, v as isXRPLChain } from './index-BJrBRC2u.mjs';
+export { D as DEFAULT_CHAIN, a as DEFAULT_FACILITATOR_URL, S as SUPPORTED_CHAINS, X as X402Client, b as getAlgorandChains, c as getChainById, g as getChainByName, d as getChainsByNetworkType, e as getChainsByToken, f as getEVMChainIds, h as getEnabledChains, i as getExplorerAddressUrl, j as getExplorerTxUrl, k as getNetworkType, l as getSVMChains, m as getSuiChains, n as getSupportedTokens, o as getTokenConfig, p as getXRPLChains, q as isAlgorandChain, r as isChainSupported, s as isSVMChain, t as isSuiChain, u as isTokenSupported, v as isXRPLChain } from './index-Bw4S80Ph.mjs';
 export { DEFAULT_PAYMENT_HEADER, PAYMENT_HEADER_NAMES, caip2ToChain, chainToCAIP2, convertX402Header, createPaymentHeaders, createX402Header, createX402V1Header, createX402V2Header, decodeX402Header, detectX402Version, encodeX402Header, generatePaymentOptions, getPaymentHeader, isCAIP2Format, parseNetworkIdentifier, validateAmount, validateRecipient } from './utils/index.mjs';
-export { A as AlgorandPaymentPayload, C as CAIP2_IDENTIFIERS, a as CAIP2_TO_CHAIN, b as ChainConfig, D as DEFAULT_CONFIG, E as EIP712Domain, c as EIP712Types, d as EVMPaymentPayload, M as MultiPaymentConfig, N as NEARPaymentPayload, e as NativeCurrency, f as NetworkBalance, g as NetworkType, P as PaymentHeaders, h as PaymentInfo, i as PaymentPayload, j as PaymentRequest, k as PaymentResult, S as SolanaPaymentPayload, l as StellarPaymentPayload, m as SuiPaymentPayload, T as TokenConfig, n as TokenType, U as USDCConfig, W as WalletAdapter, o as WalletState, X as X402AlgorandPayload, p as X402ClientConfig, q as X402EVMPayload, r as X402Error, s as X402ErrorCode, t as X402Event, u as X402EventData, v as X402EventHandler, w as X402Header, x as X402HeaderName, y as X402HeaderV1, z as X402HeaderV2, B as X402NEARPayload, F as X402PayloadData, G as X402PaymentOption, H as X402Scheme, I as X402SettlementAccountPayload, J as X402SolanaPayload, K as X402StellarPayload, L as X402SuiPayload, O as X402Version, Q as X402XRPLPayload, R as XRPLPaymentPayload } from './index-DBCFd6mO.mjs';
+export { A as AlgorandPaymentPayload, f as CAIP2_IDENTIFIERS, g as CAIP2_TO_CHAIN, C as ChainConfig, D as DEFAULT_CONFIG, E as EIP712Domain, h as EIP712Types, i as EVMPaymentPayload, M as MultiPaymentConfig, j as NEARPaymentPayload, k as NativeCurrency, N as NetworkBalance, c as NetworkType, l as PaymentHeaders, P as PaymentInfo, m as PaymentPayload, n as PaymentRequest, b as PaymentResult, S as SolanaPaymentPayload, o as StellarPaymentPayload, p as SuiPaymentPayload, q as TokenConfig, T as TokenType, U as USDCConfig, W as WalletAdapter, d as WalletState, r as X402AlgorandPayload, a as X402ClientConfig, s as X402EVMPayload, t as X402Error, u as X402ErrorCode, v as X402Event, w as X402EventData, x as X402EventHandler, e as X402Header, y as X402HeaderName, z as X402HeaderV1, B as X402HeaderV2, F as X402NEARPayload, G as X402PayloadData, H as X402PaymentOption, I as X402Scheme, J as X402SettlementAccountPayload, K as X402SolanaPayload, L as X402StellarPayload, O as X402SuiPayload, X as X402Version, Q as X402XRPLPayload, R as XRPLPaymentPayload } from './index-NDRI_c7e.mjs';
 export { E as EIP3009Authorization, a as EIP3009Params, S as SigningWalletAdapter } from './wallet-0cX9Pw2F.mjs';
 export { E as EnvKeyAdapter, O as OWSWallet, a as OWSWalletAdapter } from './ows-CYIVd4xO.mjs';
 export { FacilitatorClient, FacilitatorClientOptions, HonoMiddlewareOptions, PaymentAcceptance, PaymentMiddlewareOptions, VerifiedPaymentState, X402_CORS_HEADERS, X402_HEADER_NAMES, buildPaymentRequirements, buildSettleRequest, buildVerifyRequest, create402Response, createHonoMiddleware, createPaymentMiddleware, extractPaymentFromHeaders, getCorsHeaders } from './backend/index.mjs';
@@ -99,4 +99,149 @@ declare function getFacilitatorAddress(chainName: string, networkType?: string):
  */
 type FacilitatorAddresses = typeof FACILITATOR_ADDRESSES;
 
-export { FACILITATOR_ADDRESSES, type FacilitatorAddresses, getFacilitatorAddress };
+/**
+ * Live traffic stream client (`GET /events`, Server-Sent Events).
+ *
+ * The facilitator emits one event per operation it handles, so you can render or
+ * react to live traffic without polling and without scraping logs.
+ *
+ * @example
+ * ```ts
+ * import { streamTrafficEvents } from '@ultravioletadao/x402-sdk';
+ *
+ * for await (const event of streamTrafficEvents()) {
+ *   console.log(event.kind, event.network, event.ok, event.tx);
+ * }
+ * ```
+ *
+ * @example Only settlements on the chains you care about. The facilitator has NO
+ * server-side filter by network, so this is applied client-side.
+ * ```ts
+ * const stream = streamTrafficEvents({
+ *   networks: ['base', 'polygon'],
+ *   kinds: ['settle'],
+ * });
+ * for await (const event of stream) console.log(event.tx);
+ * ```
+ *
+ * Three properties of this stream decide how you should use it:
+ *
+ * **It is lossy by design.** The facilitator will never slow down or fail a
+ * payment to keep an observer in sync, so an event you were not connected for is
+ * simply gone. Treat it as a live hint and use the chain as the source of truth.
+ * Absence of events is NOT evidence that nothing happened.
+ *
+ * **Failed operations are not published.** Only operations that resolved emit an
+ * event, so `ok: false` means "resolved and came back negative", never "blew up".
+ * A stream that looks healthy is not proof that the rail is.
+ *
+ * **Admission is bounded.** The endpoint is public and unauthenticated, so it
+ * sheds with HTTP 503 + `Retry-After` once too many subscribers are connected,
+ * and returns 404 when the operator disabled it.
+ */
+/** Operations the facilitator publishes. */
+type TrafficEventKind = 'verify' | 'settle';
+/** Operations the facilitator publishes, as a value. */
+declare const EVENT_KINDS: readonly TrafficEventKind[];
+/**
+ * The stream sends a `:keepalive` comment on this cadence, so any read timeout
+ * you add must comfortably exceed it or you will kill healthy connections on an
+ * idle rail.
+ */
+declare const KEEPALIVE_INTERVAL_MS = 15000;
+/**
+ * One facilitator operation, as seen by an observer.
+ *
+ * Optional fields are *omitted* by the facilitator rather than sent as null, and
+ * they are all absent when the operator runs the stream in `minimal` detail
+ * mode. Never assume `payer` or `amount` is present.
+ */
+interface TrafficEvent {
+    /** Unix epoch **milliseconds**, UTC. Note: milliseconds, not seconds. */
+    ts: number;
+    kind: TrafficEventKind | string;
+    /**
+     * The facilitator's canonical network slug, the same one `/supported` uses.
+     *
+     * Beware: this is the *canonical* name, which is not always the alias you are
+     * allowed to send. `skale` is accepted on the way in, but this field always
+     * says `skale-base`. Match on the canonical form or you will silently drop
+     * every event for that chain.
+     */
+    network: string;
+    /** Resolved successfully? False means resolved-negative, not errored. */
+    ok: boolean;
+    payer?: string;
+    /** Present on `settle`, absent on `verify` — nothing settled yet. */
+    tx?: string;
+    amount?: string;
+    asset?: string;
+}
+/** Raised when the stream cannot be opened. Carries the HTTP status. */
+declare class TrafficStreamError extends Error {
+    readonly status: number;
+    /** Seconds to wait before retrying, when the server said so (503). */
+    readonly retryAfter?: number;
+    constructor(message: string, status: number, retryAfter?: number);
+}
+interface StreamTrafficEventsOptions {
+    /** Facilitator to subscribe to. Defaults to the Ultravioleta DAO facilitator. */
+    facilitatorUrl?: string;
+    /**
+     * Only yield events for these networks. Applied client-side — the facilitator
+     * has no per-network filter, so every event still crosses the wire. Match the
+     * canonical slug (`skale-base`, not `skale`).
+     */
+    networks?: string[];
+    /** Only yield these operations. */
+    kinds?: TrafficEventKind[];
+    /** Abort the stream. Without one, iteration ends only when the server closes. */
+    signal?: AbortSignal;
+    /** Extra headers, for a deployment that gates the stream behind authorization. */
+    headers?: Record<string, string>;
+}
+/** One decoded SSE frame: the event name and its raw data payload. */
+interface SSEFrame {
+    event: string;
+    data: string;
+}
+/**
+ * Incremental Server-Sent Events parser.
+ *
+ * Kept separate from the network layer so the framing can be tested without a
+ * socket — which matters, because the case that breaks in production is an idle
+ * rail sending nothing but keepalive comments for minutes.
+ */
+declare class SSEParser {
+    private buffer;
+    private eventName;
+    private dataLines;
+    /** Feed a chunk of the response body; get back whatever frames completed. */
+    push(chunk: string): SSEFrame[];
+}
+/**
+ * Decode one SSE frame into a {@link TrafficEvent}.
+ *
+ * Returns null for anything malformed: a single bad message must never tear down
+ * a long-lived stream — the connection is worth more than the message.
+ */
+declare function parseTrafficEvent(frame: SSEFrame): TrafficEvent | null;
+/** Does this event pass the caller's client-side filters? */
+declare function matchesFilters(event: TrafficEvent, options: Pick<StreamTrafficEventsOptions, 'networks' | 'kinds'>): boolean;
+/**
+ * Subscribe to the facilitator's live traffic stream.
+ *
+ * Works in Node 18+ and in browsers: it uses `fetch` and the response body
+ * stream rather than `EventSource`, so it also works where custom headers are
+ * needed (`EventSource` cannot send them).
+ *
+ * Iteration ends when the server closes the connection or the `signal` aborts.
+ * It does NOT reconnect on its own — reconnect policy belongs to the caller, who
+ * is the only one who knows whether a gap matters.
+ *
+ * @throws {TrafficStreamError} 404 when the operator disabled the stream, 503
+ * with `retryAfter` when it is at subscriber capacity.
+ */
+declare function streamTrafficEvents(options?: StreamTrafficEventsOptions): AsyncGenerator<TrafficEvent, void, undefined>;
+
+export { EVENT_KINDS, FACILITATOR_ADDRESSES, type FacilitatorAddresses, KEEPALIVE_INTERVAL_MS, type SSEFrame, SSEParser, type StreamTrafficEventsOptions, type TrafficEvent, type TrafficEventKind, TrafficStreamError, getFacilitatorAddress, matchesFilters, parseTrafficEvent, streamTrafficEvents };

package/dist/index.d.ts

@@ -1,6 +1,6 @@
-export { D as DEFAULT_CHAIN, a as DEFAULT_FACILITATOR_URL, S as SUPPORTED_CHAINS, X as X402Client, g as getAlgorandChains, b as getChainById, c as getChainByName, d as getChainsByNetworkType, e as getChainsByToken, f as getEVMChainIds, h as getEnabledChains, i as getExplorerAddressUrl, j as getExplorerTxUrl, k as getNetworkType, l as getSVMChains, m as getSuiChains, n as getSupportedTokens, o as getTokenConfig, p as getXRPLChains, q as isAlgorandChain, r as isChainSupported, s as isSVMChain, t as isSuiChain, u as isTokenSupported, v as isXRPLChain } from './index-m2PwYmcQ.js';
+export { D as DEFAULT_CHAIN, a as DEFAULT_FACILITATOR_URL, S as SUPPORTED_CHAINS, X as X402Client, b as getAlgorandChains, c as getChainById, g as getChainByName, d as getChainsByNetworkType, e as getChainsByToken, f as getEVMChainIds, h as getEnabledChains, i as getExplorerAddressUrl, j as getExplorerTxUrl, k as getNetworkType, l as getSVMChains, m as getSuiChains, n as getSupportedTokens, o as getTokenConfig, p as getXRPLChains, q as isAlgorandChain, r as isChainSupported, s as isSVMChain, t as isSuiChain, u as isTokenSupported, v as isXRPLChain } from './index-Dgus5K-7.js';
 export { DEFAULT_PAYMENT_HEADER, PAYMENT_HEADER_NAMES, caip2ToChain, chainToCAIP2, convertX402Header, createPaymentHeaders, createX402Header, createX402V1Header, createX402V2Header, decodeX402Header, detectX402Version, encodeX402Header, generatePaymentOptions, getPaymentHeader, isCAIP2Format, parseNetworkIdentifier, validateAmount, validateRecipient } from './utils/index.js';
-export { A as AlgorandPaymentPayload, C as CAIP2_IDENTIFIERS, a as CAIP2_TO_CHAIN, b as ChainConfig, D as DEFAULT_CONFIG, E as EIP712Domain, c as EIP712Types, d as EVMPaymentPayload, M as MultiPaymentConfig, N as NEARPaymentPayload, e as NativeCurrency, f as NetworkBalance, g as NetworkType, P as PaymentHeaders, h as PaymentInfo, i as PaymentPayload, j as PaymentRequest, k as PaymentResult, S as SolanaPaymentPayload, l as StellarPaymentPayload, m as SuiPaymentPayload, T as TokenConfig, n as TokenType, U as USDCConfig, W as WalletAdapter, o as WalletState, X as X402AlgorandPayload, p as X402ClientConfig, q as X402EVMPayload, r as X402Error, s as X402ErrorCode, t as X402Event, u as X402EventData, v as X402EventHandler, w as X402Header, x as X402HeaderName, y as X402HeaderV1, z as X402HeaderV2, B as X402NEARPayload, F as X402PayloadData, G as X402PaymentOption, H as X402Scheme, I as X402SettlementAccountPayload, J as X402SolanaPayload, K as X402StellarPayload, L as X402SuiPayload, O as X402Version, Q as X402XRPLPayload, R as XRPLPaymentPayload } from './index-DBCFd6mO.js';
+export { A as AlgorandPaymentPayload, f as CAIP2_IDENTIFIERS, g as CAIP2_TO_CHAIN, C as ChainConfig, D as DEFAULT_CONFIG, E as EIP712Domain, h as EIP712Types, i as EVMPaymentPayload, M as MultiPaymentConfig, j as NEARPaymentPayload, k as NativeCurrency, N as NetworkBalance, c as NetworkType, l as PaymentHeaders, P as PaymentInfo, m as PaymentPayload, n as PaymentRequest, b as PaymentResult, S as SolanaPaymentPayload, o as StellarPaymentPayload, p as SuiPaymentPayload, q as TokenConfig, T as TokenType, U as USDCConfig, W as WalletAdapter, d as WalletState, r as X402AlgorandPayload, a as X402ClientConfig, s as X402EVMPayload, t as X402Error, u as X402ErrorCode, v as X402Event, w as X402EventData, x as X402EventHandler, e as X402Header, y as X402HeaderName, z as X402HeaderV1, B as X402HeaderV2, F as X402NEARPayload, G as X402PayloadData, H as X402PaymentOption, I as X402Scheme, J as X402SettlementAccountPayload, K as X402SolanaPayload, L as X402StellarPayload, O as X402SuiPayload, X as X402Version, Q as X402XRPLPayload, R as XRPLPaymentPayload } from './index-NDRI_c7e.js';
 export { E as EIP3009Authorization, a as EIP3009Params, S as SigningWalletAdapter } from './wallet-0cX9Pw2F.js';
 export { E as EnvKeyAdapter, O as OWSWallet, a as OWSWalletAdapter } from './ows-DTDixPzO.js';
 export { FacilitatorClient, FacilitatorClientOptions, HonoMiddlewareOptions, PaymentAcceptance, PaymentMiddlewareOptions, VerifiedPaymentState, X402_CORS_HEADERS, X402_HEADER_NAMES, buildPaymentRequirements, buildSettleRequest, buildVerifyRequest, create402Response, createHonoMiddleware, createPaymentMiddleware, extractPaymentFromHeaders, getCorsHeaders } from './backend/index.js';
@@ -99,4 +99,149 @@ declare function getFacilitatorAddress(chainName: string, networkType?: string):
  */
 type FacilitatorAddresses = typeof FACILITATOR_ADDRESSES;
 
-export { FACILITATOR_ADDRESSES, type FacilitatorAddresses, getFacilitatorAddress };
+/**
+ * Live traffic stream client (`GET /events`, Server-Sent Events).
+ *
+ * The facilitator emits one event per operation it handles, so you can render or
+ * react to live traffic without polling and without scraping logs.
+ *
+ * @example
+ * ```ts
+ * import { streamTrafficEvents } from '@ultravioletadao/x402-sdk';
+ *
+ * for await (const event of streamTrafficEvents()) {
+ *   console.log(event.kind, event.network, event.ok, event.tx);
+ * }
+ * ```
+ *
+ * @example Only settlements on the chains you care about. The facilitator has NO
+ * server-side filter by network, so this is applied client-side.
+ * ```ts
+ * const stream = streamTrafficEvents({
+ *   networks: ['base', 'polygon'],
+ *   kinds: ['settle'],
+ * });
+ * for await (const event of stream) console.log(event.tx);
+ * ```
+ *
+ * Three properties of this stream decide how you should use it:
+ *
+ * **It is lossy by design.** The facilitator will never slow down or fail a
+ * payment to keep an observer in sync, so an event you were not connected for is
+ * simply gone. Treat it as a live hint and use the chain as the source of truth.
+ * Absence of events is NOT evidence that nothing happened.
+ *
+ * **Failed operations are not published.** Only operations that resolved emit an
+ * event, so `ok: false` means "resolved and came back negative", never "blew up".
+ * A stream that looks healthy is not proof that the rail is.
+ *
+ * **Admission is bounded.** The endpoint is public and unauthenticated, so it
+ * sheds with HTTP 503 + `Retry-After` once too many subscribers are connected,
+ * and returns 404 when the operator disabled it.
+ */
+/** Operations the facilitator publishes. */
+type TrafficEventKind = 'verify' | 'settle';
+/** Operations the facilitator publishes, as a value. */
+declare const EVENT_KINDS: readonly TrafficEventKind[];
+/**
+ * The stream sends a `:keepalive` comment on this cadence, so any read timeout
+ * you add must comfortably exceed it or you will kill healthy connections on an
+ * idle rail.
+ */
+declare const KEEPALIVE_INTERVAL_MS = 15000;
+/**
+ * One facilitator operation, as seen by an observer.
+ *
+ * Optional fields are *omitted* by the facilitator rather than sent as null, and
+ * they are all absent when the operator runs the stream in `minimal` detail
+ * mode. Never assume `payer` or `amount` is present.
+ */
+interface TrafficEvent {
+    /** Unix epoch **milliseconds**, UTC. Note: milliseconds, not seconds. */
+    ts: number;
+    kind: TrafficEventKind | string;
+    /**
+     * The facilitator's canonical network slug, the same one `/supported` uses.
+     *
+     * Beware: this is the *canonical* name, which is not always the alias you are
+     * allowed to send. `skale` is accepted on the way in, but this field always
+     * says `skale-base`. Match on the canonical form or you will silently drop
+     * every event for that chain.
+     */
+    network: string;
+    /** Resolved successfully? False means resolved-negative, not errored. */
+    ok: boolean;
+    payer?: string;
+    /** Present on `settle`, absent on `verify` — nothing settled yet. */
+    tx?: string;
+    amount?: string;
+    asset?: string;
+}
+/** Raised when the stream cannot be opened. Carries the HTTP status. */
+declare class TrafficStreamError extends Error {
+    readonly status: number;
+    /** Seconds to wait before retrying, when the server said so (503). */
+    readonly retryAfter?: number;
+    constructor(message: string, status: number, retryAfter?: number);
+}
+interface StreamTrafficEventsOptions {
+    /** Facilitator to subscribe to. Defaults to the Ultravioleta DAO facilitator. */
+    facilitatorUrl?: string;
+    /**
+     * Only yield events for these networks. Applied client-side — the facilitator
+     * has no per-network filter, so every event still crosses the wire. Match the
+     * canonical slug (`skale-base`, not `skale`).
+     */
+    networks?: string[];
+    /** Only yield these operations. */
+    kinds?: TrafficEventKind[];
+    /** Abort the stream. Without one, iteration ends only when the server closes. */
+    signal?: AbortSignal;
+    /** Extra headers, for a deployment that gates the stream behind authorization. */
+    headers?: Record<string, string>;
+}
+/** One decoded SSE frame: the event name and its raw data payload. */
+interface SSEFrame {
+    event: string;
+    data: string;
+}
+/**
+ * Incremental Server-Sent Events parser.
+ *
+ * Kept separate from the network layer so the framing can be tested without a
+ * socket — which matters, because the case that breaks in production is an idle
+ * rail sending nothing but keepalive comments for minutes.
+ */
+declare class SSEParser {
+    private buffer;
+    private eventName;
+    private dataLines;
+    /** Feed a chunk of the response body; get back whatever frames completed. */
+    push(chunk: string): SSEFrame[];
+}
+/**
+ * Decode one SSE frame into a {@link TrafficEvent}.
+ *
+ * Returns null for anything malformed: a single bad message must never tear down
+ * a long-lived stream — the connection is worth more than the message.
+ */
+declare function parseTrafficEvent(frame: SSEFrame): TrafficEvent | null;
+/** Does this event pass the caller's client-side filters? */
+declare function matchesFilters(event: TrafficEvent, options: Pick<StreamTrafficEventsOptions, 'networks' | 'kinds'>): boolean;
+/**
+ * Subscribe to the facilitator's live traffic stream.
+ *
+ * Works in Node 18+ and in browsers: it uses `fetch` and the response body
+ * stream rather than `EventSource`, so it also works where custom headers are
+ * needed (`EventSource` cannot send them).
+ *
+ * Iteration ends when the server closes the connection or the `signal` aborts.
+ * It does NOT reconnect on its own — reconnect policy belongs to the caller, who
+ * is the only one who knows whether a gap matters.
+ *
+ * @throws {TrafficStreamError} 404 when the operator disabled the stream, 503
+ * with `retryAfter` when it is at subscriber capacity.
+ */
+declare function streamTrafficEvents(options?: StreamTrafficEventsOptions): AsyncGenerator<TrafficEvent, void, undefined>;
+
+export { EVENT_KINDS, FACILITATOR_ADDRESSES, type FacilitatorAddresses, KEEPALIVE_INTERVAL_MS, type SSEFrame, SSEParser, type StreamTrafficEventsOptions, type TrafficEvent, type TrafficEventKind, TrafficStreamError, getFacilitatorAddress, matchesFilters, parseTrafficEvent, streamTrafficEvents };