Guides

Deposits and Withdrawals

📘

Upfront onboarding and terms (optional)

This guide walks through a just-in-time pattern — users are prompted to accept ProphetX's terms and complete identity verification the first time they open a deposit or withdrawal. If you prefer, you can run these steps upfront during your registration flow so the wallet flows open straight into the modal.

  • useOnboarding — bundles terms acceptance, identity verification, and an optional first deposit into a single guided flow.
  • useTerms — standalone T&C acceptance.

What you'll do

  1. Set up the SDK — install and configure the ProphetX SDK for your stack.
  2. Open a deposit — let them fund their account via your frontend.
  3. View transaction history — show users their recent transactions and statuses.
  4. Display the balance — show the user's current wallet balance.
  5. Add withdrawals — let them withdraw funds.

Before you begin

Complete the User Setup guide first — you'll need a created and verified ProphetX user before continuing.

Complete the Session Token Setup guide — your backend signs short-lived JWTs that authorize the embed to act on behalf of each user.

Step 1: Set up the SDK

Install the package for your stack:

Then set up the provider:

Step 2: Open a deposit

With the provider in place, opening a deposit is a single function call. The SDK renders a modal that handles the full deposit flow. When the user completes it, onSuccess fires with a transactionId and amount — store the transactionId on your backend to track deposit status.

🚧

User Prerequisites

When the embed opens it validates the user's prerequisite gates (terms, email, phone, geoip) from POST /api/v1/session/validate. If any are missing, onError fires with the corresponding code:

  • TERMS_NOT_SIGNED — open useTerms for targeted acceptance, or useOnboarding if you also want to bundle an optional first deposit.
  • EMAIL_NOT_VERIFIED / PHONE_NOT_VERIFIED — there's no embedded flow; handle these on your side (re-send verification email, OTP UI).
  • GEOFENCE_BLOCKED — user's location is restricted, no retry path. See Geofence errors.

KYC is enforced upstream at user creation, so a session token implies KYC is already complete — there is no KYC_NOT_STARTED style gate to handle here.

Full prerequisite reference →

Step 3: View transaction history

⚠️

Alpha — Coming soon

The backend endpoints for transaction history are under active development. The interface described below is planned but may change before release. We'll update this guide once the feature is generally available.

Once a user completes a deposit or withdrawal, you'll want to give them visibility into their recent transactions — including the current status of each one (e.g. pending, completed, failed, or canceled).

Rather than exposing this through the SDK, transaction history is served directly by the ProphetX backend. Your server calls the ProphetX transaction history endpoint, then returns the results to your client to render in your UI.

TODO: ProphetX transaction history endpoint(s) — pending backend team

Once published, the endpoints will support fetching a paginated list of a user's transactions, filtering by status, and the full set of status definitions. Details on the exact request/response shape and available filters will be added here as the feature is finalized.

In the meantime, the transactionId returned by onSuccess in the deposit and withdrawal flows can be stored on your backend to track individual transactions.

Step 4: Display the balance

Use the wallet hook to fetch and display the user's current balance. refetch is manual — call it on mount and after any deposit or withdrawal completes.

Step 5: Add withdrawals

Withdrawals follow the same pattern as deposits — same open() call, same callbacks, same onError codes. The piece worth calling out: before the withdraw (or deposit) modal renders, the SDK validates the user's session token against ProphetX's verification state. If the user hasn't completed identity verification or accepted ProphetX's terms and conditions, onError fires with KYC_REQUIRED, TERMS_REQUIRED, or both — and the withdraw UI never appears.

Handle either code by opening useOnboarding. The hook is adaptive: it inspects what the user is missing and only renders those steps — a user who just needs to accept T&C sees the T&C screen, a fully unverified user walks the full flow. Once onKycSuccess fires, retry the withdrawal.

📘

What your user sees during onboarding

useOnboarding renders only the steps the user is missing. A user who has cleared KYC but not yet accepted T&C sees just the T&C screen and is done in a click. A user with nothing on file walks the full flow: phone entry → SMS OTP (3 attempts, resend available) → optional extra inputs (e.g. date of birth) → identity confirmation → T&C acceptance.

One of three callbacks fires when it terminates: onKycSuccess (cleared), onKycPending (manual review — non-recoverable in-session), or onKycFailed (rejected). Build your retry-withdrawal prompt off onKycSuccess only.

Full flow reference →

Once a user has cleared verification and accepted T&C, the token validation gate stops returning KYC_REQUIRED and TERMS_REQUIRED, and future deposits and withdrawals open straight into the modal. ProphetX tracks verification state on the backend — you don't need to cache or check it yourself.

Next steps

Now that you have a working integration, explore these guides to polish it:


Updated about 6 hours ago