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

Onboarding flow

Opens the onboarding flow — combines terms acceptance, identity verification (KYC), and an optional first deposit into a single guided experience. React/React Native expose useOnboarding; Flutter exposes ProphetX.of(context).onboarding.

Controller surface

OpenOnboardingOptions

Terms flow

Opens the terms and conditions acceptance flow as a standalone step. Use this when a user is otherwise verified but has not yet accepted ProphetX's legal documents — for example, an existing user whose terms version has changed, or a new user who skipped acceptance during onboarding. React/React Native expose useTerms; Flutter exposes ProphetX.of(context).terms.

Controller surface

OpenTermsOptions

What users see

Once you call open(), the embed renders the acceptance screen inside the modal. You don't render any of these screens yourself — the embed owns them.

1. Document list. The user sees ProphetX's legal documents (Privacy Policy, Terms of Use, Market Participant Agreement, Risk Disclosure Statement), each with a checkbox and a link that opens the full document in a new tab. An "Accept all" checkbox toggles all documents at once.
2. Continue. The Continue button is disabled until every document is checked. Tapping it submits acceptance to ProphetX in a single request.
3. Terminal state. One of two outcomes fires:
   • Accepted — onTermsAccepted(acceptedAt) is called with the ISO 8601 acceptance timestamp. The embed shows a brief success screen, then closes.
   • Failed — onError(code, message) is called. The embed shows an error screen with a "Try Again" affordance that returns the user to the document list so they can resubmit.

KYC flow

Opens the identity verification (KYC) flow as a standalone step. Use this when you want to verify a user's identity without the full onboarding experience. React/React Native expose useKyc; Flutter exposes ProphetX.of(context).kyc.

Controller surface

OpenKycOptions

What users see

Once you call open(), the embed walks the user through a short multi-step flow inside the modal. You don't render any of these screens yourself — the embed owns them.

1. Phone entry. The user enters their mobile number. The embed submits it and triggers an SMS one-time passcode (OTP).
2. OTP verification. A 6-digit code arrives via SMS. The user enters it. A "Resend code" affordance is available, and a back button returns to phone entry.
3. Additional inputs (sometimes). Depending on what the identity provider needs to complete verification, the user may be asked for extra information — most commonly a date of birth. If no extra inputs are needed, this step is skipped.
4. Identity confirmation. The embed displays the personal information returned by the identity provider (name, date of birth, address, last 4 of SSN, phone, email) for the user to review and confirm.
5. Terminal state. One of three outcomes fires:
   • Verified — onKycSuccess(identityUuid) is called. The user is now cleared for transactions.
   • Pending review — onKycPending() is called. The user has not been auto-approved and is under manual review. The flow cannot continue from here; check status on your backend or wait for a webhook.
   • Failed — onKycFailed(reason) is called. Verification was rejected and cannot be retried in this session.

The embed renders its own success / pending / failed result screen with a close button before the corresponding callback fires.

Latency and retries

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)

TermsOpenOptions (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: