Docs·Public Data API
Public Data API
Row fields
Every field of every row shape the API returns, with its type and which of them are decimal strings of base units.
Row fields#
The fields below are the row shapes the list and single-resource endpoints return. A field typed wei or base units is a decimal string — see amounts. A timestamp field is an object { unix, iso }, where unix is a decimal string of seconds.
Launch#
| Field | Type | Note |
|---|---|---|
token, curve, creator, creatorFeeRecipient, factory | address | Lower-case. The factory may be a superseded generation |
launchId | integer string | The factory’s own sequence number |
force, forceName | number, LIGHT | DARK | null | The force’s registry id: 0 is LIGHT, 1 is DARK. forceName is null for any other id. Chosen at launch, permanent |
lifecycle | string | CURVE_TRADING, CURVE_COMPLETE, GRADUATED |
dev | boolean | An owner-created test launch. Excluded unless ?includeDev=true |
graduationTargetWei, initialBuyWei | wei | |
initialTokensBought | token base units | |
earlyWalletCap | { status, bps, seconds, untilGraduation } | The creator’s per-wallet cap: bps of total supply (50–250), seconds as an integer string, 4294967295 = until graduation. status: STORED | UNREADABLE | NOT_INDEXED; values null unless stored |
crewSplitter, crewMembers | address | null, number | null | Null on a launch made with no founding crew |
promotedPlacement, promotionPaidWei | number | null, wei | null | Marketing revenue. Never a protocol fee |
launchedAt, block, txHash | timestamp, integer string, hash | |
stats | object | null | null when no trade has been indexed for this launch — not a row of zeros |
stats.trades, .buys, .sells, .uniqueTraders, .holdersDerived | number | holdersDerived is a log-derived count, not a census |
raiseCurrency | object: address, isNativeEth, symbol, decimals | The unit of every amount on this launch. symbol and decimals are null when the index has no listing row for the currency |
stats.curveVolumeWei, .buyVolumeWei, .sellVolumeWei, .tradeFeeWei, .netRaisedWei | base units of raiseCurrency | Wei only when raiseCurrency.isNativeEth. Never add them across launches. netRaisedWei is the raised figure — never realEthReserve, which is zeroed at graduation |
stats.curveVolumeValue | object: ethValueWei, usdValueE18, pricedTrades, unpricedTrades, ethUnpricedTrades, oldestPricedAt, newestPricedAt, valuation | Curve volume at each trade’s event-time price (the CoinGecko price posted on chain and in force at its block). Trades with no price then are left out and counted. The VOLUME sort key |
stats.netRaisedValueWei | wei (may be negative) | netRaisedWei in ETH value, each trade at its own event-time price. The RAISED sort key |
stats.lastFdvWei, .lastPokeAt | wei | null, timestamp | null | null until a pool metrics poke exists. An unmeasured valuation, not a valuation of zero |
/api/v1/launches/{token} returns the same fields plus progressBps (derived from netRaisedWei / graduationTargetWei, capped at 10000, and forced to 10000 once graduated), progressNote, priorFactory, and graduation — which is null unless the launch has graduated, and otherwise carries ethWei, tokenWei, locker, positionId, sqrtPriceX96, block, txHash and at.
Trade#
| Field | Type | Note |
|---|---|---|
id | string | Stable row id. The tie-breaker inside a cursor |
side | BUY | SELL | REDEEM | A REDEEM is a refund out of a curve that never graduated. Filter on side before summing ethWei |
venue, venueKind | address, string | |
trader, recipient | address | |
ethWei, curveQuoteWei, tradeFeeWei | wei | ethWei − curveQuoteWei is the fee this trade actually paid, at the rate that applied at its block |
tokenWei | token base units | |
block, logIndex, txHash, at | integer string, number, hash, timestamp |
Holders#
| Field | Type | Note |
|---|---|---|
census | object | null | null when no census has ever completed. That is unknown, not zero — censusUnavailableReason says what would fix it |
census.holders, .countedSupplyWei, .candidates | number, wei, integer string | The on-chain sweep, with its floor and exclusion list applied |
census.countedAtBlock, .recordedAtBlock, .recordedAt, .txHash | integer string, integer string, timestamp, hash | No contract bounds a census’s age. The consumer decides what is too old, which is why both blocks are published |
derived.holders, .totalSupplyWei | number, wei | null | Non-zero balances in the indexer’s own projection. No floor, no exclusions, so it is always larger. Never mixed with the census |
derived.top[] | holder, balanceWei, transferCount, firstSeenBlock, lastChangeBlock | Largest balance first, up to limit |
Market#
| Field | Type | Note |
|---|---|---|
marketId | bytes32 | The id, not the clone address. address is the clone |
address, factory, oracle, creator | address (oracle may be null) | |
currency, currencyDecimals | address, number | null | The zero address is native ETH. Every amount on the row is in this currency’s base units |
question | string | Free text, written by the creator |
family, metric, comparator, subject, thresholdWei | number | null, address | null, integer string | null | The encoded predicate. Names are resolved on the single-market route |
status | OPEN | SETTLED | VOIDED | PAUSED | Three end states, not two. A settlement with one side empty is SETTLED, refunds everyone at par at zero fee, and is not a void |
paused, featuredTier | boolean, number | null | |
deadline, settlementWindowSeconds, createdAt, block | timestamp, number | null, timestamp, integer string | |
feeBps, marketingBps | number | null | One cut of the whole pot at settlement, not a per-stake fee. Zero in refund mode |
feeRecipient | address | null | PredictionMarketFactory itself, not a payout wallet. Treating it as one attributes every market’s fee to the factory |
stats | object | null | null when nothing has been staked yet |
stats.totalYes, .totalNo, .openInterest | base units of the row’s currency | openInterest is totalYes + totalNo, with the fee not deducted |
stats.paidOut, .refunded, .protocolFee, .marketingFee, .transferShortfall | base units of the row’s currency | transferShortfall is requested minus credited, summed — non-zero only for a fee-on-transfer currency |
stats.stakes, .stakers, .claims | number |
/api/v1/markets/{id} adds a predicate object that resolves the encoded ids to names, and a settlement object that is null until the market settles.
| Field | Values |
|---|---|
familyName | 0 lifecycle · 1 curve · 2 creator |
metricName | 0 GRADUATED · 1 CURVE_COMPLETE · 2 NET_RAISED_WEI · 3 TOKENS_SOLD_BASE_UNITS · 4 PROGRESS_BPS · 5 CURVE_FDV_WEI · 6 CREATOR_LAUNCH_COUNT · 7 CREATOR_GRADUATED_COUNT · 8 CREATOR_TIER · 9 SUPPLY_BURNED · 10 CURVE_TRADE_FEES_WEI · 11 PROTOCOL_FEES_METERED_WEI |
comparatorName | 0 EQ · 1 NEQ · 2 GT · 3 GTE · 4 LT · 5 LTE |
An id with no name resolves to null rather than to a label, so a new metric appearing on chain shows up as an unnamed id rather than as a mislabelled one.
Stake and settlement#
| Field | Type | Note |
|---|---|---|
id, marketId, user | string, bytes32, address | |
side, sideName | boolean, YES | NO | sideName is on the JSON rows; the CSV carries the name in side |
amountRequested, amountCredited | base units of the market’s currency | Sum amountCredited. It is the measured balance delta; the requested figure overstates a fee-on-transfer stake |
totalYesAfter, totalNoAfter | base units of the market’s currency | The running pools immediately after this stake |
block, txHash, at | integer string, hash, timestamp |
| Field | Type | Note |
|---|---|---|
id, marketId, oracle, settler | string, bytes32, address, address | settler is attribution only — settlement is permissionless and unpaid |
outcome | boolean | true is YES. The CSV renders it as YES / NO |
observedValue, thresholdWei | integer string | What the oracle read, against what the predicate required |
deadline, settledAt | timestamp | |
driftSeconds | signed integer string | settledAt − deadline. Negative is an early settle, which is legal where the predicate is already decided |
windowSeconds, windowElapsedBps | number | null | |
block, txHash | integer string, hash | The log’s own block. The settlement event carries no block number of its own |
Creators, KOLs, referrers, traders#
| Field | Type | Note |
|---|---|---|
creator | address | |
launches, graduations | number | Derived from logs |
netRaisedWei, volumeWei, creatorFeeWei, creatorFeeClaimedWei | wei | Derived from logs. Launches that raise in native ETH only |
volumeValueWei, unpricedTrades, unpricedReason, rankValueWei | wei | null, number | null, string | null, wei | Curve volume across every raise currency, each ERC-20 trade at its event-time price; unpriced trades left out and counted. rankValueWei is the ranking key |
registry.launches, .graduated, .netRaisedWei, .tier, .syncedAt | number | null, wei | null, timestamp | null | The registry’s own keeper-driven snapshot, which is what the chain gates a tier on. Never merged with the derived figures |
firstBlock, lastBlock | integer string |
/api/v1/creators/{address} adds registry.tierName: 0 Unranked, 1 Bronze, 2 Silver, 3 Gold, 4 Platinum, 5 Diamond. The tier is derived on every read and never granted.
| Field | Type | Note |
|---|---|---|
account | address | |
allocatedWei, claimedWei | wei | ETH sources only. allocatedWei is what the chain actually paid, summed from allocation logs. No contract holds a lifetime total |
allocatedValueWei, unpricedAllocations, unpricedReason, rankValueWei | wei | null, number | null, string | null, wei | Every allocation, ETH and ERC-20 sources alike, each at its event-time price; unpriced ones left out and counted. rankValueWei is the ranking key |
allocations, windows, sources | number | |
registryFeesWei | wei | null | A different quantity from a different authority: an off-chain attestation, and the one the rank is computed from. The two are not reconciled on chain |
rank, rankRoute, banned | number | null, boolean | null | |
enrolled, xVerified, attestor | boolean | null, address | null | Assertions, not chain-verified facts. The address that asserted them is published beside them — see boundaries |
activeUntil | timestamp | null | Published because the registry’s eligibility check never reads it, so eligibility is not time-bounded |
| Endpoint | Fields |
|---|---|
/referrers | referrer · earnedWei (lifetime, from logs, ETH credits only) · earnedValueWei (ETH and ERC-20 credits at event-time price) · unpricedReceipts · unpricedReason · rankValueWei (the ranking key) · claimedWei · outstandingWei (earned minus claimed, JSON only) · attributedWei (the whole fee that passed through) · receipts · sources · firstBlock · lastBlock |
/referrers?window=7d|30d | The same fields summed over data.window only, ranked by earnedValueWei (rankValueWei equals it). claimedWei and outstandingWei are lifetime-only and absent, listed in data.lifetimeOnlyFields. CSV rows add window, windowFromUnix, windowToUnix |
/traders | trader · volumeWei · buyVolumeWei · sellVolumeWei · tradeFeePaidWei (all ETH launches only) · volumeValueWei (every raise currency at event-time price) · unpricedTrades · unpricedReason · rankValueWei (the ranking key) · trades · buys · sells · tokens · stakes · settlements · voids · firstBlock · lastBlock |
Event-time values#
| Field | Type | Note |
|---|---|---|
valuation.basis | ETH_PLUS_ERC20_AT_EVENT_TIME | ETH_ONLY_INDEX_PREDATES_VALUES | The second means the serving index has no value columns yet: figures are ETH only |
valuation.excludedEvents, valuation.scope | number | null, string | ERC-20 events left out for want of a price at their block. Never a zero for an unknown |
/stats curveVolumeWei, buyVolumeWei, sellVolumeWei, tradeFeeWei | wei | Native-ETH launches only |
/stats curveVolumeValueWei, buyVolumeValueWei, sellVolumeValueWei, erc20Trades | wei, number | Every raise currency at event-time price |
/stats/daily curveVolumeValueWei, tradesUnpriced, stakedValueWei, stakesUnpriced, valueUnavailableReason | wei | null, number, wei | null, number, string | null | null with a reason on a day written before the value columns existed. The day’s other …Wei fields are native ETH only |
/fees erc20ByCurrency[] | currency, symbol, decimals, tradeFee, creator, kol, referrer, toFeeConverter, launchFeeSwept | ERC-20 fee legs, per currency, in that currency’s base units. No ETH total is published for them |