Wallets

Every ISV is provisioned as either STANDING or INDIVIDUAL. That single setting decides how funds are tracked, what GET /private/v1/wallets returns, and a few smaller details elsewhere. Confirm which one you've been provisioned as before designing your wallet flows — they're not interchangeable at runtime.

A note on naming. STANDING is the current external name for this fund type. The backend's wire-level enum and database are still mid-migration and may literally return SHARED in the fundType field instead — if you see SHARED in a raw response, treat it as the same thing as STANDING documented here. This page (and the rest of these docs) uses STANDING throughout as the term to build against; check with your ProphetX contact if you need to confirm which literal string a given environment currently returns.

This doc covers two endpoints: reading the current wallet, and reading the transaction history that produced it.

You don't move money. ProphetX handles all debits, credits, fees, and settlements on its side, atomically against the wallet. Your backend reads the resulting state through these two endpoints — it does not post ORDER, PAY, ORDER_FEE, etc. itself, and there is no ledger-write endpoint on the private API. Deposits and withdrawals also originate from ProphetX (via the embedded UI's payment modals — see Embedded UI (tokens + /embed/v1)). The flow is: ProphetX writes, you read.

Auth: see Authentication. Both endpoints accept requests with or without sub, and behave differently depending on which.


1. The two fund models

Fund typeWallet rowsSource of truth
INDIVIDUALOne wallet per user. Each user's balance is segregated.The user's own wallet row.
STANDINGOne ISV-level standing fund wallet (userId IS NULL) plus a per-user tally row for each user.The standing fund. Per-user tallies are bookkeeping and may go negative.

A few practical consequences:

  • Atomic balance updates target the standing fund for STANDING ISVs and the user wallet for INDIVIDUAL. For STANDING ISVs, the balance_before / balance_after and wallet_version fields on the transaction log refer to the standing fund, not the per-user tally.
  • User deletion semantics differ — see User Onboarding (users, KYC, terms).
  • Reading /wallets without sub only makes sense for STANDING ISVs (it returns the standing fund). INDIVIDUAL ISVs get a 404 in that case, because there's no standing-fund row to return.

2. GET /private/v1/wallets

Returns the caller's wallet row. What "the caller's wallet" means depends on which headers the gateway derives from the JWT, plus an optional ?userId=:

Headers presentuserIdResult
X-ProphetX-ISV + X-ProphetX-User (JWT has sub)ignoredThat user's wallet row.
X-ProphetX-ISV only (no sub)setThat user's wallet row — as long as they belong to your ISV. 404 otherwise.
X-ProphetX-ISV only (no sub)unsetThe ISV's standing-fund row. STANDING only — INDIVIDUAL ISVs get 404.

userId is only honored on an ISV-only JWT — it's ignored once the JWT already carries a sub. This is how an ISV-level token (support tooling, background jobs) reads one specific user's wallet without minting a per-user JWT. You don't set the X-ProphetX-* headers directly; they come from the JWT claims (iss and sub). See Authentication.

Response shape

{
  "id": 42,
  "userId": "00000000-0000-0000-0000-000000000000",
  "isvId":  "00000000-0000-0000-0000-000000000000",
  "fundType": "STANDING",
  "balance": "100.00",
  "version": 17,
  "createdAt": "2026-05-01T12:00:00Z",
  "updatedAt": "2026-05-12T09:14:22Z"
}

A few things worth calling out:

  • userId is null for the ISV's standing-fund row.
  • balance is a string, not a number. The underlying column is numeric(16,2), and the string preserves precision and is always rendered with two decimal places. Parse it with a decimal library, not a float, or you'll eventually have an off-by-one-cent bug to chase.
  • version is an optimistic-concurrency counter that increments on every write. Use it to detect concurrent updates — if you cache the wallet locally, key the cache on version.
  • updatedAt is null until the row has been updated at least once.

3. GET /private/v1/transactions

Returns the caller's transaction history, newest first, paginated by cursor.

Headers presentuserId / scopeResult
X-ProphetX-ISV + X-ProphetX-Userboth ignoredThat user's transactions.
X-ProphetX-ISV onlyuserId setThat user's transactions, as long as they belong to your ISV.
X-ProphetX-ISV onlyscope=allEvery transaction of your ISV — ISV-level rows and every user's rows together.
X-ProphetX-ISV onlyneither setISV-level transactions only (user_id IS NULL) — e.g. ISV deposits and withdrawals on the standing fund.

userId and scope are only honored on an ISV-only JWT (no sub); both are ignored once the JWT carries a sub. scope is itself ignored once userId is set. An empty result is a 200 with data: [], not a 404.

Query parameters

NameTypeDefaultNotes
userIdUUIDunsetISV-only JWT only — return this user's transactions instead of ISV-level ones. 404 if the user doesn't belong to your ISV.
scopeenumisvISV-only JWT only, and only when userId is unset. isv returns ISV-level transactions only (current default behavior); all returns every transaction of the ISV, ISV-level and per-user alike.
limitinteger50Page size. 1 ≤ limit ≤ 200.
beforeintegerunsetCursor — return rows with id strictly less than this value. Pass the nextCursor from the previous response.
refIdUUID stringunsetFilter to the transactions carrying this refId — i.e. every ledger row for one order (ORDER stake, PAY / PUSH / VOID payout, ORDER_FEE, REFUND_FEE, CANCEL, etc.). Useful when reconciling P&L for a specific order without paging through the full history.

Response shape (TransactionsPage)

{
  "data": [
    {
      "id": 5128,
      "txId": "00000000-0000-0000-0000-000000000000",
      "userId": "00000000-0000-0000-0000-000000000000",
      "isvId":  "00000000-0000-0000-0000-000000000000",
      "refId":  "11111111-1111-1111-1111-111111111111",
      "contractId": "8315d4bc44d06eef736959e0b214c170",
      "txType": "ORDER",
      "amount": "-25.00",
      "balanceBefore": "100.00",
      "balanceAfter":  "75.00",
      "walletVersion": 18,
      "createdAt": "2026-05-12T09:14:22Z"
    }
  ],
  "nextCursor": 5128,
  "hasMore": true
}

Field meanings:

  • id — internal row id, also used as the pagination cursor.
  • txId — UUID idempotency / dedupe key for the transaction.
  • userId — null for ISV-level rows.
  • refId — UUID of the originating market order or parlay. null when no order is associated (e.g. ISV deposits). This is the bare UUID with any isv_/isv_mo_ prefix already stripped — it will not string-match the refId you got back from POST /market-orders directly. See the ID-formats note in Market Orders.
  • contractId — empty string when no contract is associated.
  • txType — one of the values in the next section.
  • amount — signed decimal, two decimal places, string-encoded for the same precision reason as balance. Debits are negative (e.g. ORDER quantity = -25.00), credits are positive (e.g. PAY payout = +45.45).
  • balanceBefore / balanceAfter — wallet balance immediately before and after this transaction. For STANDING ISVs, these refer to the standing fund, not the per-user tally.
  • walletVersion — the optimistic-concurrency version recorded against this transaction (matches the version field on the wallet at the time).
  • nextCursor — pass as before to fetch the next page. null when there are no more rows.
  • hasMore — true when nextCursor is set and more rows may follow.

TransactionType enum

ValueWhat it represents
ORDERQuantity debited when an order is submitted.
CANCELQuantity returned on order cancellation.
PAYPayout on a winning order.
PUSHCredit on a push settlement. On Pushable markets this returns the cost of the contracts. On Not Pushable markets (from November 30, 2026) a tie settles at $0.50 per contract, so amount is the settled value, not the cost. See the note below.
VOIDCredit on a voided contract. On Pushable markets this returns the cost. On Not Pushable markets (from November 30, 2026) a void settles at Fair Market Value, so amount is the settled value, not the cost. See the note below.
ADJUSTMENT_INCREASE / ADJUSTMENT_REDUCEManual balance adjustments.
DEPOSIT / WITHDRAWMoney in/out via the funds system.
APPROVE_WITHDRAW / REJECT_WITHDRAWWithdrawal decision postings.
COMMISSIONDefined in the enum, but not currently written on the ISV ledger — no code path produces this row for an ISV today. Fees on ISV orders post as ORDER_FEE / REFUND_FEE instead (below); don't build reconciliation logic expecting a COMMISSION row to appear.
REFUNDGeneric refund.
ORDER_FEEISV fee deducted from an order.
REFUND_FEERefund of a previously-charged ORDER_FEE — posted when an order is cancelled and its fee is returned. Paired with a matching CANCEL entry on the underlying quantity.

Settlement change on November 30, 2026 — PUSH and VOID are no longer always a refund of cost. With the Position Closure (cash out) release, markets are split into two classes. Not Pushable markets (moneyline, spread and total on any period, and game props) no longer push: a tie settles at $0.50 per contract and a cancellation or void settles at Fair Market Value as of the moment the disruption became known (platform rule 13.4). Pushable markets (player props, including golf player props) keep the traditional treatment — a push or void returns the cost. The transaction type does not change: both classes still post as PUSH / VOID. What changes is the number. Read amount from the transaction row; never derive the credit from the user's stake or quantity. The row's refId still links it to the originating order. The settlement webhook fires when the settlement is requested and the ledger row lands once it is processed, so the PUSH / VOID row can trail the ContractSettlementEvent by a short interval — reconcile on the transaction, not the webhook. Whether an ORDER_FEE refund accompanies a $0.50 or Fair Market Value settlement is still being confirmed, so don't assume a REFUND_FEE row. Which markets are Pushable is described under Fixtures; the per-contract settled value is being added to the settlement webhook and the settlements endpoint — see Webhooks.

Internal journal entries are filtered out. On STANDING ISVs, the backend writes per-user JOURNAL_DEPOSIT / JOURNAL_WITHDRAW bookkeeping entries so the platform can track each user's net exposure against the standing fund. Those rows are filtered at the query layer and never returned to ISV clients — you'll see the customer-facing DEPOSIT / WITHDRAW / ORDER / PAY etc. transactions, but not the underlying journal ones. If your reconciliation-vs-your-own-ledger diff includes journal-type rows, they're missing on purpose.

Pagination pattern

# First page
GET /private/v1/transactions?limit=50
# → { data: [...], nextCursor: 5128, hasMore: true }

# Next page
GET /private/v1/transactions?limit=50&before=5128
# → { data: [...], nextCursor: 5078, hasMore: true }

# Last page
GET /private/v1/transactions?limit=50&before=12
# → { data: [...], nextCursor: null, hasMore: false }

4. Deposits and withdrawals

GET /private/v1/wallets and /transactions are read-only. Money movement happens elsewhere:

  • Deposits and withdrawals flow through the /embed/v1/payment/* surface used by the embedded UI, which proxies to ProphetX's funds system. They show up here later as DEPOSIT, WITHDRAW, APPROVE_WITHDRAW, or REJECT_WITHDRAW transactions. See Embedded UI (tokens + /embed/v1).
  • Order debits and payouts are side effects of POST /market-orders and POST /parlays/{id}/confirm. They show up here as ORDER, CANCEL, PAY, PUSH, VOID, ORDER_FEE, etc.

The private ISV API doesn't expose direct deposit or withdraw endpoints.


5. Failure modes

HTTPWhen
400Bad request — invalid limit (outside 1..200), malformed before, etc.
401JWT missing or invalid.
404INDIVIDUAL ISV calling /wallets without sub and without userId. No standing fund exists. Also returned for /wallets?userId= naming a user of another ISV. (/transactions returns 200 with data: [] for a userId/scope combination with no rows, not 404.)
500Server error.

6. Curl

BASE="https://isv-api.sandbox.prophetx.dev/private/v1"

# A user's wallet (works for both STANDING and INDIVIDUAL ISVs)
curl "$BASE/wallets" -H "Authorization: Bearer $JWT_USER"

# The ISV standing fund (STANDING ISVs only; INDIVIDUAL returns 404)
curl "$BASE/wallets" -H "Authorization: Bearer $JWT_ISV"

# A user's most recent 50 transactions
curl "$BASE/transactions?limit=50" -H "Authorization: Bearer $JWT_USER"

# ISV-level transactions (deposits/withdrawals on the standing fund)
curl "$BASE/transactions?limit=100" -H "Authorization: Bearer $JWT_ISV"

# One specific user's wallet, from an ISV-only token (support tooling)
curl "$BASE/wallets?userId=<userId>" -H "Authorization: Bearer $JWT_ISV"

# One specific user's transactions, from an ISV-only token
curl "$BASE/transactions?userId=<userId>&limit=50" -H "Authorization: Bearer $JWT_ISV"

# Every transaction across the whole ISV (ISV-level + every user's rows)
curl "$BASE/transactions?scope=all&limit=100" -H "Authorization: Bearer $JWT_ISV"

# Next page
curl "$BASE/transactions?limit=50&before=5128" -H "Authorization: Bearer $JWT_USER"

# All ledger rows for one order (stake + payout + fee + refund, in one call)
curl "$BASE/transactions?refId=11111111-1111-1111-1111-111111111111" \
  -H "Authorization: Bearer $JWT_USER"

Did this page help you?