API Reference

The Flutter SDK (prophetx_sdk) mirrors the React Native surface — same provider, same options, same event payloads. Differences are called out per-section: hooks become ChangeNotifier flow controllers on ProphetX.of(context), callbacks fire on Dart Function types, and the event bus is a Dart Stream.

ProphetXProvider

Props

Environment

Pass a preset name or a custom config object:

Custom config:

type EnvironmentConfig = {
  embedUrl: string;
  apiBaseUrl: string;
};

AuthConfig

Optional. When provided, the SDK manages authentication internally — you don't need to pass token yourself.

DevToolsConfig

Deposit flow

Opens the deposit flow. The SDK renders a modal that handles the full deposit UI. React/React Native expose this via the useDeposit hook; the Flutter SDK exposes a DepositFlow controller on ProphetX.of(context).deposit.

Controller surface

OpenDepositOptions

The JavaScript SDK's OpenOptions also accepts token, theme, and onSessionExpired — these are passed per-call instead of through a provider.

Withdraw flow

Opens the withdrawal flow. Follows the same pattern as the deposit flow above. React/React Native expose useWithdraw; Flutter exposes ProphetX.of(context).withdraw.

Controller surface

OpenWithdrawOptions

1-Click Signup flow

Creates a ProphetX user from a phone number in about ten seconds, with no signup form of your own. The user confirms their phone by one-time code inside Verified Inc's own hosted modal, reviews the identity Verified already holds for them, and shares it. Your backend redeems that identity and the user exists — KYC has not run yet at that point; it starts once your backend redeems the identity. React/React Native expose useOneClickSignup; Flutter exposes ProphetX.of(context).oneClickSignup.

This is the one flow with no embed token at all — it carries a single-use sessionKey (minted by your backend via POST /private/v1/one-click/sessions) instead.

Controller surface

OpenOneClickSignupOptions

There is no token or redirectUrl on this flow. onGeofenceBlocked is defined and wired identically to every other flow, but it will never actually fire here — 1-Click runs before a user exists, so its tokenless session is treated as always-allowed by the geo gate rather than being evaluated against it.

Terms flow

Point an iframe at {embedBaseUrl}/tandc and run the same session handshake every flow uses: wait for PROPHETX_EMBED_LOADED, then post PROPHETX_SESSION with your token (and optionally PROPHETX_THEME).

// React — no useTerms hook; a plain iframe + postMessage listener
function AcceptTermsFrame({ token, onAccepted, onCancel }) {
  const iframeRef = useRef(null);

  useEffect(() => {
    function handleMessage(event) {
      if (event.origin !== embedOrigin) return;
      const { type, payload } = event.data;
      switch (type) {
        case "PROPHETX_EMBED_LOADED":
          iframeRef.current.contentWindow.postMessage(
            { type: "PROPHETX_SESSION", payload: { token } },
            embedOrigin
          );
          break;
        case "PROPHETX_SUCCESS":
          // payload is always { transactionId: "tandc", amount: 0 } — not a
          // real transaction reference, don't reconcile it as one.
          onAccepted();
          break;
        case "PROPHETX_CANCEL":
          onCancel();
          break;
        // This route never emits PROPHETX_ERROR — fetch/accept failures
        // render their own in-embed error screen with Try Again instead.
      }
    }
    window.addEventListener("message", handleMessage);
    return () => window.removeEventListener("message", handleMessage);
  }, [token]);

  return <iframe ref={iframeRef} src={`${embedBaseUrl}/tandc`} />;
}

Messages this route sends

This route never emits PROPHETX_ERROR — a terms-fetch failure and an accept failure both render an error page inside the embed with Try Again, so don't wait on an error message to know something went wrong.

What users see

1. Document list. The documents come from GET /embed/v1/terms verbatim, with document types PRIVACY_POLICY, TERMS_OF_USE, MARKET_PARTICIPANT_AGREEMENT, RISK_DISCLOSURE_STATEMENT, RULEBOOK, each with a checkbox and a link to the full document. An "Accept all" checkbox toggles all documents at once. Continue stays disabled until every document is checked — there's no partial acceptance.
2. Continue. Submits acceptance in a single request. The screen goes back to the same loading state as the initial fetch — a submit and a fetch look identical.
3. Terminal state. Success shows a result page and sends PROPHETX_SUCCESS; failure shows an in-embed error page with Try Again (which restarts from the terms fetch, wiping any checked boxes).

Don't log or reconcile transactionId as a payment reference — it's the literal string "tandc", and amount: 0 doesn't mean a zero-value transaction; no money moves in this flow at all.

Document verification flow

For a user who already exists and whose automated KYC check came back FAILURE, this opens a government-ID photo upload reviewed by IDComply. React/React Native expose useKyc (a historical alias, kept for backward compatibility) and useIdUpload (the current preferred name) — both open the exact same flow. Flutter exposes ProphetX.of(context).idUpload.

This flow is narrow by design: it only reaches the document step for a user whose automated check actually came back FAILURE. Anyone already verified, still under review, or out of attempts sees the matching terminal screen within a second or two instead — that's expected behavior, not a bug. Gate any "Verify ID" entry point on the user's KYC status rather than showing it unconditionally.

Controller surface

OpenIdUploadOptions vs. OpenKycOptions

These two option types are identical except for exactly one field, redirectUrl — present on OpenIdUploadOptions, absent on OpenKycOptions. That's the one functional reason to prefer useIdUpload over the legacy useKyc alias: on native, a user who finishes in the device browser without a redirectUrl lands on the vendor's own web page instead of back in your app. On web there's no functional difference — migrating is housekeeping, not a fix.

What users see

Once you call open():

1. The embed reads the user's KYC status first. If they're not eligible (already verified, still under review, compliance-failed, or attempts exhausted), it stops here and shows the matching terminal screen — no attempt is consumed. All four ineligible cases answer the same 409 kyc_not_retryable from the API; the embed disambiguates by checking status first, so you just receive the resolved outcome.
2. If eligible, it mints an IDComply session and opens the hosted form in a second browser tab — IDComply sets X-Frame-Options/frame-ancestors, so it cannot be shown in an iframe. There is no in-modal fallback.
3. The modal shows a "Finish Verifying Your Identity" waiting screen and polls while the user is in the other tab. Document capture takes minutes, so this wait is deliberately generous.
4. When the session finishes, the verdict resolves and the modal lands on a terminal screen, then fires the corresponding callback. Unlike 1-Click Signup, there's no further async step after this — by the time your callback fires, the decision is final.

Wallet

Fetches and returns the user's current wallet balance. Requires ProphetXProvider with an environment configured. React/React Native expose useWallet; Flutter exposes ProphetX.of(context).wallet (a ChangeNotifier).

Return value (React / React Native)

WalletBalance

JavaScript SDK

The vanilla SDK exposes a wallet property on the SDK instance:

Flutter

ProphetX.of(context).wallet is a WalletClient that extends ChangeNotifier. Pair it with ListenableBuilder to react to balance / loading / error transitions.

Auth

Manages user authentication. Requires ProphetXProvider with the auth prop configured. React/React Native expose useAuth; Flutter exposes ProphetX.of(context).auth (an AuthManager that extends ChangeNotifier).

Return value (React / React Native)

AuthState

LoginCredentials

LoginResult

ProphetXAuthError

JavaScript SDK

The vanilla SDK exposes an auth property on the SDK instance:

sdk.auth is null if AuthConfig was not passed to createProphetX.

Flutter

ProphetX.of(context).auth is an AuthManager that extends ChangeNotifier. state is a sealed hierarchy (Unauthenticated, Authenticating, Authenticated, Expired, AuthError) — match on it with Dart 3 pattern syntax.

AuthState subtypes: Unauthenticated, Authenticating, Authenticated(token, expiresAt), Expired(lastToken), AuthError(error). expiresAt on Flutter is Unix seconds (the JS SDKs use milliseconds).

ProphetXAuthError.code is the Dart enum AuthErrorCode { invalidCredentials, networkError, serverError, timeout }.

Events

Subscribes to all SDK events globally. Useful for analytics, logging, or cross-cutting concerns that apply regardless of which flow is open. React/React Native expose useEvents; Flutter exposes a broadcast Stream on ProphetX.of(context).events.

ProphetXEventHandlers (React / React Native)

All fields are optional. Pass only the events you care about.

Note: useEvents receives payload data as objects (e.g. { transactionId, amount }), while flow hook callbacks receive them as positional arguments (e.g. (transactionId, amount)).

Flutter event types

The Flutter SDK uses a sealed ProphetXEvent hierarchy. Subscribe to a single subtype with events.on<T>(handler) or to the full union with events.stream.listen(...).

ProphetXEmbed

Low-level iframe component. Use this when you need direct control over the embed lifecycle — most integrations should use the hooks above instead.

This component is only available in @prophetx/sdk-react.

function CustomEmbed() {
  const ref = useRef<ProphetXEmbedHandle>(null);

  return (
    <ProphetXEmbed
      ref={ref}
      open={true}
      onOpenChange={(open) => console.log("Open state:", open)}
      src="https://embed.prophetx.co/deposit"
      token={token}
      title="Deposit"
      theme={{ mode: "dark" }}
      onSuccess={(transactionId, amount) => console.log("Success:", transactionId)}
      onError={(code, message) => console.error("Error:", code, message)}
      onCancel={() => console.log("Cancelled")}
      onReady={() => console.log("Ready")}
      onGeofenceBlocked={(stateCode, reason) => console.log("Blocked:", stateCode)}
      onKycSuccess={(identityUuid) => console.log("KYC passed:", identityUuid)}
      onKycFailed={(reason) => console.log("KYC failed:", reason)}
      onKycPending={() => console.log("KYC pending")}
      onSessionExpired={async () => {
        const fresh = await fetchToken();
        return fresh;
      }}
    />
  );
}

Props

ProphetXEmbedHandle (ref)

Access the imperative handle via useRef<ProphetXEmbedHandle>:

JavaScript SDK instance

The object returned by createProphetX().

OpenOptions (JavaScript SDK)

KycOpenOptions (JavaScript SDK)

Events

The SDK has three event layers. Most integrations only use callback events (passed to open()). Use the EventEmitter for global analytics or logging. Use the postMessage protocol only if building a custom integration without the SDK.

Callback events

Passed as options to open() on each flow hook. See the individual hook sections above for the full list per flow.

Summary of all callback events across flows:

EventEmitter

A typed pub/sub system available in all three SDKs. In React/React Native, use useEvents. In JavaScript, use sdk.on() / sdk.off().

EventEmitter API:

// Subscribe — returns an unsubscribe function
const unsub = sdk.on("success", ({ transactionId, amount }) => { ... });

// Unsubscribe by reference
sdk.off("success", handler);

// Unsubscribe via return value
unsub();

postMessage protocol

Raw messages exchanged between the host page and the ProphetX iframe via window.postMessage. The SDK handles these automatically — use this reference only if you are building a custom integration without the SDK.

Outbound messages (iframe to host)

These messages are sent by the ProphetX embed to your page:

Inbound messages (host to iframe)

Send these messages to the ProphetX iframe:

Example — listening without the SDK:

window.addEventListener("message", (event) => {
  // Validate origin
  if (event.origin !== "https://embed.prophetx.co") return;

  const { type, payload } = event.data;

  switch (type) {
    case "PROPHETX_READY":
      console.log("Embed ready");
      break;
    case "PROPHETX_SUCCESS":
      console.log("Transaction:", payload.transactionId, payload.amount);
      break;
    case "PROPHETX_ERROR":
      console.error("Error:", payload.code, payload.message);
      break;
    case "PROPHETX_CANCEL":
      console.log("Cancelled");
      break;
    case "PROPHETX_SESSION_EXPIRED":
      // Fetch a new token and send it back
      fetchToken().then((token) => {
        iframe.contentWindow.postMessage(
          { type: "PROPHETX_SESSION_REFRESH", payload: { token } },
          "https://embed.prophetx.co"
        );
      });
      break;
  }
});

EmbedTheme

Theme overrides applied to the embed UI. Pass via the theme prop on ProphetXProvider (React/React Native), as part of OpenOptions (JavaScript SDK), or dynamically via sdk.updateTheme().

type EmbedTheme = {
  mode?: "light" | "dark";
  primaryColor?: string;
  colorOverrides?: Partial<ColorOverrides>;
  spacingOverrides?: Partial<SpacingOverrides>;
  radiusOverrides?: Partial<RadiusOverrides>;
  fontSizeOverrides?: Partial<FontSizeOverrides>;
};

Top-level fields

colorOverrides

Fine-grained color tokens. All fields are optional CSS color strings.

spacingOverrides

radiusOverrides

fontSizeOverrides

DevToolsLogEntry

Entries emitted by the devtools system. Receive them via DevToolsConfig.onEvent.

Type exports

All types are exported from the SDK package you're using. Import them alongside components and hooks: