Skip to main content

​
TL;DR

Two integration models for exchange connectivity and withdrawal flows:
  • Headful iFrame widget. The vendor hosts the UI in a cross-origin <iframe> and communicates with the host page via postMessage.
  • Headless whitelabel API. The vendor exposes REST endpoints and optional SDKs; the integrator builds and owns the UI.
Bluvo ships only the headless model: REST APIs at api-bluvo.com, plus optional @bluvo/sdk-ts and @bluvo/react. No Bluvo iFrame.
Whitelabel wins on UI control, instrumentation, latency, and agent compatibility. With a state-machine SDK, the implementation gap against an iFrame is small.

​
Comparison

iFrame WidgetWhitelabel API
UI ownershipVendor DOM, cross-originIntegrator DOM, same-origin
Flow controlVendor-defined, postMessage eventsEnumerable states, direct fetch
BundleVendor runtime on the critical pathZero, or SDK (~few KB)
LatencyExtra document load, frame-ancestors negotiationSingle request round-trip
AnalyticsOnly vendor-exposed eventsFull x-bluvo-* request tracing
A/B testingConstrained to vendor surfacesAny screen, any variant
AccessibilityVendor markup, limited overrideIntegrator markup, full control
Agent / MCPOpaque cross-origin DOMDeterministic function calls
Compliance surfaceShared with the vendorIntegrator-owned
Time-to-first-flowHours, if widget config fitsHours with SDK, days without

​
Trade-offs

iFrame constraints. Cross-frame postMessage for state sync, frame-ancestors and CSP negotiation, vendor bundle on the critical path, mobile scroll and focus quirks, third-party branding on the 2FA screen. No way to gate entry on KYC, branch by user segment, or inject product-specific confirmation steps. Whitelabel responsibilities. You own forms, error states, and KYC / 2FA branching. A mature SDK collapses the protocol (OAuth popup, 2FA, SMS, MFA, quote refresh, execute) into enumerable states; without one, you wire the states yourself against REST with x-bluvo-* headers.

​
Code

"use client";

import { useBluvoFlow } from "@bluvo/react";

export function Withdraw({ walletId }: { walletId: string }) {
  const flow = useBluvoFlow({ walletId });

  if (flow.needs2FA)   return <TwoFAInput onSubmit={flow.submit2FA} />;
  if (flow.needsQuote) return <QuoteForm  onSubmit={flow.requestQuote} />;
  if (flow.canExecute) return <Confirm    onClick={flow.execute} />;

  return <Status state={flow.state} />;
}
The SDK is opt-in. REST is always available.

​
By audience

  • Product and business. Brand, analytics, funnel, compliance surface, and A/B testing on the highest-trust screen in the app.
  • Engineering. Same headers, same walletId, same auth. The SDK reduces 30+ withdrawal states (OAuth, 2FA, SMS, KYC, MFA, quote, execute) to booleans, or call REST directly for zero runtime cost. See /learn/sdk/state-machine.
  • End users. Faster first paint, native UI, consistent copy, no embedded-document scroll or focus quirks on mobile.

​
Automation and MCP

Whitelabel exposes deterministic, enumerable states. Through MCP and Bluvo’s skill.md, an agent reads state, submits 2FA, polls, and confirms, all by calling functions. An iFrame is an opaque cross-origin DOM; agents cannot interact with it programmatically.

​
Why Bluvo ships whitelabel only

iFrames are a legitimate choice for prototypes, internal tools, and demos. Bluvo’s customers, PSPs, dApps, and agent platforms, care about brand, conversion, compliance, and agent compatibility more than “shippable in an afternoon.” With the state-machine SDK, the time an iFrame saves is not worth the trade-offs.

​
Next Steps

OAuth2 Integration

Implement the full OAuth2 popup flow

State Machine SDK

30+ withdrawal states reduced to booleans

Agent Skills

Make AI agents build accurate Bluvo integrations