Content Security Policy (CSP)

TokenFlight widgets inject styles into Shadow DOM. If your page has a strict Content Security Policy, you need to allow these styles.

Should you read this?

Read this page if your app sets a CSP header, uses nonce-based styles, or runs in a locked-down checkout environment.

If your app does not use CSP yet, you can ship the widget first and return before production hardening.

What the widget needs

• style-src must allow the widget's Shadow DOM styles.
• connect-src must allow your configured API endpoint.
• Card checkout also needs connect-src for the configured fiat API endpoint.
• img-src must allow chain icons and token logos.

The csp-nonce Attribute

Pass a nonce to the widget, and it will include it on all injected <style> elements:

<tokenflight-widget csp-nonce="abc123" theme="dark" to-token="eip155:8453:0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913" trade-type="EXACT_OUTPUT" amount="100"></tokenflight-widget>

Or create the custom element from JavaScript and set the same HTML attribute before appending it:

// The csp-nonce is an HTML attribute on the custom element
const el = document.createElement('tokenflight-widget');
el.setAttribute('csp-nonce', 'abc123');
el.setAttribute('theme', 'dark');
el.setAttribute('to-token', 'eip155:8453:0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913');
el.setAttribute('trade-type', 'EXACT_OUTPUT');
el.setAttribute('amount', '100');
document.getElementById('container').appendChild(el);

The csp-nonce attribute applies to the custom element path. If you use the TokenFlightWidget JavaScript class in a nonce-only CSP environment, test styles carefully or use the custom element path for strict nonce support.

Required CSP Directives

Content-Security-Policy:
  style-src 'nonce-{your-nonce}';
  connect-src https://your-api-endpoint.example.com https://fiat.hyperstream.dev;
  img-src https://your-api-endpoint.example.com https: data:;

Directive	Value	Purpose
style-src	'nonce-{value}'	Shadow DOM inline styles
connect-src	https://your-api-endpoint.example.com and https://fiat.hyperstream.dev if card checkout is enabled	API requests (quotes, orders, tokens, fiat checkout)
img-src	https://your-api-endpoint.example.com plus token logo domains	Chain icons (/v1/chain/{id}/icon) and token logos

Replace your-api-endpoint.example.com with the domain of your configured apiEndpoint.

Full CSP Header Example

Content-Security-Policy:
  default-src 'self';
  script-src 'self';
  style-src 'self' 'nonce-abc123';
  connect-src 'self' https://your-api-endpoint.example.com https://fiat.hyperstream.dev;
  img-src 'self' https://your-api-endpoint.example.com https: data:;
  font-src 'self';

INFO

Token icon images (logoURI) may come from various CDNs. If you see broken token icons, check your img-src directive and add the necessary domains. Chain icons use the API endpoint path /v1/chain/{id}/icon.

Without a Nonce

If you cannot use nonces (e.g., static hosting without server-side header injection), you can use 'unsafe-inline' for style-src:

style-src 'self' 'unsafe-inline';

This is less secure but allows the widget's Shadow DOM styles to load without a nonce.

Next step

• Need the broader security model? Read Security.
• Need browser support details? Read Browser Compatibility.