Game

Game state, leaderboards, feeds, and PnL cards

PnL card

get/cards/pnl

Query parameters

positionIdstring
Position id: canonical decimal (digits only, no sign, whitespace or leading zero), else 400 bad_position (empty included; "0007" is refused, not echoed). A canonical decimal above 18446744073709551615 names no position: 404 position_not_found, without calling the service. Omitted: the service's position_required.
Pattern^(0|[1-9][0-9]*)$
Example1042

Responses

PnL card. positionId is forwarded when present and omitted when omitted.
application/json
dataPnlCardrequired
The PnL card of a position.
isLongbooleanrequired
marketIdstringrequired
Pattern^0x[0-9a-f]{64}$
Example0x6e6238eb4f69bfcc3e884a7d20904eb0995ca2e42c95dc8560d5a417486ab645
pnlstringrequired
Realized PnL of the last close or liquidation (base units); 0 while open.
Pattern^-?(0|[1-9][0-9]*)n$
Example42500000n
pnlPctstringrequired
pnl * 10000 / margin (bps); 0 without a margin.
Pattern^-?(0|[1-9][0-9]*)n$
Example1250n
positionIdstringrequired
Pattern^-?(0|[1-9][0-9]*)n$
Example1042n
settledbooleanrequired
Whether the close or liquidation is indexed, including a settled zero PnL.
walletAddressstringrequired
Pattern^0x[0-9a-f]{64}$
Example0x77b909b550ed11c45f1378c03c0954c0d77d320cdc938e35509564b1e505ce0d
position_required from the service (positionId omitted); bad_position (positionId not a canonical decimal, checked locally)
application/json
errorErrorObjectrequired
codestringrequired
messagestringrequired
position_not_found: from the service for an unknown positionId, locally for one above 18446744073709551615
application/json
errorErrorObjectrequired
codestringrequired
messagestringrequired
rate_limited: too many requests from this client IP; retry after Retry-After seconds
application/json
Headers: Retry-After
errorErrorObjectrequired
codestringrequired
messagestringrequired
Bad gateway: the service is temporarily unavailable
application/json
errorErrorObjectrequired
codestringrequired
messagestringrequired

Example request

curl 'https://api.parchment.trade/cards/pnl'

const res = await fetch("https://api.parchment.trade/cards/pnl");
const { data } = await res.json();

Example response (200)

application/json

{
  "data": {
    "isLong": true,
    "marketId": "0x6e6238eb4f69bfcc3e884a7d20904eb0995ca2e42c95dc8560d5a417486ab645",
    "pnl": "42500000n",
    "pnlPct": "1250n",
    "positionId": "1042n",
    "settled": true,
    "walletAddress": "0x77b909b550ed11c45f1378c03c0954c0d77d320cdc938e35509564b1e505ce0d"
  }
}

Rekt feed

get/feed/rekt

Query parameters

limitstring
Page size: canonical decimal (digits only, no sign, whitespace or leading zero), 1 to 18446744073709551615, else 400 bad_request; an empty value is omitted (service default 50).
Pattern^(0|[1-9][0-9]*)$
Example50

Responses

Rekt feed. The service's typed response, as public camelCase JSON; entries carry side, isLong, leverage and kind.
application/json
dataFeedrequired
entriesFeedEntry[]required
atMsstringrequired
Milliseconds.
Pattern^-?(0|[1-9][0-9]*)n$
Example1796677200000n
exitWadstring | null
The position's exit price (WAD); null while it is open or unindexed.
Pattern^-?(0|[1-9][0-9]*)n$
Example74250000000000000000n
isLongboolean | null
kindstringrequired
What a feed entry records.
One ofopencloseliquidate
leveragestring | null
Pattern^-?(0|[1-9][0-9]*)n$
Example10n
marketIdstringrequired
Pattern^0x[0-9a-f]{64}$
Example0x6e6238eb4f69bfcc3e884a7d20904eb0995ca2e42c95dc8560d5a417486ab645
notionalstringrequired
Position notional (base units).
Pattern^-?(0|[1-9][0-9]*)n$
Example1000000000n
pnlstringrequired
Realized PnL (base units); 0 on an open.
Pattern^-?(0|[1-9][0-9]*)n$
Example42500000n
positionIdstringrequired
Pattern^-?(0|[1-9][0-9]*)n$
Example1042n
sidenull | string
walletAddressstringrequired
Pattern^0x[0-9a-f]{64}$
Example0x77b909b550ed11c45f1378c03c0954c0d77d320cdc938e35509564b1e505ce0d
rate_limited: too many requests from this client IP; retry after Retry-After seconds
application/json
Headers: Retry-After
errorErrorObjectrequired
codestringrequired
messagestringrequired
Bad gateway: the service is temporarily unavailable
application/json
errorErrorObjectrequired
codestringrequired
messagestringrequired

Example request

curl 'https://api.parchment.trade/feed/rekt'

const res = await fetch("https://api.parchment.trade/feed/rekt");
const { data } = await res.json();

Example response (200)

application/json

{
  "data": {
    "entries": [
      {
        "atMs": "1796677200000n",
        "exitWad": "74250000000000000000n",
        "isLong": true,
        "kind": "open",
        "leverage": "10n",
        "marketId": "0x6e6238eb4f69bfcc3e884a7d20904eb0995ca2e42c95dc8560d5a417486ab645",
        "notional": "1000000000n",
        "pnl": "42500000n",
        "positionId": "1042n",
        "side": "long",
        "walletAddress": "0x77b909b550ed11c45f1378c03c0954c0d77d320cdc938e35509564b1e505ce0d"
      }
    ]
  }
}

Whale feed

get/feed/whales

Query parameters

limitstring
Page size: canonical decimal (digits only, no sign, whitespace or leading zero), 1 to 18446744073709551615, else 400 bad_request; an empty value is omitted (service default 50).
Pattern^(0|[1-9][0-9]*)$
Example50

Responses

Whale feed. The service's typed response, as public camelCase JSON; entries carry side, isLong, leverage and kind.
application/json
dataFeedrequired
entriesFeedEntry[]required
atMsstringrequired
Milliseconds.
Pattern^-?(0|[1-9][0-9]*)n$
Example1796677200000n
exitWadstring | null
The position's exit price (WAD); null while it is open or unindexed.
Pattern^-?(0|[1-9][0-9]*)n$
Example74250000000000000000n
isLongboolean | null
kindstringrequired
What a feed entry records.
One ofopencloseliquidate
leveragestring | null
Pattern^-?(0|[1-9][0-9]*)n$
Example10n
marketIdstringrequired
Pattern^0x[0-9a-f]{64}$
Example0x6e6238eb4f69bfcc3e884a7d20904eb0995ca2e42c95dc8560d5a417486ab645
notionalstringrequired
Position notional (base units).
Pattern^-?(0|[1-9][0-9]*)n$
Example1000000000n
pnlstringrequired
Realized PnL (base units); 0 on an open.
Pattern^-?(0|[1-9][0-9]*)n$
Example42500000n
positionIdstringrequired
Pattern^-?(0|[1-9][0-9]*)n$
Example1042n
sidenull | string
walletAddressstringrequired
Pattern^0x[0-9a-f]{64}$
Example0x77b909b550ed11c45f1378c03c0954c0d77d320cdc938e35509564b1e505ce0d
rate_limited: too many requests from this client IP; retry after Retry-After seconds
application/json
Headers: Retry-After
errorErrorObjectrequired
codestringrequired
messagestringrequired
Bad gateway: the service is temporarily unavailable
application/json
errorErrorObjectrequired
codestringrequired
messagestringrequired

Example request

curl 'https://api.parchment.trade/feed/whales'

const res = await fetch("https://api.parchment.trade/feed/whales");
const { data } = await res.json();

Example response (200)

application/json

{
  "data": {
    "entries": [
      {
        "atMs": "1796677200000n",
        "exitWad": "74250000000000000000n",
        "isLong": true,
        "kind": "open",
        "leverage": "10n",
        "marketId": "0x6e6238eb4f69bfcc3e884a7d20904eb0995ca2e42c95dc8560d5a417486ab645",
        "notional": "1000000000n",
        "pnl": "42500000n",
        "positionId": "1042n",
        "side": "long",
        "walletAddress": "0x77b909b550ed11c45f1378c03c0954c0d77d320cdc938e35509564b1e505ce0d"
      }
    ]
  }
}

Game definitions

get/game/definitions

Responses

Quest, achievement (with mintAmount) and cosmetic definitions plus achievementMintFractionBps and the service progression catalog (XP rules, tiers, achievements and cosmetics). The service's typed response, as public camelCase JSON. Quests, daily claims and crates grant XP/cosmetics only; FEES_PAID achievements are the only game mint.
application/json
dataGameDefinitionsrequired
Registered quests, achievements and cosmetics, by id.
achievementMintFractionBpsstringrequired
Indexed achievement_mint_fraction_bps, else the launch default (2500).
Pattern^-?(0|[1-9][0-9]*)n$
Example2000n
achievementsAchievementDefinition[]required
activebooleanrequired
cosmeticstring | null
Pattern^-?(0|[1-9][0-9]*)n$
Example4n
idstringrequired
Pattern^-?(0|[1-9][0-9]*)n$
Example7n
kindstringrequired
Pattern^-?(0|[1-9][0-9]*)n$
Example0n
mintAmountstringrequired
Game PARCHMENT accrued on unlock (base units).
Pattern^-?(0|[1-9][0-9]*)n$
Example1500000000000n
namestring | null
null when the registration carried no UTF-8 name.
paramstringrequired
Pattern^-?(0|[1-9][0-9]*)n$
Example3n
xpstringrequired
Pattern^-?(0|[1-9][0-9]*)n$
Example1250n
catalogCatalogrequired
achievementsAchievementDef[]required
badgeSlotsstringrequired
Pattern^(0|[1-9][0-9]*)n$
Example3n
cosmeticsCosmeticDef[]required
giltMarkXpstringrequired
Pattern^(0|[1-9][0-9]*)n$
Example1250n
maxLevelstringrequired
Pattern^(0|[1-9][0-9]*)n$
Example4n
seasonAchievementsSeasonAchievementDef[]required
tiersTierDef[]required
xpRulesVersionstringrequired
Pattern^(0|[1-9][0-9]*)n$
Example1n
cosmeticsCosmeticDefinition[]required
questsQuestDefinition[]required
activebooleanrequired
cosmeticstring | null
Pattern^-?(0|[1-9][0-9]*)n$
Example4n
endMsstringrequired
Milliseconds.
Pattern^-?(0|[1-9][0-9]*)n$
Example1796677200000n
idstringrequired
Pattern^-?(0|[1-9][0-9]*)n$
Example7n
kindstringrequired
Pattern^-?(0|[1-9][0-9]*)n$
Example0n
namestring | null
null when the registration carried no UTF-8 name.
paramstringrequired
Pattern^-?(0|[1-9][0-9]*)n$
Example3n
seasonIdstringrequired
Pattern^-?(0|[1-9][0-9]*)n$
Example3n
serviceXpstring | null
Service XP awarded for this quest; absent when the service omits it.
Pattern^-?(0|[1-9][0-9]*)n$
Example1250n
startMsstringrequired
Milliseconds.
Pattern^-?(0|[1-9][0-9]*)n$
Example1796677200000n
xpstringrequired
Pattern^-?(0|[1-9][0-9]*)n$
Example1250n
rate_limited: too many requests from this client IP; retry after Retry-After seconds
application/json
Headers: Retry-After
errorErrorObjectrequired
codestringrequired
messagestringrequired
Bad gateway: the service is temporarily unavailable
application/json
errorErrorObjectrequired
codestringrequired
messagestringrequired

Example request

curl 'https://api.parchment.trade/game/definitions'

const res = await fetch("https://api.parchment.trade/game/definitions");
const { data } = await res.json();

Example response (200)

application/json

{
  "data": {
    "achievementMintFractionBps": "2000n",
    "achievements": [
      {
        "active": true,
        "cosmetic": "4n",
        "id": "7n",
        "kind": "0n",
        "mintAmount": "1500000000000n",
        "name": "string",
        "param": "3n",
        "xp": "1250n"
      }
    ],
    "catalog": {
      "achievements": [
        {
          "category": "string",
          "chainId": "1n",
          "description": "string",
          "key": "string",
          "mint": "1500000000000n",
          "name": "string",
          "onChain": true,
          "stamp": "string",
          "target": "3n",
          "xp": "1250n"
        }
      ],
      "badgeSlots": "3n",
      "cosmetics": [
        {
          "chainId": "1n",
          "key": "string",
          "name": "string",
          "rarity": "string",
          "slot": "string",
          "source": "string"
        }
      ],
      "giltMarkXp": "1250n",
      "maxLevel": "4n",
      "seasonAchievements": [
        {
          "name": "string",
          "suffix": "string",
          "xp": "1250n"
        }
      ],
      "tiers": [
        {
          "key": "string",
          "minLevel": "4n",
          "minXp": "1250n",
          "name": "string",
          "stamp": "string",
          "tagline": "string"
        }
      ],
      "xpRulesVersion": "1n"
    },
    "cosmetics": [
      {
        "id": "7n",
        "name": "string"
      }
    ],
    "quests": [
      {
        "active": true,
        "cosmetic": "4n",
        "endMs": "1796677200000n",
        "id": "7n",
        "kind": "0n",
        "name": "string",
        "param": "3n",
        "seasonId": "3n",
        "serviceXp": "1250n",
        "startMs": "1796677200000n",
        "xp": "1250n"
      }
    ]
  }
}

Game profile

get/game/{walletAddress}

Path parameters

walletAddressstringrequired
Wallet address
Pattern^(0[xX])?[0-9a-fA-F]{1,64}$
Example0x77b909b550ed11c45f1378c03c0954c0d77d320cdc938e35509564b1e505ce0d

Responses

Game state for the wallet, including service XP, levels, named tiers, achievement progress, cosmetic ownership and card drops. chainXp and chainAchievementIds/chainCosmeticIds preserve the on-chain counters. The service's typed response, as public camelCase JSON, every integer an n-suffixed decimal string ("5000000n"), including pendingMint, lastDailyDay, dailyClaimedToday, feeCredit / feeCreditUsed, achievementMintFractionBps and feeAchievements (feesRequired, feesNeeded, eligibleMint, mintAtUnlock, unlocked). lockedLedgerStatus is current, rebuilding or failed; the seven locked-mint ledger figures (lockedBalance, lockWindowBalance, nextUnlockMs, vestingBalance, releasableNow, earlyExitPaidNow, earlyExitPenaltyNow) are n-suffixed decimal strings while it is current and null otherwise (never zero-filled). earlyExitUnlocks is the n-suffixed decimal list of ledger entries earlyExitPenaltyNow covers, read with earlyExitPaidNow and earlyExitPenaltyNow in one ledger snapshot; pass it and earlyExitPenaltyNow (as maxPenalty) to exit-early-bounded. It is null when the ledger is not current or the service does not serve the quote (404); another quote failure is the route's error. A quote that finds the ledger no longer current serves that status with every ledger figure null. Only fee-backed achievements accrue game PARCHMENT; collect-mint issues it.
application/json
dataGameProfilerequired
A wallet's game state (zeros for an unknown wallet).
achievementMintFractionBpsstringrequired
Basis points (1/10000).
Pattern^-?(0|[1-9][0-9]*)n$
Example2000n
achievementsAchievementState[]required
cardDropsCardDrop[]required
chainAchievementIdsstring[]required
chainCosmeticIdsstring[]required
chainCountersChainCounter[] | null
The wallet's on-chain game_book counters as last reported by CountersUpdatedEvent, ascending kind (game_events::counter_*; 2 and 3 are the last genuine winning close's leverage and profit bps). Raw: achievement progress above stays service-derived. Omitted by older services.
chainXpstringrequired
Pattern^(0|[1-9][0-9]*)n$
Example1250n
cosmeticsCosmeticState[]required
cratesstringrequired
Unopened crates.
Pattern^-?(0|[1-9][0-9]*)n$
Example3n
dailyClaimedTodaybooleanrequired
earlyExitPaidNowstring | null
What an early exit would pay now (vest_status.exit_paid).
Pattern^-?(0|[1-9][0-9]*)n$
Example1200000000000n
earlyExitPenaltyNowstring | null
What an early exit would forfeit now (vest_status.exit_penalty).
Pattern^-?(0|[1-9][0-9]*)n$
Example300000000000n
earlyExitUnlocksstring[] | null
feeAchievementsFeeAchievement[]required
activebooleanrequired
eligibleMintstringrequired
mint_amount when the next settle with no new fees pays this rung, else 0.
Pattern^-?(0|[1-9][0-9]*)n$
Example1500000000000n
feesNeededstringrequired
Fee credit still to pay before a settle is sure to pay this rung in full: 0 when eligible, else the larger of fees_required - fee_credit and the full cost of this rung plus every earlier locked rung, less the unconsumed credit (can exceed fees_required - fee_credit).
Pattern^-?(0|[1-9][0-9]*)n$
Example250000000n
feesRequiredstringrequired
The achievement's param: fees to pay to unlock it (base units).
Pattern^-?(0|[1-9][0-9]*)n$
Example250000000n
idstringrequired
Pattern^-?(0|[1-9][0-9]*)n$
Example7n
mintAmountstringrequired
Pattern^-?(0|[1-9][0-9]*)n$
Example1500000000000n
mintAtUnlockstringrequired
The mint the rung pays when it unlocks: the full mintAmount, never part of it.
Pattern^-?(0|[1-9][0-9]*)n$
Example1500000000000n
namestring | null
unlockableboolean | null
False when no fee top-up can unlock this locked rung under the current config (inactive, a mint at fraction 0, or past the fee-credit ceiling); true once unlocked. Optional: omitted while the service's response does not carry it.
unlockedbooleanrequired
xpstringrequired
Pattern^-?(0|[1-9][0-9]*)n$
Example1250n
feeCreditstringrequired
Pattern^-?(0|[1-9][0-9]*)n$
Example800000n
feeCreditUsedstringrequired
Pattern^-?(0|[1-9][0-9]*)n$
Example800000n
giltMarksstringrequired
Pattern^(0|[1-9][0-9]*)n$
Example3n
lastDailyDaystring | null
UTC day (ms / 86_400_000) of the last daily claim; null before the first.
Pattern^-?(0|[1-9][0-9]*)n$
Example20794n
levelstringrequired
Pattern^(0|[1-9][0-9]*)n$
Example4n
levelXpstringrequired
Pattern^(0|[1-9][0-9]*)n$
Example1250n
lockWindowBalancestring | null
Part still inside the lock window (vest_status.locked).
Pattern^-?(0|[1-9][0-9]*)n$
Example1200000000000n
lockedBalancestring | null
Everything held in the wallet's locked ledger.
Pattern^-?(0|[1-9][0-9]*)n$
Example1200000000000n
lockedLedgerStatusstringrequired
Whether the seven ledger figures below come from the wallet's current ledger; they are null unless it is current.
One ofcurrentrebuildingfailed
lockedMintSchedulenull | LockedMintSchedule
mintedstringrequired
Game PARCHMENT minted to the wallet so far (base units).
Pattern^-?(0|[1-9][0-9]*)n$
Example1500000000000n
mintedTodaystringrequired
Game PARCHMENT issued to the wallet in the current UTC day (base units).
Pattern^-?(0|[1-9][0-9]*)n$
Example1500000000000n
nextLevelXpstringrequired
Pattern^(0|[1-9][0-9]*)n$
Example1250n
nextTierstring | null
nextUnlockMsstring | null
When the next entry leaves the lock; 0 when nothing is still inside the lock.
Pattern^-?(0|[1-9][0-9]*)n$
Example1796677200000n
parkedMintnull | ParkedMint
claimsParkedMintClaim[]required
Latest claim per account that has claimed.
accountIdstringrequired
Pattern^0x[0-9a-f]{64}$
Example0xad23e722f3542ae36c276c1b303e30ae77c840a84db89c7215fa87bf92006691
amountstringrequired
Pattern^(0|[1-9][0-9]*)n$
Example100000000n
basisstringrequired
Pattern^(0|[1-9][0-9]*)n$
Example42500000n
epochsstringrequired
Pattern^(0|[1-9][0-9]*)n$
Example24n
remainingBasisstringrequired
Pattern^(0|[1-9][0-9]*)n$
Example42500000n
remainingEpochsstringrequired
Parked loss days still to claim (claim again while non-zero).
Pattern^(0|[1-9][0-9]*)n$
Example24n
timestampMsstringrequired
Milliseconds.
Pattern^(0|[1-9][0-9]*)n$
Example1796677200000n
txDigeststringrequired
Pattern^[1-9A-HJ-NP-Za-km-z]{32,44}$
Examplec3CE1sYJ2ufo1E8wNhVahkJbu66F4tMxpTXLeW3o8QSA
lastParkednull | LedgerFullParked
accountIdstring | null
The account whose pending basis holds it; null for game issuance (kind 2).
Pattern^0x[0-9a-f]{64}$
Example0xad23e722f3542ae36c276c1b303e30ae77c840a84db89c7215fa87bf92006691
basisstringrequired
Pattern^(0|[1-9][0-9]*)n$
Example42500000n
kindstringrequired
0 loss mint (claim with claim-pending-mint), 1 parked claim left parked, 2 game issuance left pending (collect-mint).
Pattern^(0|[1-9][0-9]*)n$
Example0n
timestampMsstringrequired
Milliseconds.
Pattern^(0|[1-9][0-9]*)n$
Example1796677200000n
txDigeststringrequired
Pattern^[1-9A-HJ-NP-Za-km-z]{32,44}$
Examplec3CE1sYJ2ufo1E8wNhVahkJbu66F4tMxpTXLeW3o8QSA
pendingMintstringrequired
Accrued, not yet issued (base units).
Pattern^-?(0|[1-9][0-9]*)n$
Example1500000000000n
questsQuestDefinition[]required
Quest definitions supplied by the service.
activebooleanrequired
cosmeticstring | null
Pattern^-?(0|[1-9][0-9]*)n$
Example4n
endMsstringrequired
Milliseconds.
Pattern^-?(0|[1-9][0-9]*)n$
Example1796677200000n
idstringrequired
Pattern^-?(0|[1-9][0-9]*)n$
Example7n
kindstringrequired
Pattern^-?(0|[1-9][0-9]*)n$
Example0n
namestring | null
null when the registration carried no UTF-8 name.
paramstringrequired
Pattern^-?(0|[1-9][0-9]*)n$
Example3n
seasonIdstringrequired
Pattern^-?(0|[1-9][0-9]*)n$
Example3n
serviceXpstring | null
Service XP awarded for this quest; absent when the service omits it.
Pattern^-?(0|[1-9][0-9]*)n$
Example1250n
startMsstringrequired
Milliseconds.
Pattern^-?(0|[1-9][0-9]*)n$
Example1796677200000n
xpstringrequired
Pattern^-?(0|[1-9][0-9]*)n$
Example1250n
questsDonestring[]required
releasableNowstring | null
vest_status.claimable: releasable now.
Pattern^-?(0|[1-9][0-9]*)n$
Example1200000000000n
seasonIdstringrequired
Pattern^-?(0|[1-9][0-9]*)n$
Example3n
seasonRankstringrequired
Pattern^(0|[1-9][0-9]*)n$
Example17n
seasonXpstringrequired
Pattern^-?(0|[1-9][0-9]*)n$
Example1250n
streakstringrequired
Pattern^-?(0|[1-9][0-9]*)n$
Example3n
tierstringrequired
tierKeystringrequired
tradesstringrequired
Pattern^-?(0|[1-9][0-9]*)n$
Example24n
vestingBalancestring | null
Part unlocked and vesting (vest_status.vesting).
Pattern^-?(0|[1-9][0-9]*)n$
Example1200000000000n
walletAddressstringrequired
Pattern^0x[0-9a-f]{64}$
Example0x77b909b550ed11c45f1378c03c0954c0d77d320cdc938e35509564b1e505ce0d
winStreakstringrequired
Pattern^-?(0|[1-9][0-9]*)n$
Example3n
xpstringrequired
Pattern^-?(0|[1-9][0-9]*)n$
Example1250n
xpRulesVersionstringrequired
Pattern^(0|[1-9][0-9]*)n$
Example1n
application/json
errorErrorObjectrequired
codestringrequired
messagestringrequired
rate_limited: too many requests from this client IP; retry after Retry-After seconds
application/json
Headers: Retry-After
errorErrorObjectrequired
codestringrequired
messagestringrequired
Bad gateway: the service is temporarily unavailable
application/json
errorErrorObjectrequired
codestringrequired
messagestringrequired

Example request

curl 'https://api.parchment.trade/game/0x77b909b550ed11c45f1378c03c0954c0d77d320cdc938e35509564b1e505ce0d'

const res = await fetch("https://api.parchment.trade/game/0x77b909b550ed11c45f1378c03c0954c0d77d320cdc938e35509564b1e505ce0d");
const { data } = await res.json();

Example response (200)

application/json

{
  "data": {
    "achievementMintFractionBps": "2000n",
    "achievements": [
      {
        "key": "string",
        "progress": "3n",
        "target": "3n",
        "unlocked": true,
        "unlockedAtMs": "1796677200000n"
      }
    ],
    "cardDrops": [
      {
        "eventSeq": "88231n",
        "key": "string",
        "timestampMs": "1796677200000n",
        "txDigest": "c3CE1sYJ2ufo1E8wNhVahkJbu66F4tMxpTXLeW3o8QSA"
      }
    ],
    "chainAchievementIds": [
      "4n"
    ],
    "chainCosmeticIds": [
      "4n"
    ],
    "chainCounters": [
      {
        "kind": "4n",
        "value": "100000000n"
      }
    ],
    "chainXp": "1250n",
    "cosmetics": [
      {
        "key": "string",
        "owned": true,
        "source": "string"
      }
    ],
    "crates": "3n",
    "dailyClaimedToday": true,
    "earlyExitPaidNow": "1200000000000n",
    "earlyExitPenaltyNow": "300000000000n",
    "earlyExitUnlocks": [
      "1500000000000n"
    ],
    "feeAchievements": [
      {
        "active": true,
        "eligibleMint": "1500000000000n",
        "feesNeeded": "250000000n",
        "feesRequired": "250000000n",
        "id": "7n",
        "mintAmount": "1500000000000n",
        "mintAtUnlock": "1500000000000n",
        "name": "string",
        "unlockable": true,
        "unlocked": true,
        "xp": "1250n"
      }
    ],
    "feeCredit": "800000n",
    "feeCreditUsed": "800000n",
    "giltMarks": "3n",
    "lastDailyDay": "20794n",
    "level": "4n",
    "levelXp": "1250n",
    "lockWindowBalance": "1200000000000n",
    "lockedBalance": "1200000000000n",
    "lockedLedgerStatus": "current",
    "lockedMintSchedule": {
      "lockMs": "604800000n",
      "vestMs": "2592000000n"
    },
    "minted": "1500000000000n",
    "mintedToday": "1500000000000n",
    "nextLevelXp": "1250n",
    "nextTier": "string",
    "nextUnlockMs": "1796677200000n",
    "parkedMint": {
      "claims": [
        {
          "accountId": "0xad23e722f3542ae36c276c1b303e30ae77c840a84db89c7215fa87bf92006691",
          "amount": "100000000n",
          "basis": "42500000n",
          "epochs": "24n",
          "remainingBasis": "42500000n",
          "remainingEpochs": "24n",
          "timestampMs": "1796677200000n",
          "txDigest": "c3CE1sYJ2ufo1E8wNhVahkJbu66F4tMxpTXLeW3o8QSA"
        }
      ],
      "lastParked": {
        "accountId": "0xad23e722f3542ae36c276c1b303e30ae77c840a84db89c7215fa87bf92006691",
        "basis": "42500000n",
        "kind": "0n",
        "timestampMs": "1796677200000n",
        "txDigest": "c3CE1sYJ2ufo1E8wNhVahkJbu66F4tMxpTXLeW3o8QSA"
      }
    },
    "pendingMint": "1500000000000n",
    "quests": [
      {
        "active": true,
        "cosmetic": "4n",
        "endMs": "1796677200000n",
        "id": "7n",
        "kind": "0n",
        "name": "string",
        "param": "3n",
        "seasonId": "3n",
        "serviceXp": "1250n",
        "startMs": "1796677200000n",
        "xp": "1250n"
      }
    ],
    "questsDone": [
      "12n"
    ],
    "releasableNow": "1200000000000n",
    "seasonId": "3n",
    "seasonRank": "17n",
    "seasonXp": "1250n",
    "streak": "3n",
    "tier": "string",
    "tierKey": "string",
    "trades": "24n",
    "vestingBalance": "1200000000000n",
    "walletAddress": "0x77b909b550ed11c45f1378c03c0954c0d77d320cdc938e35509564b1e505ce0d",
    "winStreak": "3n",
    "xp": "1250n",
    "xpRulesVersion": "1n"
  }
}

XP ledger

get/game/{walletAddress}/xp-ledger

Path parameters

walletAddressstringrequired
Wallet address
Pattern^(0[xX])?[0-9a-fA-F]{1,64}$
Example0x77b909b550ed11c45f1378c03c0954c0d77d320cdc938e35509564b1e505ce0d

Query parameters

cursorstring
Offset cursor returned by the service.
Example0xc00d9a508112ec1dff7df53f35f096e26af4ec600dc291264b483d27aeb18b75
limitstring
Page size; the service defaults to 50 and caps at 200.
Example50

Responses

Service XP ledger, newest first, with the next offset cursor.
application/json
dataLedgerPagerequired
nextCursorstring | null
rowsLedgerRow[]required
application/json
errorErrorObjectrequired
codestringrequired
messagestringrequired
rate_limited: too many requests from this client IP; retry after Retry-After seconds
application/json
Headers: Retry-After
errorErrorObjectrequired
codestringrequired
messagestringrequired
Bad gateway: the service is temporarily unavailable
application/json
errorErrorObjectrequired
codestringrequired
messagestringrequired
application/json
errorErrorObjectrequired
codestringrequired
messagestringrequired

Example request

curl 'https://api.parchment.trade/game/0x77b909b550ed11c45f1378c03c0954c0d77d320cdc938e35509564b1e505ce0d/xp-ledger'

const res = await fetch("https://api.parchment.trade/game/0x77b909b550ed11c45f1378c03c0954c0d77d320cdc938e35509564b1e505ce0d/xp-ledger");
const { data } = await res.json();

Example response (200)

application/json

{
  "data": {
    "nextCursor": "string",
    "rows": [
      {
        "amount": "100000000n",
        "key": "string",
        "seasonId": "3n",
        "source": "string",
        "timestampMs": "1796677200000n"
      }
    ]
  }
}

Leaderboards

get/leaderboards

Query parameters

periodstring
Window: daily, weekly, all or season; omitted or empty is all. Anything else is 400 bad_period.
One ofdailyweeklyallseason
bystring
Ranking metric: pnl (realized PnL), pnlPct (PnL in basis points of margin), volume (open notional), winStreak or xp; omitted or empty is pnl. Anything else is 400 bad_metric.
One ofpnlpnlPctvolumewinStreakxp
ownerstring
Viewer wallet: normalized; an empty value is omitted; anything else is 400 bad_request.
Example0x77b909b550ed11c45f1378c03c0954c0d77d320cdc938e35509564b1e505ce0d
cursorstring
Row offset: ASCII digits up to 18446744073709551615 (surrounding whitespace trimmed); an empty value is omitted; anything else is 400 bad_cursor.
Pattern^[0-9]+$
Example50
limitstring
Page size: canonical decimal (digits only, no sign, whitespace or leading zero), 1 to 18446744073709551615, else 400 bad_request; an empty value is omitted.
Pattern^(0|[1-9][0-9]*)$
Example50
nowMsstring
Clock for the day/week windows, canonical decimal (digits only, no sign, whitespace or leading zero) from 0 to 18446744073709551615, else 400 bad_time; an empty value is omitted (service default: its own clock). Negative values are 400.
Pattern^(0|[1-9][0-9]*)$
Example1796677200000

Responses

Leaderboards. period, by, owner (normalized), cursor (canonical), limit, and nowMs are forwarded when present and omitted when omitted. Rows and viewer carry per-period stats.
application/json
dataLeaderboardrequired
One offset page, with the viewer's (owner) row.
bystringrequired
Leaderboard ranking metric (by; the service defaults to pnl).
One ofpnlpnlPctvolumewinStreakxp
nextCursorstring | null
Offset of the next page (the request's cursor); null on the last page.
Pattern^-?(0|[1-9][0-9]*)n$
Example50n
periodstringrequired
Leaderboard window (period; the service defaults to all).
One ofdailyweeklyallseason
rowsLeaderboardRow[]required
rankstringrequired
1-based.
Pattern^-?(0|[1-9][0-9]*)n$
Example17n
statsLeaderboardStatsrequired
A leaderboard row's stats inside the board's period window.
closesstringrequired
Settled closes and liquidations.
Pattern^-?(0|[1-9][0-9]*)n$
Example24n
pnlstringrequired
Realized PnL (base units).
Pattern^-?(0|[1-9][0-9]*)n$
Example42500000n
tierstringrequired
Pattern^-?(0|[1-9][0-9]*)n$
Example4n
tradesstringrequired
Opens.
Pattern^-?(0|[1-9][0-9]*)n$
Example24n
volumestringrequired
Open notional (base units).
Pattern^-?(0|[1-9][0-9]*)n$
Example1850000000000n
winRateBpsstring | null
wins * 10000 / closes; null without a close.
Pattern^-?(0|[1-9][0-9]*)n$
Example5400n
winStreakstringrequired
Pattern^-?(0|[1-9][0-9]*)n$
Example3n
winsstringrequired
Closes with a positive PnL.
Pattern^-?(0|[1-9][0-9]*)n$
Example24n
xpstringrequired
Pattern^-?(0|[1-9][0-9]*)n$
Example1250n
valuestringrequired
The by metric's value: pnl and volume in USDC base units (6 decimals), pnlPct in basis points of margin (sum(pnl) * 10000 / sum(margin)), winStreak the win streak (consecutive winning closes), xp in XP.
Pattern^-?(0|[1-9][0-9]*)n$
Example100000000n
walletAddressstringrequired
Pattern^0x[0-9a-f]{64}$
Example0x77b909b550ed11c45f1378c03c0954c0d77d320cdc938e35509564b1e505ce0d
viewernull | LeaderboardRow
rankstringrequired
1-based.
Pattern^-?(0|[1-9][0-9]*)n$
Example17n
statsLeaderboardStatsrequired
A leaderboard row's stats inside the board's period window.
closesstringrequired
Settled closes and liquidations.
Pattern^-?(0|[1-9][0-9]*)n$
Example24n
pnlstringrequired
Realized PnL (base units).
Pattern^-?(0|[1-9][0-9]*)n$
Example42500000n
tierstringrequired
Pattern^-?(0|[1-9][0-9]*)n$
Example4n
tradesstringrequired
Opens.
Pattern^-?(0|[1-9][0-9]*)n$
Example24n
volumestringrequired
Open notional (base units).
Pattern^-?(0|[1-9][0-9]*)n$
Example1850000000000n
winRateBpsstring | null
wins * 10000 / closes; null without a close.
Pattern^-?(0|[1-9][0-9]*)n$
Example5400n
winStreakstringrequired
Pattern^-?(0|[1-9][0-9]*)n$
Example3n
winsstringrequired
Closes with a positive PnL.
Pattern^-?(0|[1-9][0-9]*)n$
Example24n
xpstringrequired
Pattern^-?(0|[1-9][0-9]*)n$
Example1250n
valuestringrequired
The by metric's value: pnl and volume in USDC base units (6 decimals), pnlPct in basis points of margin (sum(pnl) * 10000 / sum(margin)), winStreak the win streak (consecutive winning closes), xp in XP.
Pattern^-?(0|[1-9][0-9]*)n$
Example100000000n
walletAddressstringrequired
Pattern^0x[0-9a-f]{64}$
Example0x77b909b550ed11c45f1378c03c0954c0d77d320cdc938e35509564b1e505ce0d
Invalid limit (bad_request) or nowMs (bad_time): not a canonical decimal up to 18446744073709551615; owner not an address (bad_request); cursor not ASCII digits up to 18446744073709551615 (bad_cursor)
application/json
errorErrorObjectrequired
codestringrequired
messagestringrequired
rate_limited: too many requests from this client IP; retry after Retry-After seconds
application/json
Headers: Retry-After
errorErrorObjectrequired
codestringrequired
messagestringrequired
Bad gateway: the service is temporarily unavailable
application/json
errorErrorObjectrequired
codestringrequired
messagestringrequired
season_rebuilding: the service is rebuilding the season leaderboard; retry later
application/json
errorErrorObjectrequired
codestringrequired
messagestringrequired

Example request

curl 'https://api.parchment.trade/leaderboards'

const res = await fetch("https://api.parchment.trade/leaderboards");
const { data } = await res.json();

Example response (200)

application/json

{
  "data": {
    "by": "pnl",
    "nextCursor": "50n",
    "period": "daily",
    "rows": [
      {
        "rank": "17n",
        "stats": {
          "closes": "24n",
          "pnl": "42500000n",
          "tier": "4n",
          "trades": "24n",
          "volume": "1850000000000n",
          "winRateBps": "5400n",
          "winStreak": "3n",
          "wins": "24n",
          "xp": "1250n"
        },
        "value": "100000000n",
        "walletAddress": "0x77b909b550ed11c45f1378c03c0954c0d77d320cdc938e35509564b1e505ce0d"
      }
    ],
    "viewer": {
      "rank": "17n",
      "stats": {
        "closes": "24n",
        "pnl": "42500000n",
        "tier": "4n",
        "trades": "24n",
        "volume": "1850000000000n",
        "winRateBps": "5400n",
        "winStreak": "3n",
        "wins": "24n",
        "xp": "1250n"
      },
      "value": "100000000n",
      "walletAddress": "0x77b909b550ed11c45f1378c03c0954c0d77d320cdc938e35509564b1e505ce0d"
    }
  }
}

Live trade stream (SSE)

get/trades/stream

Query parameters

afterstring
Resume after this trade id (plain decimal): every later trade, oldest first, however far back. Last-Event-ID takes precedence
Example884213

Headers

Last-Event-IDstring | null
Resume trade id sent by EventSource on reconnect; takes precedence over after
Example884213

Responses

Server-Sent Events: every trader's opens, closes and liquidations as the service indexes them. A retry: 1000 hint first. event trade: { id, action, marketId, symbol, side, owner, positionId, notional, margin, pnl, timestampMs } (n-suffixed decimal strings, USDC base units; action is open, close or liquidate; side is long, short or null; pnl is realized PnL, null on opens); id increases with every trade and is also the event's SSE id. Resuming (Last-Event-ID takes precedence over after) sends every trade past it, however far back, oldest first; a new client first gets the last 30 trades, oldest first. A cursor past the newest trade (another database) cannot be resumed: event reset {} comes first, with an empty SSE id, then the last 30 trades; drop the trades held. After the initial replay, event backfill-end: { lastId: string | null } gives the plain decimal id of the last trade sent on this connection, or null if none; it has no SSE id and does not change the resume cursor. event heartbeat: { timestampMs } every 10 s. The stream closes after about an hour (54 to 60 minutes), after 30 s of downstream backpressure, or on client disconnect; EventSource reconnects using the retry hint. Cache-Control: no-cache; X-Accel-Buffering: no.
text/event-stream
string
application/json
errorErrorObjectrequired
codestringrequired
messagestringrequired
rate_limited: too many requests from this client IP; retry after Retry-After seconds
application/json
Headers: Retry-After
errorErrorObjectrequired
codestringrequired
messagestringrequired
Bad gateway: the service is temporarily unavailable
application/json
errorErrorObjectrequired
codestringrequired
messagestringrequired
overloaded (the process has 2048 trade streams open) or stream_unavailable; Retry-After: 1
application/json
errorErrorObjectrequired
codestringrequired
messagestringrequired
Gateway timeout: the service did not answer in time
application/json
errorErrorObjectrequired
codestringrequired
messagestringrequired

Example request

curl -N 'https://api.parchment.trade/trades/stream' \
  -H 'Accept: text/event-stream'

const events = new EventSource("https://api.parchment.trade/trades/stream");
events.onmessage = (event) => console.log(JSON.parse(event.data));

Example response (200)

text/event-stream

data: "string"