Known Issues & Limitations

Rate Limits

• The Hyperstream API is rate-limited by IP address.
• The SDK uses a 15-second timeout for API requests.
• Failed requests are not automatically retried.

Performance

• Bundle size depends on build mode, bundler, and included adapters.
• Multiple widget instances share a query cache for chains, tokens, and balances.
• Order tracking polling starts only after a transaction or fiat order is created.

Multiple Instances

Multiple widget instances on the same page are supported:

• Each instance has its own Shadow DOM.
• State is isolated per instance.
• registerWidgetElement() can be called multiple times safely.
• Instances share cached API data.

Cleanup

const widget = new TokenFlightWidget({
  container: '#widget',
  config: {
    toToken: { chainId: 8453, address: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' },
    tradeType: 'EXACT_OUTPUT',
    amount: '100',
    theme: 'dark',
  },
});

widget.initialize();
widget.destroy();

Network & Offline Behavior

• No built-in offline detection.
• Requests that exceed 15 seconds surface as TF3002.
• Users must retry manually after network failures.

Privacy

• No telemetry or analytics.
• No cookies.
• No sessionStorage usage.
• One localStorage key, and only on the pay-by-transaction-hash rail: tf:pending-txhash-submit (suffixed with your storage-namespace when set). It holds the pending deposit — source chain, amount, order id and submitted hash — so the widget can offer to resume tracking after a reload. It is cleared when the deposit reaches a terminal state or the user declines the resume prompt. Nothing else the widget does touches storage: token and chain metadata are cached in memory only, for the lifetime of the page.
• Network requests go to your configured APIs, https://embed.tokenflight.ai for the shared defaults document, and asset domains referenced by token metadata.

Known Limitations

Limitation	Status
No limit orders	Not planned for v1.x
No custom translation overrides	Only built-in locales are supported
No testnet / sandbox mode	Write a stub adapter — see Testing
No webhook notifications	Use polling or backend verification
No React-specific wrapper package	Use the public widget directly
No post-init config updates	Destroy and recreate to update config