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.
STANDINGis the current external name for this fund type. The backend's wire-level enum and database are still mid-migration and may literally returnSHAREDin thefundTypefield instead — if you seeSHAREDin a raw response, treat it as the same thing asSTANDINGdocumented here. This page (and the rest of these docs) usesSTANDINGthroughout 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 type | Wallet rows | Source of truth |
|---|---|---|
INDIVIDUAL | One wallet per user. Each user's balance is segregated. | The user's own wallet row. |
STANDING | One 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_afterandwallet_versionfields 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
/walletswithoutsubonly 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
GET /private/v1/walletsReturns 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 present | userId | Result |
|---|---|---|
X-ProphetX-ISV + X-ProphetX-User (JWT has sub) | ignored | That user's wallet row. |
X-ProphetX-ISV only (no sub) | set | That user's wallet row — as long as they belong to your ISV. 404 otherwise. |
X-ProphetX-ISV only (no sub) | unset | The 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:
userIdisnullfor the ISV's standing-fund row.balanceis a string, not a number. The underlying column isnumeric(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.versionis an optimistic-concurrency counter that increments on every write. Use it to detect concurrent updates — if you cache the wallet locally, key the cache onversion.updatedAtisnulluntil the row has been updated at least once.
3. GET /private/v1/transactions
GET /private/v1/transactionsReturns the caller's transaction history, newest first, paginated by cursor.
| Headers present | userId / scope | Result |
|---|---|---|
X-ProphetX-ISV + X-ProphetX-User | both ignored | That user's transactions. |
X-ProphetX-ISV only | userId set | That user's transactions, as long as they belong to your ISV. |
X-ProphetX-ISV only | scope=all | Every transaction of your ISV — ISV-level rows and every user's rows together. |
X-ProphetX-ISV only | neither set | ISV-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
| Name | Type | Default | Notes |
|---|---|---|---|
userId | UUID | unset | ISV-only JWT only — return this user's transactions instead of ISV-level ones. 404 if the user doesn't belong to your ISV. |
scope | enum | isv | ISV-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. |
limit | integer | 50 | Page size. 1 ≤ limit ≤ 200. |
before | integer | unset | Cursor — return rows with id strictly less than this value. Pass the nextCursor from the previous response. |
refId | UUID string | unset | Filter 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)
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—nullfor ISV-level rows.refId— UUID of the originating market order or parlay.nullwhen no order is associated (e.g. ISV deposits). This is the bare UUID with anyisv_/isv_mo_prefix already stripped — it will not string-match therefIdyou got back fromPOST /market-ordersdirectly. 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 asbalance. Debits are negative (e.g.ORDERquantity =-25.00), credits are positive (e.g.PAYpayout =+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 theversionfield on the wallet at the time).nextCursor— pass asbeforeto fetch the next page.nullwhen there are no more rows.hasMore— true whennextCursoris set and more rows may follow.
TransactionType enum
TransactionType enum| Value | What it represents |
|---|---|
ORDER | Quantity debited when an order is submitted. |
CANCEL | Quantity returned on order cancellation. |
PAY | Payout on a winning order. |
PUSH | Credit 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. |
VOID | Credit 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_REDUCE | Manual balance adjustments. |
DEPOSIT / WITHDRAW | Money in/out via the funds system. |
APPROVE_WITHDRAW / REJECT_WITHDRAW | Withdrawal decision postings. |
COMMISSION | Defined 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. |
REFUND | Generic refund. |
ORDER_FEE | ISV fee deducted from an order. |
REFUND_FEE | Refund 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 —
PUSHandVOIDare 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 asPUSH/VOID. What changes is the number. Readamountfrom the transaction row; never derive the credit from the user's stake or quantity. The row'srefIdstill 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 thePUSH/VOIDrow can trail theContractSettlementEventby a short interval — reconcile on the transaction, not the webhook. Whether anORDER_FEErefund accompanies a $0.50 or Fair Market Value settlement is still being confirmed, so don't assume aREFUND_FEErow. 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_WITHDRAWbookkeeping 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-facingDEPOSIT/WITHDRAW/ORDER/PAYetc. 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 asDEPOSIT,WITHDRAW,APPROVE_WITHDRAW, orREJECT_WITHDRAWtransactions. See Embedded UI (tokens + /embed/v1). - Order debits and payouts are side effects of
POST /market-ordersandPOST /parlays/{id}/confirm. They show up here asORDER,CANCEL,PAY,PUSH,VOID,ORDER_FEE, etc.
The private ISV API doesn't expose direct deposit or withdraw endpoints.
5. Failure modes
| HTTP | When |
|---|---|
400 | Bad request — invalid limit (outside 1..200), malformed before, etc. |
401 | JWT missing or invalid. |
404 | INDIVIDUAL 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.) |
500 | Server 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"Updated 5 days ago
