Local development

The kit ships a mock mode that routes the iframe's GraphQL calls to a stubbed mock endpoint (/api/graphql-mock) instead of the real one. Use it during local development when you don't have a token-minting endpoint stood up yet, or when CoinTracker's alpha environment is unavailable.

Enable mock mode

Pass options.mode: 'mock' and a no-op fetchAccessToken:

<TaxKitProvider
  fetchAccessToken={async () => 'mock-token'}
  options={{ mode: 'mock' }}
>
  <YourApp />
</TaxKitProvider>

In mock mode:

• The iframe's GraphQL queries are routed to <apiBaseUrl>/api/graphql-mock instead of the real GraphQL endpoint. Network requests still fire — they just hit stubbed handlers.
• Status transitions are simulated based on user actions.
• Tokens are accepted opaquely — return any non-empty string from fetchAccessToken.
• The iframe renders the full UI — every screen, every status, every overlay — but populated with placeholder data instead of real wallets / transactions. Theming, layout, copy overrides, and the post-robot bridge all behave identically to production. Only the data layer is stubbed.

What mock mode is for

• First-time integration: render the iframe and verify the bridge works before you've stood up the token-minting backend.
• UI development: iterate on your tax-center surface without depending on backend round-trips.
• Demo / sales scenarios: show the kit's flow without provisioning a real CoinTracker user.

What mock mode is not for

• End-to-end testing of partner-specific behavior — the mock skips the actual CoinTracker logic, so any partner-specific cost-basis calculation, promo-code handling, or import flow won't be exercised. Use the alpha environment for those.
• Production. Make absolutely sure options.mode is 'production' (or omitted — production is the default) in your prod build.

Environments at a glance

options.mode	Backend	When to use
'production'	Live CoinTracker	Your shipped build.
'alpha'	Pre-release backend	Pre-release testing — coordinate with CoinTracker.
'mock'	No backend	Local UI development, demos.

Verifying the bridge

While in mock mode, open the iframe and check the browser devtools console. You should see post-robot messages logged from both the parent ([TaxKit Parent]) and the iframe ([TaxKit]). If those don't appear:

• Check that <TaxKitProvider> actually renders. The iframe only mounts when the provider is in the tree.
• Check that you're not blocking the iframe origin via Content-Security-Policy. The default frame-src needs to allow the CoinTracker embedded origin (https://embedded.cointracker.com for production).
• Check the iframe URL — it should contain a config= query parameter encoding your options and theme.

See Troubleshooting for more specific failure modes.

When to graduate from mock to alpha

Move to options.mode: 'alpha' (with real tokens minted by your backend) as soon as you need to validate partner-specific behavior — promo codes, theming in a real flow, the cost-basis review screen with real data, etc. Coordinate with your CoinTracker integration contact on the alpha endpoint and any per-partner test users.