> For the complete documentation index, see [llms.txt](https://docs.glacislabs.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.glacislabs.com/zero-delta/widget/api-reference.md). # API Reference The complete export surface, the headless engine, and what the widget deliberately does not do. Package `@glacislabs/stablegenie-zerodelta`. MIT, zero runtime dependencies. The current version and the full changelog are on [npm](https://www.npmjs.com/package/@glacislabs/stablegenie-zerodelta). ### Exports #### `@glacislabs/stablegenie-zerodelta` | Kind | Exports | | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------- | | Components | `StableGeniePay` · `StableGenieSwap` · `StableGenieExchange` · `StableGenieRwaExchange` · `PaymentIsland` · `StableGenieProvider` | | Mounting | `mount` | | Theme | `lightTheme` · `darkTheme` · `resolveTheme` | | Compliance | `CompliancePanel` · `complianceChecks` · `complianceView` · `complianceControlsLine` · `formatJurisdiction` · `humanizeComplianceReason` | | Engine | `createEngine` · `symbolKey` | | Catalogue | `assetClassOf` · `brokenLaneReason` · `counterpartTokens` · `destinationAvailability` | | Constants | `EXECUTABLE_STABLE_ASSETS` · `STABLE_ASSETS` · `TRADEABLE_RWA_ASSETS` · `SUPPORTED_ASSETS` · `SUPPORTED_CHAIN_IDS` | #### `…/core` The framework-agnostic engine — no React, no DOM. Everything above except the components, plus the primitives (address, units, ABI encoding, escrow, route solving, order normalisation, transaction validation, compliance derivation, the API client and the verifier). #### `…/mount` `mount(el, config)` for non-React hosts. Returns an unmount function. #### `…/standalone` The IIFE build. Sets `window.StableGenieWidget` with `mountPay`, `mountSwap`, `mountExchange`, `mountRwaExchange` and `mountExpress`. ### Types | Type | Shape | | -------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `StableGenieConfig` | The shared config — see Configure | | `StableGeniePayProps` · `StableGenieSwapProps` · `StableGenieExchangeProps` · `PaymentIslandProps` | Per-component props | | `SupportedAsset` | Union of 26 symbols (below) | | `ExchangeMode` | `"exchange" \| "onramp" \| "offramp"` | | `ExchangeProduct` | `"stable" \| "rwa"` | | `ExchangeInput` | `{ fromChainId: number \| null; fromAsset: string \| null; toChainId: number \| null; toAsset: string \| null; amount: string }` — what the exchange card holds, as `onInputChange` reports it; see Configure → Events | | `PillOpenAs` | `"modal" \| "drawer"` — how a `variant="pill"` card opens; see Configure → The pill | | `PaymentIslandKind` | `"pay" \| "swap" \| "exchange"` | | `SettlementMethod` | `"stablecoin" \| "bank"` | | `MountConfig` | Discriminated union on `variant: "pay" \| "swap" \| "exchange" \| "rwa"` | | `StableGenieTheme` | 23 theme tokens — see Theming | | `SuccessInfo` | `{ hash: string; verdict: VerifyResult; route: RouteResult }` | | `VerifyResult` | `{ status: "confirmed" \| "mismatch" \| "reverted" \| "unconfirmed"; reason?: string }` | | `Compliance` | The gateway's decision for a quote's wallet pair — status, decision, screened wallets, jurisdiction, applied policies and legislation, risk / flagged / blocking categories, reasons, `checkId`, `expiresAt` — plus `sourceCountry` when your proxy adds it (see The Keyless Proxy) | | `ComplianceCheck` | One control: `id` (`location` \| `screening` \| `risk` \| `asset` \| `limits`), `label`, `ok`, `reasons`, evidence | | `ComplianceView` | The derived display state: `tone`, `label`, `headline`, `blocked`, `needsAction`, `screened` | | `ComplianceTone` | `"ok" \| "warn" \| "blocked" \| "neutral"` | | `WalletScreen` | A standalone `/screen/wallet` verdict — the direct-settlement gate | | `SanitizedTxEntry` | The display-safe record passed to `onTransaction` | | `QuoteBlock` | `{ blocked: true; category: string; reason: string; message: string }` | | `Catalogue` · `Availability` · `BrokenLane` | The derived selectable set and why a lane is unavailable | | `Chain` · `Token` · `Route` | Registry shapes | | `Plan` · `RouteResult` · `SwapInput` | Engine planning shapes. `Quote` and `RouteResult` carry `compliance?`. From v4.11.0 an exact-receive `Plan` also carries `unquotedOptions` — the funding options it did not price | | `LinkIdentity` · `BankPayoutAccount` | ZeroDelta Link shapes | | `Eip1193Provider` | The provider interface accepted by `config.provider` | #### `SupportedAsset` ```ts type SupportedAsset = // Stables that can execute a stable-to-stable destination leg | "USDC" | "USDT" | "USDE" | "USDTB" | "AUSD" | "PYUSD" | "USDG" // Stables that can fund an RWA order but not execute a stable-to-stable leg | "USD1" | "WM" | "USDS" | "DAI" | "RLUSD" // Real-world assets | "XAUT" | "NALPHA" | "NTBILL" | "NBASIS" | "NCREDIT" | "NOPAL" | "NWISDOM" | "NACRDX" | "NLCRD" | "NAXI" | "NCLOA" | "NFALCON" | "DEJAAA" | "DESPXA"; ``` The union bounds what can be **named**. What is **selectable** is derived per load — see Configure → Coverage. ### The headless engine `createEngine()` gives you the routing, encoding and verification layer without any UI. Use it to build your own picker or checkout on top of the same guarantees the widget enforces. ```ts import { createEngine } from "@glacislabs/stablegenie-zerodelta/core"; const engine = createEngine({ apiBase: "/api/widget/v1" }); const catalogue = await engine.fetchCatalogue(); // what a picker should render const preview = await engine.quoteSwapPreview({ fromChainId: 42161, fromToken: "USDT", toChainId: 8453, toToken: "USDC", amountIn: "100", }); ``` #### `EngineConfig` | Field | Type | Default | | ------------------ | ----------------------------------- | ---------------- | | `apiBase` | `string` | `/api/widget/v1` | | `apiKey` | `string` | — | | `getApiKey` | `() => string \| Promise` | — | | `trustedApiOrigin` | `string` | — | | `fetchImpl` | `typeof fetch` | global `fetch` | | `rpcOverrides` | `Record` | — | | `onTransaction` | `(entry: SanitizedTxEntry) => void` | — | #### `Engine` | Method | Returns | | ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `fetchChains()` | the enabled chain registry | | `fetchTokens()` | per-chain token addresses and decimals | | `fetchRoutes()` | the published route matrix | | `fetchRouteHealth()` | measured lane health, or `null` — never rejects | | `fetchPrices(symbols)` | USD prices by upper-cased symbol, for display only — never rejects; an unpriced symbol is absent | | `fetchQuote(body)` | a priced quote, carrying the compliance decision | | `fetchCatalogue(allowedAssets?, product?)` | the selectable `Catalogue` | | `fetchPaymentPlan(request, payer, wallet?)` | an exact-receive `Plan` | | `quotePayOption(request, payer, option, wallet?)` | the route for one funding option the plan did not price (`Plan.unquotedOptions`), v4.11.0 — rejects an option the live catalogue no longer offers, and never prices a direct transfer | | `quoteSwapPreview(swap, owner?)` | an exact-in preview | | `buildSwapPlan(swap, payer, wallet?)` | an exact-in `Plan` | | `payerNonceBaseline(...)` | the pre-broadcast nonce baseline | | `verifySubmittedTx(...)` | a `VerifyResult` | | `readBalances(...)` · `readNativeBalance(...)` | wallet balances | | `recordTransaction(entry)` | the sanitized history entry | | `api` · `verifier` · `apiBase` | the underlying client, verifier and resolved base | Resource reads are cached for 60 seconds. From **v4.10.0** the registry reads — chains, tokens, routes, route health and the vault catalogue — are shared by every engine on the page with the same `apiBase` and `apiKey`, and one in flight is not requested twice, so a widget that remounts does not read the registry again; an engine given its own `fetchImpl` or `getApiKey` keeps a private cache. A wallet screening verdict is held for 5 minutes, because it is a property of the address rather than of the market. `fetchCatalogue` never rejects: a failed read yields `ready: false`, which means "not known yet", not "nothing is supported". `fetchPrices` never rejects either, and a stale snapshot counts as no price — treat its numbers as decoration, never as an input to an amount. ### Rendering the compliance decision yourself If you build your own checkout on `…/core`, use the same derivation the widget uses rather than reimplementing it — `complianceChecks()`, `complianceView()` and `CompliancePanel` are exported for exactly that. `formatJurisdiction(jurisdiction, country)` prints the jurisdiction the way the widget and the ZeroDelta app do: the policy region, with the visitor's country beside it when the decision carries `sourceCountry` (`EU · Spain (ES)`), and the region alone when it does not. See Configure → Compliance for the rule that governs all of them. ### Fees and attribution The widget takes **no fee**. There is no fee hook, no integrator string and no revenue-share configuration — what the quote prices is what the payer pays. From **v4.7.0** the widget submits the quote's own `partnerId`. A quote priced on an API key with special rates carries a `partnerId` marker that binds that price to the order (wallets, tokens, chains and amounts); the widget passes it verbatim to `submitOrder`, and the pre-sign validator binds the encoded word to it. A quote without a marker — an ordinary key, or one priced before both wallets were known — is submitted with `bytes32(0)`, exactly as before. The marker is not an integrator setting: you cannot supply or override it. **Versions before 4.7.0 always submit `bytes32(0)`**, so do not use a key with special rates on them: the order would ask for the special rate with nothing behind it and may remain unfilled. ### Known limits | Limit | Detail | | -------------------------------- | ------------------------------------------------------------------------------------------- | | No localisation | Every string is English. There is no locale seam or message catalogue. | | No fee or attribution hook | See above. | | `mount()` cannot set a layout | Its `variant` selects the component; use JSX or the script-tag helpers for `pill` / `wide`. | | On- and off-ramp are not shipped | `mode: "onramp"` / `"offramp"` render a coming-soon panel. | | Bank settlement is not shipped | `settlement: "bank"` parks the same way. | | Plume network switching | No `wallet_addEthereumChain` metadata is bundled for Plume (98866); users add it manually. | | Reference proxy rate limiter | In-memory per warm instance — best-effort, not a hard ceiling. | ### Versioning Releases are semantic and automated from `main`. **Pin an exact version in production** — this component sits in a payment path. Four majors have carried breaking changes: | Version | Change | | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **4.0.0** | Direct settlements are screened, and the compliance decision is disclosed in the UI. Deployments must add `screen/wallet` to the proxy allow-list or direct settlement fails closed — see The Keyless Proxy. | | **3.0.0** | The exported `PayMethod` union drops `"recommended"` and `"anyasset"`; the default method is `"stablecoin"`. The any-asset funding rail is no longer reachable from the UI. | | **2.0.0** | Closed an API-key leak and readied the package for public npm. | | **1.0.0** | `DEFAULT_API_BASE` is no longer exported. Hosts passing an absolute `apiBase` together with an `apiKey` must now also set `trustedApiOrigin`, or the key is withheld. Consumers on the default same-origin proxy are unaffected. | Minor and patch releases are listed in the changelog that ships with the package on [npm](https://www.npmjs.com/package/@glacislabs/stablegenie-zerodelta).