Protocol

Config, protocol summary, and API limits

Config

get/config

Responses

Package ids, object ids, storage type, and feed pins, as public camelCase JSON. basePackageId(s), gamePackageId(s) and mintPackageId(s) are the split packages (original first, latest last; empty when the service does not serve them). Every integer is an n-suffixed decimal string ("5000000n"). maxPendingOrders is the admin-set per-account cap on pending two-step opens (the contract default "64n" until the service has indexed the config). Compare an account's pendingOpenOrders with maxPendingOrders before a request-open: a request-open while pendingOpenOrders >= maxPendingOrders aborts order::ETooManyOrders; closes are never capped. Older services omit it. trim is the global close-preview trim { maxShareBps, cPpm, source: indexed|default } (n-suffixed decimal strings; applies to every market; source is default until the service has indexed the config); older services omit it.
application/json
dataConfigrequired
The public service configuration.
basePackageIdstring | null
Latest base package id (null until configured). Type tags use the first of basePackageIds.
Pattern^0x[0-9a-f]{64}$
Example0x63e4c0750101534f8ac9187e6e7b1fd2d1b4e364e141dc26e0ccb60f5176de9d
basePackageIdsstring[]required
Every parchment_base version, original first.
buildersBuilderConfigrequired
createFeestringrequired
Pattern^-?(0|[1-9][0-9]*)n$
Example800000n
enabledbooleanrequired
hardCapBpsstringrequired
Basis points (1/10000).
Pattern^-?(0|[1-9][0-9]*)n$
Example2000n
maxFeeBpsstringrequired
Basis points (1/10000).
Pattern^-?(0|[1-9][0-9]*)n$
Example8n
ownerFeeLimitBpsstringrequired
Highest fee (bps of profit) a builder owner may set self-serve (self_serve_fee_cap_bps); above it is admin-only.
Pattern^-?(0|[1-9][0-9]*)n$
Example2000n
configIdstring | null
Pattern^0x[0-9a-f]{64}$
Example0xd3130ac108d621be0d73cb8f130ea4dca14f52512c4d06bf48610067098e93e1
exchangeIdstring | null
Pattern^0x[0-9a-f]{64}$
Example0x2e53756af142bc2768c9bae0d2acae16558e68ab11dc71987dbfc96e4dd40819
gamePackageIdstring | null
Latest parchment_game id; game_events and game_book types use the original id.
Pattern^0x[0-9a-f]{64}$
Example0x29a65f44f54483f8675b3b19a048e66a163977af77a7e545ddabc8d6b1a9ed71
gamePackageIdsstring[]required
gameRewardsGameRewardsrequired
achievementMintFractionBpsstringrequired
Basis points (1/10000).
Pattern^-?(0|[1-9][0-9]*)n$
Example2000n
dailyDropDailyDroprequired
Daily drop schedule.
basestringrequired
Base drop, in the drop's unit (XP), as configured on chain.
Pattern^-?(0|[1-9][0-9]*)n$
Example100000000n
maxstringrequired
Maximum drop, in the drop's unit (XP), as configured on chain.
Pattern^-?(0|[1-9][0-9]*)n$
Example100000000n
stepstringrequired
Step, in the drop's unit (XP), as configured on chain.
Pattern^-?(0|[1-9][0-9]*)n$
Example3n
streakCapstringrequired
Pattern^-?(0|[1-9][0-9]*)n$
Example3n
dailyDropUnitstringrequired
Unit of the daily drop.
One ofXP
decimalsstringrequired
PARCHMENT decimals.
Pattern^-?(0|[1-9][0-9]*)n$
Example9n
globalMintCapPerDaystringrequired
Pattern^-?(0|[1-9][0-9]*)n$
Example1500000000000n
modelstringrequired
How game rewards are issued.
One ofminted
notestringrequired
treasuryInstalledbooleanrequired
The exchange holds TreasuryCap<PARCHMENT>.
walletMintCapPerDaystringrequired
Pattern^-?(0|[1-9][0-9]*)n$
Example1500000000000n
winMintstringrequired
Pattern^-?(0|[1-9][0-9]*)n$
Example1500000000000n
graphqlUrlstringrequired
maxPendingOrdersstringrequired
The per-account pending open order cap. The service uses 64 until config is indexed; indexed admin values take precedence.
Pattern^-?(0|[1-9][0-9]*)n$
Example24n
mintPackageIdstring | null
Latest parchment_mint id; locked_mint and mint_cap types use the original id.
Pattern^0x[0-9a-f]{64}$
Example0x9556fe18f66c066edbb2f504afc2c82a1edade7d81fcd9136e529dad565f2235
mintPackageIdsstring[]required
oraclePackageIdstring | null
Pattern^0x[0-9a-f]{64}$
Example0x267f963332073dc80eb7aba86e7e47a2200dea686684c98d4bc87822465f81a9
packageIdstring | null
Pattern^0x[0-9a-f]{64}$
Example0x70fcdf24c8937202fe8fdc5b9fccfe62439ca58fdd2b7b0f077325a611261939
packageIdsstring[]required
pauseMaskstringrequired
Pause flags bitmask, one bit per pause category.
Pattern^-?(0|[1-9][0-9]*)n$
Example0n
pinsConfigPin[]required
proofTtlMsstring | null
Milliseconds.
Pattern^(0|[1-9][0-9]*)n$
Example60000n
randomIdstring | null
Pattern^0x[0-9a-f]{64}$
Example0x65068926e2b7ccdde582818e77fdc59297a7b3b4f2b8f3deb05373e411b69afd
refereeDiscountBpsstringrequired
Basis points (1/10000).
Pattern^-?(0|[1-9][0-9]*)n$
Example2000n
referralEnabledbooleanrequired
referralSourcestringrequired
Where a config value comes from.
One ofindexeddefault
registryIdstring | null
Pattern^0x[0-9a-f]{64}$
Example0x4399cf463f722e69fa1a3b4c2ef486425ad6cd388722813ab994d9548edd6205
rewardCoinTypestring | null
Example0xdba34672e30cb065b1f93e3ab55318768fd6fef66c15942c9f7cb846e2f900e7::usdc::USDC
stakingPoolIdstring | null
Pattern^0x[0-9a-f]{64}$
Example0xd49df5e14280365fd33dc1673cf6725601f811af209fd316b4a152f704ddf409
storageTypestringrequired
tokenPackageIdstring | null
Pattern^0x[0-9a-f]{64}$
Example0xd97802de3066eae5235d901ceb5fad724675c3fb0cb921dee4f047a9b0815c5d
tradePackageIdstring | null
Pattern^0x[0-9a-f]{64}$
Example0x101304235b64d3aed1b96eaffabf2768f7df54366ac9c6cb15d8934898c11ca9
tradePackageIdsstring[]required
triggerDelegatestring | null
Pattern^0x[0-9a-f]{64}$
Example0x77b909b550ed11c45f1378c03c0954c0d77d320cdc938e35509564b1e505ce0d
triggersLiveboolean | null
triggersPackageIdstring | null
Latest parchment_triggers id (on-chain TP/SL commitment calls), omitted until deployed; from the service's split-packages route.
Pattern^0x[0-9a-f]{64}$
Example0xfd69a144c9ae4dc7a492a80dcec01f16a27aecb4cfc7580efb9bac24e77d65e9
triggersPackageIdsstring[]
trimConfigTrimrequired
Live profit-trim knobs, global to every market.
usdcTypestringrequired
Example0xdba34672e30cb065b1f93e3ab55318768fd6fef66c15942c9f7cb846e2f900e7::usdc::USDC
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/config'

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

Example response (200)

application/json

{
  "data": {
    "basePackageId": "0x63e4c0750101534f8ac9187e6e7b1fd2d1b4e364e141dc26e0ccb60f5176de9d",
    "basePackageIds": [
      "0x63e4c0750101534f8ac9187e6e7b1fd2d1b4e364e141dc26e0ccb60f5176de9d"
    ],
    "builders": {
      "createFee": "800000n",
      "enabled": true,
      "hardCapBps": "2000n",
      "maxFeeBps": "8n",
      "ownerFeeLimitBps": "2000n"
    },
    "configId": "0xd3130ac108d621be0d73cb8f130ea4dca14f52512c4d06bf48610067098e93e1",
    "exchangeId": "0x2e53756af142bc2768c9bae0d2acae16558e68ab11dc71987dbfc96e4dd40819",
    "gamePackageId": "0x29a65f44f54483f8675b3b19a048e66a163977af77a7e545ddabc8d6b1a9ed71",
    "gamePackageIds": [
      "0x29a65f44f54483f8675b3b19a048e66a163977af77a7e545ddabc8d6b1a9ed71"
    ],
    "gameRewards": {
      "achievementMintFractionBps": "2000n",
      "dailyDrop": {
        "base": "100000000n",
        "max": "100000000n",
        "step": "3n",
        "streakCap": "3n"
      },
      "dailyDropUnit": "XP",
      "decimals": "9n",
      "globalMintCapPerDay": "1500000000000n",
      "model": "minted",
      "note": "string",
      "treasuryInstalled": true,
      "walletMintCapPerDay": "1500000000000n",
      "winMint": "1500000000000n"
    },
    "graphqlUrl": "string",
    "maxPendingOrders": "24n",
    "mintPackageId": "0x9556fe18f66c066edbb2f504afc2c82a1edade7d81fcd9136e529dad565f2235",
    "mintPackageIds": [
      "0x9556fe18f66c066edbb2f504afc2c82a1edade7d81fcd9136e529dad565f2235"
    ],
    "oraclePackageId": "0x267f963332073dc80eb7aba86e7e47a2200dea686684c98d4bc87822465f81a9",
    "packageId": "0x70fcdf24c8937202fe8fdc5b9fccfe62439ca58fdd2b7b0f077325a611261939",
    "packageIds": [
      "0x70fcdf24c8937202fe8fdc5b9fccfe62439ca58fdd2b7b0f077325a611261939"
    ],
    "pauseMask": "0n",
    "pins": [
      {
        "lazerFeedId": "1398n",
        "sourceId": "2n",
        "storageId": "0x36d5377cee4c4a61087f999a9c137472ab8daa75ce225ec82d9e5f4ac1fb12bd",
        "symbol": "WTI"
      }
    ],
    "proofTtlMs": "60000n",
    "randomId": "0x65068926e2b7ccdde582818e77fdc59297a7b3b4f2b8f3deb05373e411b69afd",
    "refereeDiscountBps": "2000n",
    "referralEnabled": true,
    "referralSource": "indexed",
    "registryId": "0x4399cf463f722e69fa1a3b4c2ef486425ad6cd388722813ab994d9548edd6205",
    "rewardCoinType": "0xdba34672e30cb065b1f93e3ab55318768fd6fef66c15942c9f7cb846e2f900e7::usdc::USDC",
    "stakingPoolId": "0xd49df5e14280365fd33dc1673cf6725601f811af209fd316b4a152f704ddf409",
    "storageType": "string",
    "tokenPackageId": "0xd97802de3066eae5235d901ceb5fad724675c3fb0cb921dee4f047a9b0815c5d",
    "tradePackageId": "0x101304235b64d3aed1b96eaffabf2768f7df54366ac9c6cb15d8934898c11ca9",
    "tradePackageIds": [
      "0x101304235b64d3aed1b96eaffabf2768f7df54366ac9c6cb15d8934898c11ca9"
    ],
    "triggerDelegate": "0x77b909b550ed11c45f1378c03c0954c0d77d320cdc938e35509564b1e505ce0d",
    "triggersLive": true,
    "triggersPackageId": "0xfd69a144c9ae4dc7a492a80dcec01f16a27aecb4cfc7580efb9bac24e77d65e9",
    "triggersPackageIds": [
      "0xfd69a144c9ae4dc7a492a80dcec01f16a27aecb4cfc7580efb9bac24e77d65e9"
    ],
    "trim": {
      "cPpm": "1000n",
      "maxShareBps": "2000n",
      "source": "indexed"
    },
    "usdcType": "0xdba34672e30cb065b1f93e3ab55318768fd6fef66c15942c9f7cb846e2f900e7::usdc::USDC"
  }
}

API limits

get/limits

Responses

Limits this API preserves. Settlement prices come only from the pinned on-chain price storage.
application/json
dataLimitsrequired
incomingTxKindstringrequired
moveAbortCatalogstringrequired
orderBookstringrequired
orderTxNotestringrequired
priceFeedStorageGetterstringrequired
priceUnavailablestringrequired
referralBonusesstringrequired
referralEstimatestringrequired
signedAuthstringrequired
sponsorstringrequired
Pattern^0x[0-9a-f]{64}$
Example0x77b909b550ed11c45f1378c03c0954c0d77d320cdc938e35509564b1e505ce0d
tradeTransactionsstringrequired
tradeTxNotestringrequired
rate_limited: too many requests from this client IP; retry after Retry-After seconds
application/json
Headers: Retry-After
errorErrorObjectrequired
codestringrequired
messagestringrequired

Example request

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

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

Example response (200)

application/json

{
  "data": {
    "incomingTxKind": "string",
    "moveAbortCatalog": "string",
    "orderBook": "string",
    "orderTxNote": "string",
    "priceFeedStorageGetter": "string",
    "priceUnavailable": "string",
    "referralBonuses": "string",
    "referralEstimate": "string",
    "signedAuth": "string",
    "sponsor": "0x77b909b550ed11c45f1378c03c0954c0d77d320cdc938e35509564b1e505ce0d",
    "tradeTransactions": "string",
    "tradeTxNote": "string"
  }
}

LP payout queue

get/lp/queue

Responses

LP vault payout queue: length, total owed, LP cash, head and claims.
application/json
dataLpQueuerequired
claimsClaim[]required
The first queued claims in FIFO order, at most 200.
accountIdstring | null
Pattern^0x[0-9a-f]{64}$
Example0xad23e722f3542ae36c276c1b303e30ae77c840a84db89c7215fa87bf92006691
claimIdstringrequired
Pattern^-?(0|[1-9][0-9]*)n$
Example5531n
enqueuedTxstring | null
feeRemainingstring | null
Protocol fee still queued with the claim, once its queue node is indexed.
Pattern^-?(0|[1-9][0-9]*)n$
Example800000n
harvestedTxstring | null
netstringrequired
Pattern^-?(0|[1-9][0-9]*)n$
Example100000000n
onTopRemainingstring | null
Builder on-top fee still queued with the claim.
Pattern^-?(0|[1-9][0-9]*)n$
Example800000n
ownerstring | null
Pattern^0x[0-9a-f]{64}$
Example0x77b909b550ed11c45f1378c03c0954c0d77d320cdc938e35509564b1e505ce0d
positionIdstring | null
null until the close that queued it is indexed.
Pattern^-?(0|[1-9][0-9]*)n$
Example1042n
remainingstringrequired
Net still owed (net until partly paid).
Pattern^-?(0|[1-9][0-9]*)n$
Example100000000n
statusstringrequired
One ofqueuedharvested
timestampMsstring | null
Milliseconds.
Pattern^-?(0|[1-9][0-9]*)n$
Example1796677200000n
headnull | Claim
accountIdstring | null
Pattern^0x[0-9a-f]{64}$
Example0xad23e722f3542ae36c276c1b303e30ae77c840a84db89c7215fa87bf92006691
claimIdstringrequired
Pattern^-?(0|[1-9][0-9]*)n$
Example5531n
enqueuedTxstring | null
feeRemainingstring | null
Protocol fee still queued with the claim, once its queue node is indexed.
Pattern^-?(0|[1-9][0-9]*)n$
Example800000n
harvestedTxstring | null
netstringrequired
Pattern^-?(0|[1-9][0-9]*)n$
Example100000000n
onTopRemainingstring | null
Builder on-top fee still queued with the claim.
Pattern^-?(0|[1-9][0-9]*)n$
Example800000n
ownerstring | null
Pattern^0x[0-9a-f]{64}$
Example0x77b909b550ed11c45f1378c03c0954c0d77d320cdc938e35509564b1e505ce0d
positionIdstring | null
null until the close that queued it is indexed.
Pattern^-?(0|[1-9][0-9]*)n$
Example1042n
remainingstringrequired
Net still owed (net until partly paid).
Pattern^-?(0|[1-9][0-9]*)n$
Example100000000n
statusstringrequired
One ofqueuedharvested
timestampMsstring | null
Milliseconds.
Pattern^-?(0|[1-9][0-9]*)n$
Example1796677200000n
lpCashstring | null
Pattern^-?(0|[1-9][0-9]*)n$
Example1850000000000n
queueLengthstringrequired
Pattern^-?(0|[1-9][0-9]*)n$
Example24n
totalOwedstringrequired
Pattern^-?(0|[1-9][0-9]*)n$
Example1850000000000n
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/lp/queue'

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

Example response (200)

application/json

{
  "data": {
    "claims": [
      {
        "accountId": "0xad23e722f3542ae36c276c1b303e30ae77c840a84db89c7215fa87bf92006691",
        "claimId": "5531n",
        "enqueuedTx": "string",
        "feeRemaining": "800000n",
        "harvestedTx": "string",
        "net": "100000000n",
        "onTopRemaining": "800000n",
        "owner": "0x77b909b550ed11c45f1378c03c0954c0d77d320cdc938e35509564b1e505ce0d",
        "positionId": "1042n",
        "remaining": "100000000n",
        "status": "queued",
        "timestampMs": "1796677200000n"
      }
    ],
    "head": {
      "accountId": "0xad23e722f3542ae36c276c1b303e30ae77c840a84db89c7215fa87bf92006691",
      "claimId": "5531n",
      "enqueuedTx": "string",
      "feeRemaining": "800000n",
      "harvestedTx": "string",
      "net": "100000000n",
      "onTopRemaining": "800000n",
      "owner": "0x77b909b550ed11c45f1378c03c0954c0d77d320cdc938e35509564b1e505ce0d",
      "positionId": "1042n",
      "remaining": "100000000n",
      "status": "queued",
      "timestampMs": "1796677200000n"
    },
    "lpCash": "1850000000000n",
    "queueLength": "24n",
    "totalOwed": "1850000000000n"
  }
}

OpenAPI document

get/openapi.json

Responses

application/json
object
rate_limited: too many requests from this client IP; retry after Retry-After seconds
application/json
Headers: Retry-After
errorErrorObjectrequired
codestringrequired
messagestringrequired

Example request

curl 'https://api.parchment.trade/openapi.json'

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

Example response (200)

application/json

{}

Recent positions

get/positions/recent

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.
Pattern^(0|[1-9][0-9]*)$
Example50

Responses

Recent opens, closes and liquidations (ticker). Opens carry entryWad; closes and liquidations carry exitWad. priceWad is the relevant one. limit (canonical decimal, 1 to 18446744073709551615) is forwarded when present; an empty limit is omitted.
application/json
dataRecentPositionsrequired
Newest first.
entriesRecentTrade[]required
atMsstringrequired
Milliseconds.
Pattern^-?(0|[1-9][0-9]*)n$
Example1796677200000n
entryWadstring | null
Scaled by 1e18 (WAD).
Pattern^-?(0|[1-9][0-9]*)n$
Example74250000000000000000n
exitWadstring | null
Scaled by 1e18 (WAD).
Pattern^-?(0|[1-9][0-9]*)n$
Example74250000000000000000n
isLongboolean | null
kindstringrequired
A trade activity kind.
One ofopencloseliquidate
leveragestring | null
Pattern^-?(0|[1-9][0-9]*)n$
Example10n
marginstring | null
Pattern^-?(0|[1-9][0-9]*)n$
Example100000000n
marketIdstring | null
Pattern^0x[0-9a-f]{64}$
Example0x6e6238eb4f69bfcc3e884a7d20904eb0995ca2e42c95dc8560d5a417486ab645
notionalstring | null
Pattern^-?(0|[1-9][0-9]*)n$
Example1000000000n
positionIdstring | null
Pattern^-?(0|[1-9][0-9]*)n$
Example1042n
priceWadstring | null
entry_wad for an open, exit_wad otherwise.
Pattern^-?(0|[1-9][0-9]*)n$
Example74250000000000000000n
sidenull | string
symbolstring | null
ExampleWTI
txDigeststringrequired
Pattern^[1-9A-HJ-NP-Za-km-z]{32,44}$
Examplec3CE1sYJ2ufo1E8wNhVahkJbu66F4tMxpTXLeW3o8QSA
walletAddressstringrequired
Pattern^0x[0-9a-f]{64}$
Example0x77b909b550ed11c45f1378c03c0954c0d77d320cdc938e35509564b1e505ce0d
limit is not a canonical positive integer up to 18446744073709551615 (bad_request; "0007", "+7", " 7" included)
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/positions/recent'

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

Example response (200)

application/json

{
  "data": {
    "entries": [
      {
        "atMs": "1796677200000n",
        "entryWad": "74250000000000000000n",
        "exitWad": "74250000000000000000n",
        "isLong": true,
        "kind": "open",
        "leverage": "10n",
        "margin": "100000000n",
        "marketId": "0x6e6238eb4f69bfcc3e884a7d20904eb0995ca2e42c95dc8560d5a417486ab645",
        "notional": "1000000000n",
        "positionId": "1042n",
        "priceWad": "74250000000000000000n",
        "side": "long",
        "symbol": "WTI",
        "txDigest": "c3CE1sYJ2ufo1E8wNhVahkJbu66F4tMxpTXLeW3o8QSA",
        "walletAddress": "0x77b909b550ed11c45f1378c03c0954c0d77d320cdc938e35509564b1e505ce0d"
      }
    ]
  }
}

Protocol summary

get/protocol

Responses

application/json
dataProtocolrequired
closesPausedbooleanrequired
Global close pause, as indexed.
equitystring | null
Pattern^-?(0|[1-9][0-9]*)n$
Example1850000000000n
lpCashstring | null
Pattern^-?(0|[1-9][0-9]*)n$
Example1850000000000n
openNotionalstringrequired
Pattern^-?(0|[1-9][0-9]*)n$
Example1850000000000n
openPositionsstringrequired
Pattern^-?(0|[1-9][0-9]*)n$
Example24n
pausedboolean | null
queueLengthstringrequired
Pattern^-?(0|[1-9][0-9]*)n$
Example24n
volumeNotionalstringrequired
Sum of the notional of every open.
Pattern^-?(0|[1-9][0-9]*)n$
Example1000000000n
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/protocol'

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

Example response (200)

application/json

{
  "data": {
    "closesPaused": true,
    "equity": "1850000000000n",
    "lpCash": "1850000000000n",
    "openNotional": "1850000000000n",
    "openPositions": "24n",
    "paused": true,
    "queueLength": "24n",
    "volumeNotional": "1000000000n"
  }
}