Previews

Open and close previews

Preview a close

post/previews/close

Request body (required)

PreviewCloseRequest · application/json

acceptableExitWadstring | null
Format-checked only; the fill ignores it.
Pattern^-?(0|[1-9][0-9]*)n$
Example74250000000000000000n
nowMsstring | null
Unix ms the hold checks are judged at (the service defaults to its clock).
Pattern^-?(0|[1-9][0-9]*)n$
Example1796677200000n
positionIdstringrequired
Pattern^-?(0|[1-9][0-9]*)n$
Example1042n
slippageBpsstring | null
0..=10000; with it the preview returns suggested_bound_wad.
Pattern^-?(0|[1-9][0-9]*)n$
Example50n
topUpstring | null
Owner top-up added to the free balance (base units).
Pattern^-?(0|[1-9][0-9]*)n$
Example100000000n

Responses

Close preview, as public camelCase JSON. fillWad/exitWad are the oracle mid; oneStepWad (n-suffixed decimal or null) is the one-step exit price emergency close and close_retired pay (the mid moved by the one-step spread against the position); oneStepSpreadBps and emergencyAfterMs (a delay; the contract bounds it to 5000..=60000 ms, default 15000, so emergency close is never disabled) are n-suffixed decimal strings like every integer ("5000000n"; fillWindowMs/cancelDelayMs/signedWindowMs included; pnl includes builderFee and builderFeeBps). liquidationPaused (bool or null) is true only under the market's oracle kill switch (liquidate aborts trade::EOracleKilled 20 then; no pause stops liquidation), null for an unindexed market. errors includes price_unavailable when the storage price has not been read.
application/json
dataPreviewCloserequired
With the market's two-step order params (or the defaults). Without a live price the price fields, pnl, liquidatable and max_fee_bps are null, and spread_source, indicative and conf_wad are absent (one_step_spread_bps too while the market is unindexed).
cancelDelayMsstringrequired
Milliseconds.
Pattern^-?(0|[1-9][0-9]*)n$
Example30000n
confWadstring | null
Scaled by 1e18 (WAD).
Pattern^-?(0|[1-9][0-9]*)n$
Example30000000000000000n
emergencyAfterMsstringrequired
The emergency close delay in ms (5000 to 60000 on chain).
Pattern^-?(0|[1-9][0-9]*)n$
Example15000n
errorsstring[]required
Reasons the close would fail; empty when it would go through.
execFeestringrequired
Collateral base units escrowed with the request.
Pattern^-?(0|[1-9][0-9]*)n$
Example800000n
exitWadstring | null
The two-step exit: the plain mid (WAD).
Pattern^-?(0|[1-9][0-9]*)n$
Example74250000000000000000n
feeOwedstring | null
Pattern^-?(0|[1-9][0-9]*)n$
Example800000n
fillWadstring | null
Same as exit_wad.
Pattern^-?(0|[1-9][0-9]*)n$
Example74250000000000000000n
fillWindowMsstringrequired
Milliseconds.
Pattern^-?(0|[1-9][0-9]*)n$
Example60000n
indicativeboolean | null
liquidatableboolean | null
liquidationPausedboolean | null
Whether the market's oracle kill switch stops liquidation; null while unindexed.
maxFeeBpsstring | null
The effective taker fee snapshot; null without a live price.
Pattern^-?(0|[1-9][0-9]*)n$
Example8n
oneStepSpreadBpsstring | null
Basis points (1/10000).
Pattern^-?(0|[1-9][0-9]*)n$
Example5n
oneStepWadstring | null
The one-step exit price emergency close and close_retired pay: the mid moved by the one-step spread against the position (down for a long, up for a short).
Pattern^-?(0|[1-9][0-9]*)n$
Example74250000000000000000n
pnlnull | ClosePnl
adjustedstringrequired
Pattern^-?(0|[1-9][0-9]*)n$
Example42500000n
builderFeestringrequired
Pattern^-?(0|[1-9][0-9]*)n$
Example800000n
builderFeeBpsstringrequired
Basis points (1/10000).
Pattern^-?(0|[1-9][0-9]*)n$
Example8n
closeTollstringrequired
Pattern^-?(0|[1-9][0-9]*)n$
Example800000n
closeTollFromMarginstringrequired
Pattern^-?(0|[1-9][0-9]*)n$
Example100000000n
closeTollFromProfitstringrequired
Pattern^-?(0|[1-9][0-9]*)n$
Example100000000n
feesCollectedNowstringrequired
Pattern^-?(0|[1-9][0-9]*)n$
Example1850000000000n
lossstringrequired
Pattern^-?(0|[1-9][0-9]*)n$
Example100000000n
marginReturnedstringrequired
Pattern^-?(0|[1-9][0-9]*)n$
Example100000000n
netstringrequired
Pattern^-?(0|[1-9][0-9]*)n$
Example100000000n
paidNowbooleanrequired
Paid at close (queue empty and LP cash covers it).
payoutstringrequired
payout_before_refund + referee_refund.
Pattern^-?(0|[1-9][0-9]*)n$
Example100000000n
payoutBeforeRefundstringrequired
Pattern^-?(0|[1-9][0-9]*)n$
Example100000000n
queuedbooleanrequired
The profit waits in the payout queue.
rawstringrequired
Pattern^-?(0|[1-9][0-9]*)n$
Example42500000n
refereeRefundstringrequired
Pattern^-?(0|[1-9][0-9]*)n$
Example800000n
trimCPpmstringrequired
Parts per million.
Pattern^-?(0|[1-9][0-9]*)n$
Example1000n
trimMaxShareBpsstringrequired
Basis points (1/10000).
Pattern^-?(0|[1-9][0-9]*)n$
Example2000n
trimmedstringrequired
raw - adjusted: the profit trim.
Pattern^-?(0|[1-9][0-9]*)n$
Example42500000n
userProfitstringrequired
Pattern^-?(0|[1-9][0-9]*)n$
Example42500000n
winFeestringrequired
Pattern^-?(0|[1-9][0-9]*)n$
Example800000n
positionIdstringrequired
Pattern^-?(0|[1-9][0-9]*)n$
Example1042n
signedWindowMsstringrequired
Milliseconds.
Pattern^-?(0|[1-9][0-9]*)n$
Example60000n
spreadSourcenull | string
suggestedAcceptablePriceWadstring | null
The mid 0.5% against the trader; null without a live mid.
Pattern^-?(0|[1-9][0-9]*)n$
Example74250000000000000000n
suggestedBoundWadstring | null
exit_wad moved slippage_bps against the trader; null without slippage_bps.
Pattern^-?(0|[1-9][0-9]*)n$
Example74250000000000000000n
Non-object body, sponsor / txKind which this API does not implement, or a positionId / nowMs / topUp / slippageBps / acceptableExitWad of the wrong type, a JSON number or plain decimal string included: integers are n-suffixed decimal strings such as "7n" (bad_request, local, the service is not called)
application/json
errorErrorObjectrequired
codestringrequired
messagestringrequired
position_not_found: locally for a missing or null positionId, from the service for an unknown one
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 -X POST 'https://api.parchment.trade/previews/close' \
  -H 'Content-Type: application/json' \
  -d '{
  "acceptableExitWad": "74250000000000000000n",
  "nowMs": "1796677200000n",
  "positionId": "1042n",
  "slippageBps": "50n",
  "topUp": "100000000n"
}'

const res = await fetch("https://api.parchment.trade/previews/close", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    "acceptableExitWad": "74250000000000000000n",
    "nowMs": "1796677200000n",
    "positionId": "1042n",
    "slippageBps": "50n",
    "topUp": "100000000n"
  }),
});
const { data } = await res.json();

Example response (200)

application/json

{
  "data": {
    "cancelDelayMs": "30000n",
    "confWad": "30000000000000000n",
    "emergencyAfterMs": "15000n",
    "errors": [],
    "execFee": "800000n",
    "exitWad": "74250000000000000000n",
    "feeOwed": "800000n",
    "fillWad": "74250000000000000000n",
    "fillWindowMs": "60000n",
    "indicative": true,
    "liquidatable": true,
    "liquidationPaused": true,
    "maxFeeBps": "8n",
    "oneStepSpreadBps": "5n",
    "oneStepWad": "74250000000000000000n",
    "pnl": {
      "adjusted": "42500000n",
      "builderFee": "800000n",
      "builderFeeBps": "8n",
      "closeToll": "800000n",
      "closeTollFromMargin": "100000000n",
      "closeTollFromProfit": "100000000n",
      "feesCollectedNow": "1850000000000n",
      "loss": "100000000n",
      "marginReturned": "100000000n",
      "net": "100000000n",
      "paidNow": true,
      "payout": "100000000n",
      "payoutBeforeRefund": "100000000n",
      "queued": true,
      "raw": "42500000n",
      "refereeRefund": "800000n",
      "trimCPpm": "1000n",
      "trimMaxShareBps": "2000n",
      "trimmed": "42500000n",
      "userProfit": "42500000n",
      "winFee": "800000n"
    },
    "positionId": "1042n",
    "signedWindowMs": "60000n",
    "spreadSource": "floor",
    "suggestedAcceptablePriceWad": "74250000000000000000n",
    "suggestedBoundWad": "74250000000000000000n"
  }
}

Preview an open

post/previews/open

Request body (required)

PreviewOpenRequest · application/json

acceptableEntryWadstring | null
Format-checked only; the fill ignores it.
Pattern^-?(0|[1-9][0-9]*)n$
Example74250000000000000000n
accountIdstring | null
With it, the account's free balance, notional cap and referee discount are checked.
Example0xad23e722f3542ae36c276c1b303e30ae77c840a84db89c7215fa87bf92006691
isLongboolean | null
The service defaults to true (long).
leveragestringrequired
Pattern^-?(0|[1-9][0-9]*)n$
Example10n
marginstringrequired
Collateral base units, fee included.
Pattern^-?(0|[1-9][0-9]*)n$
Example100000000n
marketIdstringrequired
Example0x6e6238eb4f69bfcc3e884a7d20904eb0995ca2e42c95dc8560d5a417486ab645
minFactorBpsstring | null
Basis points (1/10000).
Pattern^-?(0|[1-9][0-9]*)n$
Example10000n
slippageBpsstring | null
0..=10000; with it the preview returns suggested_bound_wad.
Pattern^-?(0|[1-9][0-9]*)n$
Example50n
topUpstring | null
Owner top-up added to the free balance (base units).
Pattern^-?(0|[1-9][0-9]*)n$
Example100000000n

Responses

Open preview, as public camelCase JSON. fillWad/entryWad are the oracle mid (the two-step fill price); oneStepWad (n-suffixed decimal or null) is the one-step reference price (the mid moved by the one-step spread against the trader); every integer (WADs, oneStepSpreadBps, fillWindowMs, cancelDelayMs, signedWindowMs, ...) is an n-suffixed decimal string ("5000000n"). errors includes price_unavailable when the storage price has not been read. spreadSource stays floor.
application/json
dataPreviewOpenrequired
With the market's two-step order params (or the defaults). A preview stopped at its first invalid input (margin, leverage, sizing) has every sizing and price field and max_fee_bps null, and no indicative, conf_wad, taker_fee_bps nor min_payout_factor_bps.
bustWadstring | null
Scaled by 1e18 (WAD).
Pattern^-?(0|[1-9][0-9]*)n$
Example67550000000000000000n
cancelDelayMsstringrequired
Milliseconds.
Pattern^-?(0|[1-9][0-9]*)n$
Example30000n
confWadstring | null
Scaled by 1e18 (WAD).
Pattern^-?(0|[1-9][0-9]*)n$
Example30000000000000000n
entryWadstring | null
Same as fill_wad.
Pattern^-?(0|[1-9][0-9]*)n$
Example74250000000000000000n
errorsstring[]required
Reasons the open would fail; empty when it would go through.
execFeestringrequired
Collateral base units escrowed with the request.
Pattern^-?(0|[1-9][0-9]*)n$
Example800000n
factorBpsstring | null
Basis points (1/10000).
Pattern^-?(0|[1-9][0-9]*)n$
Example10000n
feestring | null
The charged open fee (after the referee discount).
Pattern^-?(0|[1-9][0-9]*)n$
Example800000n
fillWadstring | null
The two-step fill: the plain mid (WAD).
Pattern^-?(0|[1-9][0-9]*)n$
Example74250000000000000000n
fillWindowMsstringrequired
Milliseconds.
Pattern^-?(0|[1-9][0-9]*)n$
Example60000n
indicativeboolean | null
true while no fresh signed confidence is indexed (the spread is the floor only).
isLongbooleanrequired
lockedstring | null
Margin locked in the position: margin minus the charged fee, USDC base units (6 decimals).
Pattern^-?(0|[1-9][0-9]*)n$
Example100000000n
marginstring | null
Pattern^-?(0|[1-9][0-9]*)n$
Example100000000n
marketIdstringrequired
Pattern^0x[0-9a-f]{64}$
Example0x6e6238eb4f69bfcc3e884a7d20904eb0995ca2e42c95dc8560d5a417486ab645
maxFeeBpsstring | null
The effective taker fee snapshot; null on a rejected open.
Pattern^-?(0|[1-9][0-9]*)n$
Example8n
minPayoutFactorBpsstring | null
Basis points (1/10000).
Pattern^-?(0|[1-9][0-9]*)n$
Example10000n
notionalstring | null
Pattern^-?(0|[1-9][0-9]*)n$
Example1000000000n
oneStepSpreadBpsstringrequired
Basis points (1/10000).
Pattern^-?(0|[1-9][0-9]*)n$
Example5n
oneStepWadstring | null
The one-step reference price: the mid moved by the one-step spread against a long open (up) or a short open (down).
Pattern^-?(0|[1-9][0-9]*)n$
Example74250000000000000000n
signedWindowMsstringrequired
Milliseconds.
Pattern^-?(0|[1-9][0-9]*)n$
Example60000n
spreadSourcenull | string
suggestedAcceptablePriceWadstring | null
The mid 0.5% against the trader; null without a live mid.
Pattern^-?(0|[1-9][0-9]*)n$
Example74250000000000000000n
suggestedBoundWadstring | null
fill_wad moved slippage_bps against the trader; null without slippage_bps.
Pattern^-?(0|[1-9][0-9]*)n$
Example74250000000000000000n
takerFeeBpsstring | null
The effective taker fee (market fee or the global override).
Pattern^-?(0|[1-9][0-9]*)n$
Example8n
winningExposurestring | null
Pattern^-?(0|[1-9][0-9]*)n$
Example1850000000000n
Non-object body, an isLong that is present, not null and not a JSON boolean (bad_request; an omitted or null isLong is forwarded without it and the service reads it as long), sponsor / txKind which this API does not implement, a missing margin / leverage or a field of the wrong type, a JSON number or plain decimal string included: integers are n-suffixed decimal strings such as "1000000n" (bad_request, local, the service is not called), or the service's 400 for a malformed marketId / accountId. An out-of-range margin / leverage (such as "0n") is the service's 200 with an errors list.
application/json
errorErrorObjectrequired
codestringrequired
messagestringrequired
market_not_found: locally for a missing or null marketId, from the service for an unknown one
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 -X POST 'https://api.parchment.trade/previews/open' \
  -H 'Content-Type: application/json' \
  -d '{
  "acceptableEntryWad": "74250000000000000000n",
  "accountId": "0xad23e722f3542ae36c276c1b303e30ae77c840a84db89c7215fa87bf92006691",
  "isLong": true,
  "leverage": "10n",
  "margin": "100000000n",
  "marketId": "0x6e6238eb4f69bfcc3e884a7d20904eb0995ca2e42c95dc8560d5a417486ab645",
  "minFactorBps": "10000n",
  "slippageBps": "50n",
  "topUp": "100000000n"
}'

const res = await fetch("https://api.parchment.trade/previews/open", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    "acceptableEntryWad": "74250000000000000000n",
    "accountId": "0xad23e722f3542ae36c276c1b303e30ae77c840a84db89c7215fa87bf92006691",
    "isLong": true,
    "leverage": "10n",
    "margin": "100000000n",
    "marketId": "0x6e6238eb4f69bfcc3e884a7d20904eb0995ca2e42c95dc8560d5a417486ab645",
    "minFactorBps": "10000n",
    "slippageBps": "50n",
    "topUp": "100000000n"
  }),
});
const { data } = await res.json();

Example response (200)

application/json

{
  "data": {
    "bustWad": "67550000000000000000n",
    "cancelDelayMs": "30000n",
    "confWad": "30000000000000000n",
    "entryWad": "74250000000000000000n",
    "errors": [],
    "execFee": "800000n",
    "factorBps": "10000n",
    "fee": "800000n",
    "fillWad": "74250000000000000000n",
    "fillWindowMs": "60000n",
    "indicative": true,
    "isLong": true,
    "locked": "100000000n",
    "margin": "100000000n",
    "marketId": "0x6e6238eb4f69bfcc3e884a7d20904eb0995ca2e42c95dc8560d5a417486ab645",
    "maxFeeBps": "8n",
    "minPayoutFactorBps": "10000n",
    "notional": "1000000000n",
    "oneStepSpreadBps": "5n",
    "oneStepWad": "74250000000000000000n",
    "signedWindowMs": "60000n",
    "spreadSource": "floor",
    "suggestedAcceptablePriceWad": "74250000000000000000n",
    "suggestedBoundWad": "74250000000000000000n",
    "takerFeeBps": "8n",
    "winningExposure": "1850000000000n"
  }
}