Accounts

Accounts, open positions, and history

Account overview

get/accounts/{owner}

Path parameters

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

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. The service clamps it to api.max-page-limit.
Pattern^(0|[1-9][0-9]*)$
Example50
accountsCursorstring
Account id cursor (address) from accountsNextCursor.
Example0x77b909b550ed11c45f1378c03c0954c0d77d320cdc938e35509564b1e505ce0d
positionsCursorstring
Position id cursor (decimal).
Example1042
claimsCursorstring
Claim id cursor (decimal).
Example5531

Responses

Accounts, free balance, open positions, and queue rank, as public camelCase JSON. Every integer is an n-suffixed decimal string ("5000000n"). Each account carries pendingOrders (requested, not yet finalized two-step orders, opens and closes) and pendingOpenOrders (the pending opens only). Compare pendingOpenOrders with /config maxPendingOrders before a request-open; closes are never capped. limit, accountsCursor, positionsCursor and claimsCursor are forwarded when present.
application/json
dataAccountOverviewrequired
Accounts, open positions and queued claims of a wallet, each paged with its own cursor.
accountsAccount[]required
accountIdstringrequired
Pattern^0x[0-9a-f]{64}$
Example0xad23e722f3542ae36c276c1b303e30ae77c840a84db89c7215fa87bf92006691
closeDelegatesstring[] | null
delegatesDelegate[]required
The first delegates by address, at most the page limit.
delegatesCountstringrequired
Every delegate of the account.
Pattern^-?(0|[1-9][0-9]*)n$
Example24n
exchangeIdstring | null
Pattern^0x[0-9a-f]{64}$
Example0x2e53756af142bc2768c9bae0d2acae16558e68ab11dc71987dbfc96e4dd40819
freestringrequired
Free collateral (base units).
Pattern^-?(0|[1-9][0-9]*)n$
Example100000000n
noncestring | null
Pattern^-?(0|[1-9][0-9]*)n$
Example3n
openNotionalstringrequired
Pattern^-?(0|[1-9][0-9]*)n$
Example1850000000000n
openerstring | null
Immutable address used to derive this account, even after transfer.
Pattern^0x[0-9a-f]{64}$
Example0x77b909b550ed11c45f1378c03c0954c0d77d320cdc938e35509564b1e505ce0d
ownerstringrequired
Pattern^0x[0-9a-f]{64}$
Example0x77b909b550ed11c45f1378c03c0954c0d77d320cdc938e35509564b1e505ce0d
pendingMintstringrequired
Upper-bound estimate of the PARCHMENT raw units the basis mints at the current H (the remaining-supply clamp is not applied).
Pattern^-?(0|[1-9][0-9]*)n$
Example1500000000000n
pendingMintBasisstringrequired
USDC fee basis claimable with the claim-pending-mint tx.
Pattern^-?(0|[1-9][0-9]*)n$
Example42500000n
pendingOpenOrdersstringrequired
Pending opens only, the ones capped by the config's max_pending_orders.
Pattern^-?(0|[1-9][0-9]*)n$
Example24n
pendingOrdersstringrequired
Pending requests (opens and closes).
Pattern^-?(0|[1-9][0-9]*)n$
Example24n
accountsNextCursorstring | null
nextAccountNoncestringrequired
Pattern^-?(0|[1-9][0-9]*)n$
Example3n
ownerstringrequired
Pattern^0x[0-9a-f]{64}$
Example0x77b909b550ed11c45f1378c03c0954c0d77d320cdc938e35509564b1e505ce0d
positionsPosition[]required
accountIdstring | null
Pattern^0x[0-9a-f]{64}$
Example0xad23e722f3542ae36c276c1b303e30ae77c840a84db89c7215fa87bf92006691
attributionstringrequired
Who sent a position's open.
One ofownerdelegateunindexed_account
autoCloseAtMsstring | null
Open positions on equity markets: when the session force close settles it.
Pattern^-?(0|[1-9][0-9]*)n$
Example1796677200000n
bustWadstring | null
Scaled by 1e18 (WAD).
Pattern^-?(0|[1-9][0-9]*)n$
Example67550000000000000000n
closeFeePpmstring | null
Parts per million.
Pattern^-?(0|[1-9][0-9]*)n$
Example500n
confWadstring | null
Scaled by 1e18 (WAD).
Pattern^-?(0|[1-9][0-9]*)n$
Example30000000000000000n
deadbandPpmstring | null
Parts per million.
Pattern^-?(0|[1-9][0-9]*)n$
Example1000n
entryWadstring | null
Scaled by 1e18 (WAD).
Pattern^-?(0|[1-9][0-9]*)n$
Example74250000000000000000n
exitKindnull | string
factorBpsstring | null
Basis points (1/10000).
Pattern^-?(0|[1-9][0-9]*)n$
Example10000n
fillBustWadstring | null
Liquidation price at the fill, not the requested stop-loss price.
Pattern^-?(0|[1-9][0-9]*)n$
Example67550000000000000000n
isLongbooleanrequired
leveragestring | null
notional / margin.
Pattern^-?(0|[1-9][0-9]*)n$
Example10n
marginstring | null
Pattern^-?(0|[1-9][0-9]*)n$
Example100000000n
marketIdstringrequired
Pattern^0x[0-9a-f]{64}$
Example0x6e6238eb4f69bfcc3e884a7d20904eb0995ca2e42c95dc8560d5a417486ab645
midWadstring | null
Scaled by 1e18 (WAD).
Pattern^-?(0|[1-9][0-9]*)n$
Example74250000000000000000n
notionalstring | null
Pattern^-?(0|[1-9][0-9]*)n$
Example1000000000n
openTxstring | null
openedAtMsstring | null
Milliseconds.
Pattern^-?(0|[1-9][0-9]*)n$
Example1796677200000n
ownerstringrequired
Pattern^0x[0-9a-f]{64}$
Example0x77b909b550ed11c45f1378c03c0954c0d77d320cdc938e35509564b1e505ce0d
positionIdstringrequired
Pattern^-?(0|[1-9][0-9]*)n$
Example1042n
slDroppedReasonstring | null
Service-recorded stop-loss drop reason, independent of the current trigger legs.
statusstringrequired
One ofopenclosedliquidated
stopLossWadstring | null
Scaled by 1e18 (WAD).
Pattern^(0|[1-9][0-9]*)n$
Example71500000000000000000n
takeProfitWadstring | null
Scaled by 1e18 (WAD).
Pattern^(0|[1-9][0-9]*)n$
Example78000000000000000000n
traderstringrequired
Sender of the open.
Pattern^0x[0-9a-f]{64}$
Example0x77b909b550ed11c45f1378c03c0954c0d77d320cdc938e35509564b1e505ce0d
triggersnull | TriggerView
accountIdstringrequired
Owning account.
Pattern^0x[0-9a-f]{64}$
Example0xad23e722f3542ae36c276c1b303e30ae77c840a84db89c7215fa87bf92006691
firingboolean | null
A signed close may still execute; edits are fenced until resolved.
firingEtaMsstring | null
Best known end of the epoch validity window, Unix ms; absent if unavailable.
Pattern^(0|[1-9][0-9]*)n$
Example1796677200000n
firingKindstring | null
Leg currently submitting, tp or sl.
firingMaxEpochstring | null
Last epoch in which the saved close may execute; resolved when chain epoch exceeds it.
Pattern^(0|[1-9][0-9]*)n$
Example912n
isLongbooleanrequired
Position direction.
marketIdstringrequired
Market for both legs.
Pattern^0x[0-9a-f]{64}$
Example0x6e6238eb4f69bfcc3e884a7d20904eb0995ca2e42c95dc8560d5a417486ab645
ownerstringrequired
Wallet owner.
Pattern^0x[0-9a-f]{64}$
Example0x77b909b550ed11c45f1378c03c0954c0d77d320cdc938e35509564b1e505ce0d
pausedboolean | null
Missing close grant pauses evaluation while retaining the legs.
positionIdstring | null
Position once the open attaches.
Pattern^(0|[1-9][0-9]*)n$
Example1042n
statusstringrequired
pending, attached, armed, idle, firing, submitted, fired, closed or void.
One ofpendingattachedarmedidlefiringsubmittedfiredclosedvoid
stopLossDroppednull | StopLossDropped
stopLossWadstring | null
Armed SL WAD.
Pattern^(0|[1-9][0-9]*)n$
Example71500000000000000000n
takeProfitWadstring | null
Armed TP WAD.
Pattern^(0|[1-9][0-9]*)n$
Example78000000000000000000n
voidReasonstring | null
Terminal reason for a recent void open intent.
winFeeBpsstring | null
Basis points (1/10000).
Pattern^-?(0|[1-9][0-9]*)n$
Example2000n
winningExposurestring | null
Pattern^-?(0|[1-9][0-9]*)n$
Example1850000000000n
positionsNextCursorstring | null
queueAccountClaimsrequired
The queued claims of a wallet and what is ahead of its first one.
aheadCountstringrequired
Queued claims before the wallet's first one (the whole queue without one).
Pattern^-?(0|[1-9][0-9]*)n$
Example17n
aheadNetstringrequired
Net plus fee still owed on those claims (base units).
Pattern^-?(0|[1-9][0-9]*)n$
Example100000000n
claimsClaim[]required
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
claimsNextCursorstring | null
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/accounts/0x77b909b550ed11c45f1378c03c0954c0d77d320cdc938e35509564b1e505ce0d'

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

Example response (200)

application/json

{
  "data": {
    "accounts": [
      {
        "accountId": "0xad23e722f3542ae36c276c1b303e30ae77c840a84db89c7215fa87bf92006691",
        "closeDelegates": [],
        "delegates": [
          {
            "delegate": "0x77b909b550ed11c45f1378c03c0954c0d77d320cdc938e35509564b1e505ce0d",
            "expiryMs": "1796677200000n"
          }
        ],
        "delegatesCount": "24n",
        "exchangeId": "0x2e53756af142bc2768c9bae0d2acae16558e68ab11dc71987dbfc96e4dd40819",
        "free": "100000000n",
        "nonce": "3n",
        "openNotional": "1850000000000n",
        "opener": "0x77b909b550ed11c45f1378c03c0954c0d77d320cdc938e35509564b1e505ce0d",
        "owner": "0x77b909b550ed11c45f1378c03c0954c0d77d320cdc938e35509564b1e505ce0d",
        "pendingMint": "1500000000000n",
        "pendingMintBasis": "42500000n",
        "pendingOpenOrders": "24n",
        "pendingOrders": "24n"
      }
    ],
    "accountsNextCursor": "string",
    "nextAccountNonce": "3n",
    "owner": "0x77b909b550ed11c45f1378c03c0954c0d77d320cdc938e35509564b1e505ce0d",
    "positions": [
      {
        "accountId": "0xad23e722f3542ae36c276c1b303e30ae77c840a84db89c7215fa87bf92006691",
        "attribution": "owner",
        "autoCloseAtMs": "1796677200000n",
        "bustWad": "67550000000000000000n",
        "closeFeePpm": "500n",
        "confWad": "30000000000000000n",
        "deadbandPpm": "1000n",
        "entryWad": "74250000000000000000n",
        "exitKind": "close",
        "factorBps": "10000n",
        "fillBustWad": "67550000000000000000n",
        "isLong": true,
        "leverage": "10n",
        "margin": "100000000n",
        "marketId": "0x6e6238eb4f69bfcc3e884a7d20904eb0995ca2e42c95dc8560d5a417486ab645",
        "midWad": "74250000000000000000n",
        "notional": "1000000000n",
        "openTx": "string",
        "openedAtMs": "1796677200000n",
        "owner": "0x77b909b550ed11c45f1378c03c0954c0d77d320cdc938e35509564b1e505ce0d",
        "positionId": "1042n",
        "slDroppedReason": "string",
        "status": "open",
        "stopLossWad": "71500000000000000000n",
        "takeProfitWad": "78000000000000000000n",
        "trader": "0x77b909b550ed11c45f1378c03c0954c0d77d320cdc938e35509564b1e505ce0d",
        "triggers": {
          "accountId": "0xad23e722f3542ae36c276c1b303e30ae77c840a84db89c7215fa87bf92006691",
          "firing": true,
          "firingEtaMs": "1796677200000n",
          "firingKind": "string",
          "firingMaxEpoch": "912n",
          "isLong": true,
          "marketId": "0x6e6238eb4f69bfcc3e884a7d20904eb0995ca2e42c95dc8560d5a417486ab645",
          "owner": "0x77b909b550ed11c45f1378c03c0954c0d77d320cdc938e35509564b1e505ce0d",
          "paused": true,
          "positionId": "1042n",
          "status": "pending",
          "stopLossDropped": {
            "ms": "1796677200000n",
            "reason": "string",
            "wad": "74250000000000000000n"
          },
          "stopLossWad": "71500000000000000000n",
          "takeProfitWad": "78000000000000000000n",
          "voidReason": "string"
        },
        "winFeeBps": "2000n",
        "winningExposure": "1850000000000n"
      }
    ],
    "positionsNextCursor": "string",
    "queue": {
      "aheadCount": "17n",
      "aheadNet": "100000000n",
      "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"
        }
      ],
      "claimsNextCursor": "string"
    }
  }
}

Account equity history

get/accounts/{owner}/equity

Path parameters

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

Query parameters

rangestringrequired
Required. 24h, 7d, 30d or all; anything else (missing or empty included) is 400 bad_request.
One of24h7d30dall

Responses

The owner's account equity over time from hourly snapshots (the hour's latest observation; an account with no open position gets a row only when its equity changed), plus current: the equity now from one read (null without an account or position, or while the indexer lags). Equity = free balance + open positions' margin + unrealized PnL, summed over the owner's trading accounts; a position's margin + unrealized PnL is what closing it at the indexed oracle mid would pay after fees (without a fresh price, its margin, counted in unpricedPositions). Queued payouts and wallet USDC are not included. History starts when the service began recording. Every integer is an n-suffixed decimal string; unrealizedPnl may be negative.
application/json
dataEquityHistoryrequired
The owner's hourly equity snapshots for the range and the equity now. Equity = free balance + open positions' margin + unrealized PnL (what closing each at the indexed oracle mid would pay after fees; without a fresh price, at its margin), summed over the owner's trading accounts. USDC base units (6 decimals).
bucketMsstringrequired
Snapshot spacing (one row per hour, the hour's latest observation).
Pattern^-?(0|[1-9][0-9]*)n$
Example3600000n
currentnull | EquityPointrequired
equitystringrequired
Pattern^-?(0|[1-9][0-9]*)n$
Example1850000000000n
freestringrequired
Pattern^-?(0|[1-9][0-9]*)n$
Example100000000n
marginstringrequired
Pattern^-?(0|[1-9][0-9]*)n$
Example100000000n
openPositionsstringrequired
Pattern^-?(0|[1-9][0-9]*)n$
Example1n
tsMsstringrequired
Milliseconds.
Pattern^-?(0|[1-9][0-9]*)n$
Example1796677200000n
unpricedPositionsstringrequired
Positions without a fresh price, counted at their margin.
Pattern^-?(0|[1-9][0-9]*)n$
Example0n
unrealizedPnlstringrequired
Negative while the open positions are under water.
Pattern^-?(0|[1-9][0-9]*)n$
Example-12500000n
fromMsstring | nullrequired
The window start; null for all.
Pattern^-?(0|[1-9][0-9]*)n$
Example1796677200000n
pointsEquityPoint[]required
Oldest first, at most 500; the first is the last snapshot at or before fromMs.
equitystringrequired
Pattern^-?(0|[1-9][0-9]*)n$
Example1850000000000n
freestringrequired
Pattern^-?(0|[1-9][0-9]*)n$
Example100000000n
marginstringrequired
Pattern^-?(0|[1-9][0-9]*)n$
Example100000000n
openPositionsstringrequired
Pattern^-?(0|[1-9][0-9]*)n$
Example1n
tsMsstringrequired
Milliseconds.
Pattern^-?(0|[1-9][0-9]*)n$
Example1796677200000n
unpricedPositionsstringrequired
Positions without a fresh price, counted at their margin.
Pattern^-?(0|[1-9][0-9]*)n$
Example0n
unrealizedPnlstringrequired
Negative while the open positions are under water.
Pattern^-?(0|[1-9][0-9]*)n$
Example-12500000n
rangestringrequired
"24h", "7d", "30d" or "all", as requested.
One of24h7d30dall
toMsstringrequired
The request time.
Pattern^-?(0|[1-9][0-9]*)n$
Example1796677200000n
application/json
errorErrorObjectrequired
codestringrequired
messagestringrequired
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/accounts/0x77b909b550ed11c45f1378c03c0954c0d77d320cdc938e35509564b1e505ce0d/equity?range=24h'

const res = await fetch("https://api.parchment.trade/accounts/0x77b909b550ed11c45f1378c03c0954c0d77d320cdc938e35509564b1e505ce0d/equity?range=24h");
const { data } = await res.json();

Example response (200)

application/json

{
  "data": {
    "bucketMs": "3600000n",
    "current": {
      "equity": "1850000000000n",
      "free": "100000000n",
      "margin": "100000000n",
      "openPositions": "1n",
      "tsMs": "1796677200000n",
      "unpricedPositions": "0n",
      "unrealizedPnl": "-12500000n"
    },
    "fromMs": "1796677200000n",
    "points": [
      {
        "equity": "1850000000000n",
        "free": "100000000n",
        "margin": "100000000n",
        "openPositions": "1n",
        "tsMs": "1796677200000n",
        "unpricedPositions": "0n",
        "unrealizedPnl": "-12500000n"
      }
    ],
    "range": "7d",
    "toMs": "1796677200000n"
  }
}

Account history

get/accounts/{owner}/history

Path parameters

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

Query parameters

cursorstring
Example0xc00d9a508112ec1dff7df53f35f096e26af4ec600dc291264b483d27aeb18b75
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

Deposits, withdrawals, opens, closes, and liquidations. A position closed by the equity session force close has exitKind session.
application/json
dataHistoryPagerequired
Newest first.
itemsHistoryItem[]required
accountIdstring | null
Pattern^0x[0-9a-f]{64}$
Example0xad23e722f3542ae36c276c1b303e30ae77c840a84db89c7215fa87bf92006691
idstringrequired
Pattern^-?(0|[1-9][0-9]*)n$
Example7n
marketIdstring | null
Pattern^0x[0-9a-f]{64}$
Example0x6e6238eb4f69bfcc3e884a7d20904eb0995ca2e42c95dc8560d5a417486ab645
openStopLossWadstring | null
Stop-loss level open at the time, when available; absent when the service omits it.
Pattern^(0|[1-9][0-9]*)n$
Example71500000000000000000n
openTakeProfitWadstring | null
Take-profit level open at the time, when available; absent when the service omits it.
Pattern^(0|[1-9][0-9]*)n$
Example78000000000000000000n
positionIdstring | null
Pattern^-?(0|[1-9][0-9]*)n$
Example1042n
timestampMsstringrequired
Milliseconds.
Pattern^-?(0|[1-9][0-9]*)n$
Example1796677200000n
triggerFiredAtMsstring | null
Time the trigger fired, when available; absent when the service omits it.
Pattern^(0|[1-9][0-9]*)n$
Example1796677200000n
triggerKindstring | null
triggerPriceWadstring | null
Scaled by 1e18 (WAD).
Pattern^(0|[1-9][0-9]*)n$
Example74250000000000000000n
txDigeststringrequired
Pattern^[1-9A-HJ-NP-Za-km-z]{32,44}$
Examplec3CE1sYJ2ufo1E8wNhVahkJbu66F4tMxpTXLeW3o8QSA
nextCursorstring | null
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/accounts/0x77b909b550ed11c45f1378c03c0954c0d77d320cdc938e35509564b1e505ce0d/history'

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

Example response (200)

application/json

{
  "data": {
    "items": [
      {
        "kind": "deposit",
        "payload": {
          "amount": "100000000n"
        },
        "accountId": "0xad23e722f3542ae36c276c1b303e30ae77c840a84db89c7215fa87bf92006691",
        "id": "7n",
        "marketId": "0x6e6238eb4f69bfcc3e884a7d20904eb0995ca2e42c95dc8560d5a417486ab645",
        "openStopLossWad": "71500000000000000000n",
        "openTakeProfitWad": "78000000000000000000n",
        "positionId": "1042n",
        "timestampMs": "1796677200000n",
        "triggerFiredAtMs": "1796677200000n",
        "triggerKind": "string",
        "triggerPriceWad": "74250000000000000000n",
        "txDigest": "c3CE1sYJ2ufo1E8wNhVahkJbu66F4tMxpTXLeW3o8QSA"
      }
    ],
    "nextCursor": "string"
  }
}

Open positions

get/accounts/{owner}/positions

Path parameters

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

Query parameters

cursorstring
Position id cursor (decimal) from nextCursor.
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

Responses

Open positions and nextCursor. cursor and limit are forwarded when present. autoCloseAtMs is when an equity position is force-closed at session end (null otherwise).
application/json
dataPositionsPagerequired
Open positions by id.
nextCursorstring | null
positionsPosition[]required
accountIdstring | null
Pattern^0x[0-9a-f]{64}$
Example0xad23e722f3542ae36c276c1b303e30ae77c840a84db89c7215fa87bf92006691
attributionstringrequired
Who sent a position's open.
One ofownerdelegateunindexed_account
autoCloseAtMsstring | null
Open positions on equity markets: when the session force close settles it.
Pattern^-?(0|[1-9][0-9]*)n$
Example1796677200000n
bustWadstring | null
Scaled by 1e18 (WAD).
Pattern^-?(0|[1-9][0-9]*)n$
Example67550000000000000000n
closeFeePpmstring | null
Parts per million.
Pattern^-?(0|[1-9][0-9]*)n$
Example500n
confWadstring | null
Scaled by 1e18 (WAD).
Pattern^-?(0|[1-9][0-9]*)n$
Example30000000000000000n
deadbandPpmstring | null
Parts per million.
Pattern^-?(0|[1-9][0-9]*)n$
Example1000n
entryWadstring | null
Scaled by 1e18 (WAD).
Pattern^-?(0|[1-9][0-9]*)n$
Example74250000000000000000n
exitKindnull | string
factorBpsstring | null
Basis points (1/10000).
Pattern^-?(0|[1-9][0-9]*)n$
Example10000n
fillBustWadstring | null
Liquidation price at the fill, not the requested stop-loss price.
Pattern^-?(0|[1-9][0-9]*)n$
Example67550000000000000000n
isLongbooleanrequired
leveragestring | null
notional / margin.
Pattern^-?(0|[1-9][0-9]*)n$
Example10n
marginstring | null
Pattern^-?(0|[1-9][0-9]*)n$
Example100000000n
marketIdstringrequired
Pattern^0x[0-9a-f]{64}$
Example0x6e6238eb4f69bfcc3e884a7d20904eb0995ca2e42c95dc8560d5a417486ab645
midWadstring | null
Scaled by 1e18 (WAD).
Pattern^-?(0|[1-9][0-9]*)n$
Example74250000000000000000n
notionalstring | null
Pattern^-?(0|[1-9][0-9]*)n$
Example1000000000n
openTxstring | null
openedAtMsstring | null
Milliseconds.
Pattern^-?(0|[1-9][0-9]*)n$
Example1796677200000n
ownerstringrequired
Pattern^0x[0-9a-f]{64}$
Example0x77b909b550ed11c45f1378c03c0954c0d77d320cdc938e35509564b1e505ce0d
positionIdstringrequired
Pattern^-?(0|[1-9][0-9]*)n$
Example1042n
slDroppedReasonstring | null
Service-recorded stop-loss drop reason, independent of the current trigger legs.
statusstringrequired
One ofopenclosedliquidated
stopLossWadstring | null
Scaled by 1e18 (WAD).
Pattern^(0|[1-9][0-9]*)n$
Example71500000000000000000n
takeProfitWadstring | null
Scaled by 1e18 (WAD).
Pattern^(0|[1-9][0-9]*)n$
Example78000000000000000000n
traderstringrequired
Sender of the open.
Pattern^0x[0-9a-f]{64}$
Example0x77b909b550ed11c45f1378c03c0954c0d77d320cdc938e35509564b1e505ce0d
triggersnull | TriggerView
accountIdstringrequired
Owning account.
Pattern^0x[0-9a-f]{64}$
Example0xad23e722f3542ae36c276c1b303e30ae77c840a84db89c7215fa87bf92006691
firingboolean | null
A signed close may still execute; edits are fenced until resolved.
firingEtaMsstring | null
Best known end of the epoch validity window, Unix ms; absent if unavailable.
Pattern^(0|[1-9][0-9]*)n$
Example1796677200000n
firingKindstring | null
Leg currently submitting, tp or sl.
firingMaxEpochstring | null
Last epoch in which the saved close may execute; resolved when chain epoch exceeds it.
Pattern^(0|[1-9][0-9]*)n$
Example912n
isLongbooleanrequired
Position direction.
marketIdstringrequired
Market for both legs.
Pattern^0x[0-9a-f]{64}$
Example0x6e6238eb4f69bfcc3e884a7d20904eb0995ca2e42c95dc8560d5a417486ab645
ownerstringrequired
Wallet owner.
Pattern^0x[0-9a-f]{64}$
Example0x77b909b550ed11c45f1378c03c0954c0d77d320cdc938e35509564b1e505ce0d
pausedboolean | null
Missing close grant pauses evaluation while retaining the legs.
positionIdstring | null
Position once the open attaches.
Pattern^(0|[1-9][0-9]*)n$
Example1042n
statusstringrequired
pending, attached, armed, idle, firing, submitted, fired, closed or void.
One ofpendingattachedarmedidlefiringsubmittedfiredclosedvoid
stopLossDroppednull | StopLossDropped
stopLossWadstring | null
Armed SL WAD.
Pattern^(0|[1-9][0-9]*)n$
Example71500000000000000000n
takeProfitWadstring | null
Armed TP WAD.
Pattern^(0|[1-9][0-9]*)n$
Example78000000000000000000n
voidReasonstring | null
Terminal reason for a recent void open intent.
winFeeBpsstring | null
Basis points (1/10000).
Pattern^-?(0|[1-9][0-9]*)n$
Example2000n
winningExposurestring | null
Pattern^-?(0|[1-9][0-9]*)n$
Example1850000000000n
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/accounts/0x77b909b550ed11c45f1378c03c0954c0d77d320cdc938e35509564b1e505ce0d/positions'

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

Example response (200)

application/json

{
  "data": {
    "nextCursor": "string",
    "positions": [
      {
        "accountId": "0xad23e722f3542ae36c276c1b303e30ae77c840a84db89c7215fa87bf92006691",
        "attribution": "owner",
        "autoCloseAtMs": "1796677200000n",
        "bustWad": "67550000000000000000n",
        "closeFeePpm": "500n",
        "confWad": "30000000000000000n",
        "deadbandPpm": "1000n",
        "entryWad": "74250000000000000000n",
        "exitKind": "close",
        "factorBps": "10000n",
        "fillBustWad": "67550000000000000000n",
        "isLong": true,
        "leverage": "10n",
        "margin": "100000000n",
        "marketId": "0x6e6238eb4f69bfcc3e884a7d20904eb0995ca2e42c95dc8560d5a417486ab645",
        "midWad": "74250000000000000000n",
        "notional": "1000000000n",
        "openTx": "string",
        "openedAtMs": "1796677200000n",
        "owner": "0x77b909b550ed11c45f1378c03c0954c0d77d320cdc938e35509564b1e505ce0d",
        "positionId": "1042n",
        "slDroppedReason": "string",
        "status": "open",
        "stopLossWad": "71500000000000000000n",
        "takeProfitWad": "78000000000000000000n",
        "trader": "0x77b909b550ed11c45f1378c03c0954c0d77d320cdc938e35509564b1e505ce0d",
        "triggers": {
          "accountId": "0xad23e722f3542ae36c276c1b303e30ae77c840a84db89c7215fa87bf92006691",
          "firing": true,
          "firingEtaMs": "1796677200000n",
          "firingKind": "string",
          "firingMaxEpoch": "912n",
          "isLong": true,
          "marketId": "0x6e6238eb4f69bfcc3e884a7d20904eb0995ca2e42c95dc8560d5a417486ab645",
          "owner": "0x77b909b550ed11c45f1378c03c0954c0d77d320cdc938e35509564b1e505ce0d",
          "paused": true,
          "positionId": "1042n",
          "status": "pending",
          "stopLossDropped": {
            "ms": "1796677200000n",
            "reason": "string",
            "wad": "74250000000000000000n"
          },
          "stopLossWad": "71500000000000000000n",
          "takeProfitWad": "78000000000000000000n",
          "voidReason": "string"
        },
        "winFeeBps": "2000n",
        "winningExposure": "1850000000000n"
      }
    ]
  }
}

On-chain TP/SL levels

get/accounts/{owner}/trigger-levels

Path parameters

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

Responses

On-chain TP/SL commitments of the wallet (parchment_triggers package): per open position its latest edit by chain order (revision is caller-supplied and informational), else the levels committed with the open request that created it; then pending open requests with levels. Records only: the trigger service acts on owner-signed triggers (POST /triggers), not on these. All integers are js_bigint strings.
application/json
dataChainTriggerLevelsViewrequired
GET /accounts/{owner}/trigger-levels.
levelsChainTriggerLevels[]required
accountIdstringrequired
Pattern^0x[0-9a-f]{64}$
Example0xad23e722f3542ae36c276c1b303e30ae77c840a84db89c7215fa87bf92006691
positionIdstring | null
The open position; null while the open request (requestId) is pending.
Pattern^(0|[1-9][0-9]*)n$
Example1042n
requestIdstring | null
The open request the levels were committed with (source open).
Pattern^0x[0-9a-f]{64}$
Example0xe4685be89af887adcea9b6bd3842cb9276e839bad0c361f0380ab288ae8a0b05
revisionstring | null
The edit's caller-supplied revision (set only; unchecked on chain, informational).
Pattern^(0|[1-9][0-9]*)n$
Example1n
senderstringrequired
Pattern^0x[0-9a-f]{64}$
Example0x77b909b550ed11c45f1378c03c0954c0d77d320cdc938e35509564b1e505ce0d
sourcestringrequired
open: committed with the open request; set: an edit (set_trigger_levels).
stopLossWadstring | null
Scaled by 1e18 (WAD).
Pattern^(0|[1-9][0-9]*)n$
Example71500000000000000000n
takeProfitWadstring | null
WAD price.
Pattern^(0|[1-9][0-9]*)n$
Example78000000000000000000n
timestampMsstringrequired
Milliseconds.
Pattern^(0|[1-9][0-9]*)n$
Example1796677200000n
txDigeststringrequired
Pattern^[1-9A-HJ-NP-Za-km-z]{32,44}$
Examplec3CE1sYJ2ufo1E8wNhVahkJbu66F4tMxpTXLeW3o8QSA
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
application/json
errorErrorObjectrequired
codestringrequired
messagestringrequired
application/json
errorErrorObjectrequired
codestringrequired
messagestringrequired

Example request

curl 'https://api.parchment.trade/accounts/0x77b909b550ed11c45f1378c03c0954c0d77d320cdc938e35509564b1e505ce0d/trigger-levels'

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

Example response (200)

application/json

{
  "data": {
    "levels": [
      {
        "accountId": "0xad23e722f3542ae36c276c1b303e30ae77c840a84db89c7215fa87bf92006691",
        "positionId": "1042n",
        "requestId": "0xe4685be89af887adcea9b6bd3842cb9276e839bad0c361f0380ab288ae8a0b05",
        "revision": "1n",
        "sender": "0x77b909b550ed11c45f1378c03c0954c0d77d320cdc938e35509564b1e505ce0d",
        "source": "string",
        "stopLossWad": "71500000000000000000n",
        "takeProfitWad": "78000000000000000000n",
        "timestampMs": "1796677200000n",
        "txDigest": "c3CE1sYJ2ufo1E8wNhVahkJbu66F4tMxpTXLeW3o8QSA"
      }
    ]
  }
}

TP/SL triggers

get/accounts/{owner}/triggers

Path parameters

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

Query parameters

cursorstring
Opaque cursor from the previous page's nextCursor.
Example0xc00d9a508112ec1dff7df53f35f096e26af4ec600dc291264b483d27aeb18b75
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. The service clamps it to api.max-page-limit, which is also its default.
Pattern^(0|[1-9][0-9]*)$
Example50

Responses

One page of public attached trigger rows and recent terminal outcomes ({ triggers, nextCursor }; nextCursor is an opaque page token, null on the last page). Pending open intents (lapsed ones included) and open digests are omitted by the service. Rows may include paused, stopLossDropped {reason, ms, wad}, voidReason (order_not_filled, not_in_transaction, ambiguous_open, aborted, expired, cancelled, over_cap, attach_impossible, lapse_evicted), firing, firingMaxEpoch and firingEtaMs. ETA is an estimate, not proof of expiry. All integers are n-suffixed decimal strings.
application/json
dataTriggersrequired
nextCursorstring | null
Opaque cursor of the next page (pass it as cursor); null on the last page.
triggersTriggerView[]required
Trigger rows; unsent open digests are omitted.
accountIdstringrequired
Owning account.
Pattern^0x[0-9a-f]{64}$
Example0xad23e722f3542ae36c276c1b303e30ae77c840a84db89c7215fa87bf92006691
firingboolean | null
A signed close may still execute; edits are fenced until resolved.
firingEtaMsstring | null
Best known end of the epoch validity window, Unix ms; absent if unavailable.
Pattern^(0|[1-9][0-9]*)n$
Example1796677200000n
firingKindstring | null
Leg currently submitting, tp or sl.
firingMaxEpochstring | null
Last epoch in which the saved close may execute; resolved when chain epoch exceeds it.
Pattern^(0|[1-9][0-9]*)n$
Example912n
isLongbooleanrequired
Position direction.
marketIdstringrequired
Market for both legs.
Pattern^0x[0-9a-f]{64}$
Example0x6e6238eb4f69bfcc3e884a7d20904eb0995ca2e42c95dc8560d5a417486ab645
ownerstringrequired
Wallet owner.
Pattern^0x[0-9a-f]{64}$
Example0x77b909b550ed11c45f1378c03c0954c0d77d320cdc938e35509564b1e505ce0d
pausedboolean | null
Missing close grant pauses evaluation while retaining the legs.
positionIdstring | null
Position once the open attaches.
Pattern^(0|[1-9][0-9]*)n$
Example1042n
statusstringrequired
pending, attached, armed, idle, firing, submitted, fired, closed or void.
One ofpendingattachedarmedidlefiringsubmittedfiredclosedvoid
stopLossDroppednull | StopLossDropped
stopLossWadstring | null
Armed SL WAD.
Pattern^(0|[1-9][0-9]*)n$
Example71500000000000000000n
takeProfitWadstring | null
Armed TP WAD.
Pattern^(0|[1-9][0-9]*)n$
Example78000000000000000000n
voidReasonstring | null
Terminal reason for a recent void open intent.
Invalid owner address, cursor or limit (local), or the service's bad_request for a cursor it did not issue
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
Gateway timeout: the service did not answer in time
application/json
errorErrorObjectrequired
codestringrequired
messagestringrequired

Example request

curl 'https://api.parchment.trade/accounts/0x77b909b550ed11c45f1378c03c0954c0d77d320cdc938e35509564b1e505ce0d/triggers'

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

Example response (200)

application/json

{
  "data": {
    "nextCursor": "string",
    "triggers": [
      {
        "accountId": "0xad23e722f3542ae36c276c1b303e30ae77c840a84db89c7215fa87bf92006691",
        "firing": true,
        "firingEtaMs": "1796677200000n",
        "firingKind": "string",
        "firingMaxEpoch": "912n",
        "isLong": true,
        "marketId": "0x6e6238eb4f69bfcc3e884a7d20904eb0995ca2e42c95dc8560d5a417486ab645",
        "owner": "0x77b909b550ed11c45f1378c03c0954c0d77d320cdc938e35509564b1e505ce0d",
        "paused": true,
        "positionId": "1042n",
        "status": "pending",
        "stopLossDropped": {
          "ms": "1796677200000n",
          "reason": "string",
          "wad": "74250000000000000000n"
        },
        "stopLossWad": "71500000000000000000n",
        "takeProfitWad": "78000000000000000000n",
        "voidReason": "string"
      }
    ]
  }
}

Trading referral

get/accounts/{walletAddress}/trading-referral

Path parameters

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

Responses

referrer (null when unbound), refereeCount, totalEarned and pending (integers as n-suffixed decimal strings, "5000000n").
application/json
dataTradingReferralrequired
pendingstringrequired
Pattern^-?(0|[1-9][0-9]*)n$
Example100000000n
refereeCountstringrequired
Wallets bound to this one as their referrer.
Pattern^-?(0|[1-9][0-9]*)n$
Example24n
referrerstring | null
The wallet's referrer; null when unbound.
Pattern^0x[0-9a-f]{64}$
Example0x77b909b550ed11c45f1378c03c0954c0d77d320cdc938e35509564b1e505ce0d
totalEarnedstringrequired
Pattern^-?(0|[1-9][0-9]*)n$
Example100000000n
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/accounts/0x77b909b550ed11c45f1378c03c0954c0d77d320cdc938e35509564b1e505ce0d/trading-referral'

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

Example response (200)

application/json

{
  "data": {
    "pending": "100000000n",
    "refereeCount": "24n",
    "referrer": "0x77b909b550ed11c45f1378c03c0954c0d77d320cdc938e35509564b1e505ce0d",
    "totalEarned": "100000000n"
  }
}

Position

get/positions/{id}

Path parameters

idstringrequired
Position id: canonical decimal (digits only, no sign, whitespace or leading zero). A canonical decimal above 18446744073709551615 names no position and is 404 position_not_found without calling the service.
Example1042

Responses

One position ({ position }), including autoCloseAtMs (equity session end, else null). The service's typed response, as public camelCase JSON.
application/json
dataPositionResponserequired
positionPositionrequired
One position, open or exited.
accountIdstring | null
Pattern^0x[0-9a-f]{64}$
Example0xad23e722f3542ae36c276c1b303e30ae77c840a84db89c7215fa87bf92006691
attributionstringrequired
Who sent a position's open.
One ofownerdelegateunindexed_account
autoCloseAtMsstring | null
Open positions on equity markets: when the session force close settles it.
Pattern^-?(0|[1-9][0-9]*)n$
Example1796677200000n
bustWadstring | null
Scaled by 1e18 (WAD).
Pattern^-?(0|[1-9][0-9]*)n$
Example67550000000000000000n
closeFeePpmstring | null
Parts per million.
Pattern^-?(0|[1-9][0-9]*)n$
Example500n
confWadstring | null
Scaled by 1e18 (WAD).
Pattern^-?(0|[1-9][0-9]*)n$
Example30000000000000000n
deadbandPpmstring | null
Parts per million.
Pattern^-?(0|[1-9][0-9]*)n$
Example1000n
entryWadstring | null
Scaled by 1e18 (WAD).
Pattern^-?(0|[1-9][0-9]*)n$
Example74250000000000000000n
exitKindnull | string
factorBpsstring | null
Basis points (1/10000).
Pattern^-?(0|[1-9][0-9]*)n$
Example10000n
fillBustWadstring | null
Liquidation price at the fill, not the requested stop-loss price.
Pattern^-?(0|[1-9][0-9]*)n$
Example67550000000000000000n
isLongbooleanrequired
leveragestring | null
notional / margin.
Pattern^-?(0|[1-9][0-9]*)n$
Example10n
marginstring | null
Pattern^-?(0|[1-9][0-9]*)n$
Example100000000n
marketIdstringrequired
Pattern^0x[0-9a-f]{64}$
Example0x6e6238eb4f69bfcc3e884a7d20904eb0995ca2e42c95dc8560d5a417486ab645
midWadstring | null
Scaled by 1e18 (WAD).
Pattern^-?(0|[1-9][0-9]*)n$
Example74250000000000000000n
notionalstring | null
Pattern^-?(0|[1-9][0-9]*)n$
Example1000000000n
openTxstring | null
openedAtMsstring | null
Milliseconds.
Pattern^-?(0|[1-9][0-9]*)n$
Example1796677200000n
ownerstringrequired
Pattern^0x[0-9a-f]{64}$
Example0x77b909b550ed11c45f1378c03c0954c0d77d320cdc938e35509564b1e505ce0d
positionIdstringrequired
Pattern^-?(0|[1-9][0-9]*)n$
Example1042n
slDroppedReasonstring | null
Service-recorded stop-loss drop reason, independent of the current trigger legs.
statusstringrequired
One ofopenclosedliquidated
stopLossWadstring | null
Scaled by 1e18 (WAD).
Pattern^(0|[1-9][0-9]*)n$
Example71500000000000000000n
takeProfitWadstring | null
Scaled by 1e18 (WAD).
Pattern^(0|[1-9][0-9]*)n$
Example78000000000000000000n
traderstringrequired
Sender of the open.
Pattern^0x[0-9a-f]{64}$
Example0x77b909b550ed11c45f1378c03c0954c0d77d320cdc938e35509564b1e505ce0d
triggersnull | TriggerView
accountIdstringrequired
Owning account.
Pattern^0x[0-9a-f]{64}$
Example0xad23e722f3542ae36c276c1b303e30ae77c840a84db89c7215fa87bf92006691
firingboolean | null
A signed close may still execute; edits are fenced until resolved.
firingEtaMsstring | null
Best known end of the epoch validity window, Unix ms; absent if unavailable.
Pattern^(0|[1-9][0-9]*)n$
Example1796677200000n
firingKindstring | null
Leg currently submitting, tp or sl.
firingMaxEpochstring | null
Last epoch in which the saved close may execute; resolved when chain epoch exceeds it.
Pattern^(0|[1-9][0-9]*)n$
Example912n
isLongbooleanrequired
Position direction.
marketIdstringrequired
Market for both legs.
Pattern^0x[0-9a-f]{64}$
Example0x6e6238eb4f69bfcc3e884a7d20904eb0995ca2e42c95dc8560d5a417486ab645
ownerstringrequired
Wallet owner.
Pattern^0x[0-9a-f]{64}$
Example0x77b909b550ed11c45f1378c03c0954c0d77d320cdc938e35509564b1e505ce0d
pausedboolean | null
Missing close grant pauses evaluation while retaining the legs.
positionIdstring | null
Position once the open attaches.
Pattern^(0|[1-9][0-9]*)n$
Example1042n
statusstringrequired
pending, attached, armed, idle, firing, submitted, fired, closed or void.
One ofpendingattachedarmedidlefiringsubmittedfiredclosedvoid
stopLossDroppednull | StopLossDropped
stopLossWadstring | null
Armed SL WAD.
Pattern^(0|[1-9][0-9]*)n$
Example71500000000000000000n
takeProfitWadstring | null
Armed TP WAD.
Pattern^(0|[1-9][0-9]*)n$
Example78000000000000000000n
voidReasonstring | null
Terminal reason for a recent void open intent.
winFeeBpsstring | null
Basis points (1/10000).
Pattern^-?(0|[1-9][0-9]*)n$
Example2000n
winningExposurestring | null
Pattern^-?(0|[1-9][0-9]*)n$
Example1850000000000n
Position id is not a canonical decimal integer (bad_request; "0007" and "+7" included)
application/json
errorErrorObjectrequired
codestringrequired
messagestringrequired
position_not_found: from the service for an unknown id, 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/positions/1042'

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

Example response (200)

application/json

{
  "data": {
    "position": {
      "accountId": "0xad23e722f3542ae36c276c1b303e30ae77c840a84db89c7215fa87bf92006691",
      "attribution": "owner",
      "autoCloseAtMs": "1796677200000n",
      "bustWad": "67550000000000000000n",
      "closeFeePpm": "500n",
      "confWad": "30000000000000000n",
      "deadbandPpm": "1000n",
      "entryWad": "74250000000000000000n",
      "exitKind": "close",
      "factorBps": "10000n",
      "fillBustWad": "67550000000000000000n",
      "isLong": true,
      "leverage": "10n",
      "margin": "100000000n",
      "marketId": "0x6e6238eb4f69bfcc3e884a7d20904eb0995ca2e42c95dc8560d5a417486ab645",
      "midWad": "74250000000000000000n",
      "notional": "1000000000n",
      "openTx": "string",
      "openedAtMs": "1796677200000n",
      "owner": "0x77b909b550ed11c45f1378c03c0954c0d77d320cdc938e35509564b1e505ce0d",
      "positionId": "1042n",
      "slDroppedReason": "string",
      "status": "open",
      "stopLossWad": "71500000000000000000n",
      "takeProfitWad": "78000000000000000000n",
      "trader": "0x77b909b550ed11c45f1378c03c0954c0d77d320cdc938e35509564b1e505ce0d",
      "triggers": {
        "accountId": "0xad23e722f3542ae36c276c1b303e30ae77c840a84db89c7215fa87bf92006691",
        "firing": true,
        "firingEtaMs": "1796677200000n",
        "firingKind": "string",
        "firingMaxEpoch": "912n",
        "isLong": true,
        "marketId": "0x6e6238eb4f69bfcc3e884a7d20904eb0995ca2e42c95dc8560d5a417486ab645",
        "owner": "0x77b909b550ed11c45f1378c03c0954c0d77d320cdc938e35509564b1e505ce0d",
        "paused": true,
        "positionId": "1042n",
        "status": "pending",
        "stopLossDropped": {
          "ms": "1796677200000n",
          "reason": "string",
          "wad": "74250000000000000000n"
        },
        "stopLossWad": "71500000000000000000n",
        "takeProfitWad": "78000000000000000000n",
        "voidReason": "string"
      },
      "winFeeBps": "2000n",
      "winningExposure": "1850000000000n"
    }
  }
}

Set or clear TP/SL

post/triggers

Request body (required)

SetTriggersRequest · application/json

accountIdstringrequired
Account owned by the signer.
Example0xad23e722f3542ae36c276c1b303e30ae77c840a84db89c7215fa87bf92006691
expiresAtMsstringrequired
Proof expiry and monotonic revision time, Unix ms.
Pattern^(0|[1-9][0-9]*)n$
Example1796677200000n
isLongboolean | null
Side signed for the open target.
marketIdstring | null
Market signed for the open target.
Example0x6e6238eb4f69bfcc3e884a7d20904eb0995ca2e42c95dc8560d5a417486ab645
openTxBytesBase64string | null
BCS Transaction (padded standard base64) whose digest must equal open_tx_digest. Required on open intents that set a leg so the service records the transaction's epoch bound (unbounded opens are refused); may be omitted on an open clear (both legs null); refused on position targets.
openTxDigeststring | null
Digest of the future open transaction.
Examplex21Xc3621WJsDb7MdBCf9GZ9v9vh3UnWrdWRADfTKNCq
ownerstringrequired
Wallet signing the personal message.
Example0x77b909b550ed11c45f1378c03c0954c0d77d320cdc938e35509564b1e505ce0d
positionIdstring | null
Existing position; mutually exclusive with the open target fields.
Pattern^(0|[1-9][0-9]*)n$
Example1042n
signaturestringrequired
Sui personal-message signature, base64.
stopLossWadstring | null
SL price in exact 18 decimal WAD units; null clears it.
Pattern^(0|[1-9][0-9]*)n$
Example71500000000000000000n
takeProfitWadstring | null
TP price in exact 18 decimal WAD units; null clears it.
Pattern^(0|[1-9][0-9]*)n$
Example78000000000000000000n

Responses

Set or clear both legs with a newer owner-signed proof. Target: positionId OR openTxDigest+marketId+isLong; explicit null for unused fields is absent. Open intents that set a leg carry openTxBytesBase64 (padded standard base64 BCS Transaction with finite maximum epoch) for digest/expiry verification; an open clear (both legs null) may omit it, and a position target refuses it. Each leg closes the whole position. Both null legs clear, including while paused. Integers are n-suffixed decimal strings; the signed seven-line message uses plain decimals. Responses omit open digests and signature material.
application/json
dataTriggerViewrequired
accountIdstringrequired
Owning account.
Pattern^0x[0-9a-f]{64}$
Example0xad23e722f3542ae36c276c1b303e30ae77c840a84db89c7215fa87bf92006691
firingboolean | null
A signed close may still execute; edits are fenced until resolved.
firingEtaMsstring | null
Best known end of the epoch validity window, Unix ms; absent if unavailable.
Pattern^(0|[1-9][0-9]*)n$
Example1796677200000n
firingKindstring | null
Leg currently submitting, tp or sl.
firingMaxEpochstring | null
Last epoch in which the saved close may execute; resolved when chain epoch exceeds it.
Pattern^(0|[1-9][0-9]*)n$
Example912n
isLongbooleanrequired
Position direction.
marketIdstringrequired
Market for both legs.
Pattern^0x[0-9a-f]{64}$
Example0x6e6238eb4f69bfcc3e884a7d20904eb0995ca2e42c95dc8560d5a417486ab645
ownerstringrequired
Wallet owner.
Pattern^0x[0-9a-f]{64}$
Example0x77b909b550ed11c45f1378c03c0954c0d77d320cdc938e35509564b1e505ce0d
pausedboolean | null
Missing close grant pauses evaluation while retaining the legs.
positionIdstring | null
Position once the open attaches.
Pattern^(0|[1-9][0-9]*)n$
Example1042n
statusstringrequired
pending, attached, armed, idle, firing, submitted, fired, closed or void.
One ofpendingattachedarmedidlefiringsubmittedfiredclosedvoid
stopLossDroppednull | StopLossDropped
stopLossWadstring | null
Armed SL WAD.
Pattern^(0|[1-9][0-9]*)n$
Example71500000000000000000n
takeProfitWadstring | null
Armed TP WAD.
Pattern^(0|[1-9][0-9]*)n$
Example78000000000000000000n
voidReasonstring | null
Terminal reason for a recent void open intent.
bad_request (including malformed integers), bad_signature, proof_expiry, not_owner, trigger_not_enabled, bad_price, past_liquidation, bad_trigger_order, trigger_already_crossed, position_closed, order_not_filled
application/json
errorErrorObjectrequired
codestringrequired
messagestringrequired
application/json
errorErrorObjectrequired
codestringrequired
messagestringrequired
application/json
errorErrorObjectrequired
codestringrequired
messagestringrequired
application/json
errorErrorObjectrequired
codestringrequired
messagestringrequired
application/json
errorErrorObjectrequired
codestringrequired
messagestringrequired
too_many_pending (the account's on-chain pending-order cap of orders waiting with TP/SL), too_many_pending_intents (the wallet's 256 orders waiting with TP/SL), or rate_limited; retry after backoff. Also rate_limited: too many requests from this client IP; retry after Retry-After seconds
application/json
Headers: Retry-After
errorErrorObjectrequired
codestringrequired
messagestringrequired
application/json
errorErrorObjectrequired
codestringrequired
messagestringrequired
Bad gateway: the service is temporarily unavailable
application/json
errorErrorObjectrequired
codestringrequired
messagestringrequired
application/json
errorErrorObjectrequired
codestringrequired
messagestringrequired
Gateway timeout: the service did not answer in time
application/json
errorErrorObjectrequired
codestringrequired
messagestringrequired

Example request

curl -X POST 'https://api.parchment.trade/triggers' \
  -H 'Content-Type: application/json' \
  -d '{
  "accountId": "0xad23e722f3542ae36c276c1b303e30ae77c840a84db89c7215fa87bf92006691",
  "expiresAtMs": "1796677200000n",
  "isLong": true,
  "marketId": "0x6e6238eb4f69bfcc3e884a7d20904eb0995ca2e42c95dc8560d5a417486ab645",
  "openTxBytesBase64": "string",
  "openTxDigest": "x21Xc3621WJsDb7MdBCf9GZ9v9vh3UnWrdWRADfTKNCq",
  "owner": "0x77b909b550ed11c45f1378c03c0954c0d77d320cdc938e35509564b1e505ce0d",
  "positionId": "1042n",
  "signature": "string",
  "stopLossWad": "71500000000000000000n",
  "takeProfitWad": "78000000000000000000n"
}'

const res = await fetch("https://api.parchment.trade/triggers", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    "accountId": "0xad23e722f3542ae36c276c1b303e30ae77c840a84db89c7215fa87bf92006691",
    "expiresAtMs": "1796677200000n",
    "isLong": true,
    "marketId": "0x6e6238eb4f69bfcc3e884a7d20904eb0995ca2e42c95dc8560d5a417486ab645",
    "openTxBytesBase64": "string",
    "openTxDigest": "x21Xc3621WJsDb7MdBCf9GZ9v9vh3UnWrdWRADfTKNCq",
    "owner": "0x77b909b550ed11c45f1378c03c0954c0d77d320cdc938e35509564b1e505ce0d",
    "positionId": "1042n",
    "signature": "string",
    "stopLossWad": "71500000000000000000n",
    "takeProfitWad": "78000000000000000000n"
  }),
});
const { data } = await res.json();

Example response (200)

application/json

{
  "data": {
    "accountId": "0xad23e722f3542ae36c276c1b303e30ae77c840a84db89c7215fa87bf92006691",
    "firing": true,
    "firingEtaMs": "1796677200000n",
    "firingKind": "string",
    "firingMaxEpoch": "912n",
    "isLong": true,
    "marketId": "0x6e6238eb4f69bfcc3e884a7d20904eb0995ca2e42c95dc8560d5a417486ab645",
    "owner": "0x77b909b550ed11c45f1378c03c0954c0d77d320cdc938e35509564b1e505ce0d",
    "paused": true,
    "positionId": "1042n",
    "status": "pending",
    "stopLossDropped": {
      "ms": "1796677200000n",
      "reason": "string",
      "wad": "74250000000000000000n"
    },
    "stopLossWad": "71500000000000000000n",
    "takeProfitWad": "78000000000000000000n",
    "voidReason": "string"
  }
}

Bind prepared TP/SL to an open

post/triggers/bind

Request body (required)

BindTriggersRequest · application/json

accountIdstringrequired
Example0xad23e722f3542ae36c276c1b303e30ae77c840a84db89c7215fa87bf92006691
intentIdstringrequired
Exampled54daa1bcef482122fedd0b7c675ff7c
openTxBytesBase64stringrequired
The signed open Transaction, BCS, padded standard base64.
ownerstringrequired
Example0x77b909b550ed11c45f1378c03c0954c0d77d320cdc938e35509564b1e505ce0d
signaturesstring[]required
Its base64 Sui signatures; the sender's (owner or the delegate that signed the prepare) must be one.

Responses

Binds a prepared intent to its signed open transaction, whose sender signed it: the legs become that open's intent (attached at once if the open already filled). One intent binds one transaction; a repeat with the same one answers the same. Integers in the trigger row are n-suffixed decimal strings.
application/json
dataTriggerViewrequired
accountIdstringrequired
Owning account.
Pattern^0x[0-9a-f]{64}$
Example0xad23e722f3542ae36c276c1b303e30ae77c840a84db89c7215fa87bf92006691
firingboolean | null
A signed close may still execute; edits are fenced until resolved.
firingEtaMsstring | null
Best known end of the epoch validity window, Unix ms; absent if unavailable.
Pattern^(0|[1-9][0-9]*)n$
Example1796677200000n
firingKindstring | null
Leg currently submitting, tp or sl.
firingMaxEpochstring | null
Last epoch in which the saved close may execute; resolved when chain epoch exceeds it.
Pattern^(0|[1-9][0-9]*)n$
Example912n
isLongbooleanrequired
Position direction.
marketIdstringrequired
Market for both legs.
Pattern^0x[0-9a-f]{64}$
Example0x6e6238eb4f69bfcc3e884a7d20904eb0995ca2e42c95dc8560d5a417486ab645
ownerstringrequired
Wallet owner.
Pattern^0x[0-9a-f]{64}$
Example0x77b909b550ed11c45f1378c03c0954c0d77d320cdc938e35509564b1e505ce0d
pausedboolean | null
Missing close grant pauses evaluation while retaining the legs.
positionIdstring | null
Position once the open attaches.
Pattern^(0|[1-9][0-9]*)n$
Example1042n
statusstringrequired
pending, attached, armed, idle, firing, submitted, fired, closed or void.
One ofpendingattachedarmedidlefiringsubmittedfiredclosedvoid
stopLossDroppednull | StopLossDropped
stopLossWadstring | null
Armed SL WAD.
Pattern^(0|[1-9][0-9]*)n$
Example71500000000000000000n
takeProfitWadstring | null
Armed TP WAD.
Pattern^(0|[1-9][0-9]*)n$
Example78000000000000000000n
voidReasonstring | null
Terminal reason for a recent void open intent.
bad_request, bad_signature, bind_unverified (a multisig, passkey or zkLogin sender: save with POST /triggers instead), proof_expired, not_owner (including a delegate whose delegation lapsed since prepare), trigger_not_enabled, trigger_already_crossed (the price moved past a level since prepare)
application/json
errorErrorObjectrequired
codestringrequired
messagestringrequired
application/json
errorErrorObjectrequired
codestringrequired
messagestringrequired
application/json
errorErrorObjectrequired
codestringrequired
messagestringrequired
application/json
errorErrorObjectrequired
codestringrequired
messagestringrequired
too_many_pending, too_many_pending_intents or rate_limited. Also 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
Gateway timeout: the service did not answer in time
application/json
errorErrorObjectrequired
codestringrequired
messagestringrequired

Example request

curl -X POST 'https://api.parchment.trade/triggers/bind' \
  -H 'Content-Type: application/json' \
  -d '{
  "accountId": "0xad23e722f3542ae36c276c1b303e30ae77c840a84db89c7215fa87bf92006691",
  "intentId": "d54daa1bcef482122fedd0b7c675ff7c",
  "openTxBytesBase64": "string",
  "owner": "0x77b909b550ed11c45f1378c03c0954c0d77d320cdc938e35509564b1e505ce0d",
  "signatures": []
}'

const res = await fetch("https://api.parchment.trade/triggers/bind", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    "accountId": "0xad23e722f3542ae36c276c1b303e30ae77c840a84db89c7215fa87bf92006691",
    "intentId": "d54daa1bcef482122fedd0b7c675ff7c",
    "openTxBytesBase64": "string",
    "owner": "0x77b909b550ed11c45f1378c03c0954c0d77d320cdc938e35509564b1e505ce0d",
    "signatures": []
  }),
});
const { data } = await res.json();

Example response (200)

application/json

{
  "data": {
    "accountId": "0xad23e722f3542ae36c276c1b303e30ae77c840a84db89c7215fa87bf92006691",
    "firing": true,
    "firingEtaMs": "1796677200000n",
    "firingKind": "string",
    "firingMaxEpoch": "912n",
    "isLong": true,
    "marketId": "0x6e6238eb4f69bfcc3e884a7d20904eb0995ca2e42c95dc8560d5a417486ab645",
    "owner": "0x77b909b550ed11c45f1378c03c0954c0d77d320cdc938e35509564b1e505ce0d",
    "paused": true,
    "positionId": "1042n",
    "status": "pending",
    "stopLossDropped": {
      "ms": "1796677200000n",
      "reason": "string",
      "wad": "74250000000000000000n"
    },
    "stopLossWad": "71500000000000000000n",
    "takeProfitWad": "78000000000000000000n",
    "voidReason": "string"
  }
}

Prepare TP/SL for a pending open

post/triggers/prepare

Request body (required)

PrepareTriggersRequest · application/json

accountIdstringrequired
Example0xad23e722f3542ae36c276c1b303e30ae77c840a84db89c7215fa87bf92006691
expiresAtMsstringrequired
Canonical decimal unix ms.
intentIdstringrequired
32 lowercase hex digits: 16 random bytes the client chose, used once.
Exampled54daa1bcef482122fedd0b7c675ff7c
isLongbooleanrequired
marketIdstringrequired
Example0x6e6238eb4f69bfcc3e884a7d20904eb0995ca2e42c95dc8560d5a417486ab645
ownerstringrequired
Example0x77b909b550ed11c45f1378c03c0954c0d77d320cdc938e35509564b1e505ce0d
signaturestringrequired
stopLossWadstring | null
Canonical decimal WAD, or null.
takeProfitWadstring | null
Canonical decimal WAD, or null.

Responses

TP/SL for an open that is still being built, checked like an open intent and stored under the intent id until a signed open is bound to it (POST /triggers/bind) or the proof expires. Arms nothing by itself. Decimals are plain strings, as signed.
application/json
dataPreparedIntentrequired
expiresAtMsstringrequired
intentIdstringrequired
Exampled54daa1bcef482122fedd0b7c675ff7c
bad_request, bad_signature, proof_expired, proof_expiry, not_owner, trigger_not_enabled, bad_price, bad_trigger_order, trigger_already_crossed
application/json
errorErrorObjectrequired
codestringrequired
messagestringrequired
application/json
errorErrorObjectrequired
codestringrequired
messagestringrequired
application/json
errorErrorObjectrequired
codestringrequired
messagestringrequired
application/json
errorErrorObjectrequired
codestringrequired
messagestringrequired
too_many_pending, too_many_pending_intents, too_many_requests or rate_limited. Also 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
Gateway timeout: the service did not answer in time
application/json
errorErrorObjectrequired
codestringrequired
messagestringrequired

Example request

curl -X POST 'https://api.parchment.trade/triggers/prepare' \
  -H 'Content-Type: application/json' \
  -d '{
  "accountId": "0xad23e722f3542ae36c276c1b303e30ae77c840a84db89c7215fa87bf92006691",
  "expiresAtMs": "string",
  "intentId": "d54daa1bcef482122fedd0b7c675ff7c",
  "isLong": true,
  "marketId": "0x6e6238eb4f69bfcc3e884a7d20904eb0995ca2e42c95dc8560d5a417486ab645",
  "owner": "0x77b909b550ed11c45f1378c03c0954c0d77d320cdc938e35509564b1e505ce0d",
  "signature": "string",
  "stopLossWad": "string",
  "takeProfitWad": "string"
}'

const res = await fetch("https://api.parchment.trade/triggers/prepare", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    "accountId": "0xad23e722f3542ae36c276c1b303e30ae77c840a84db89c7215fa87bf92006691",
    "expiresAtMs": "string",
    "intentId": "d54daa1bcef482122fedd0b7c675ff7c",
    "isLong": true,
    "marketId": "0x6e6238eb4f69bfcc3e884a7d20904eb0995ca2e42c95dc8560d5a417486ab645",
    "owner": "0x77b909b550ed11c45f1378c03c0954c0d77d320cdc938e35509564b1e505ce0d",
    "signature": "string",
    "stopLossWad": "string",
    "takeProfitWad": "string"
  }),
});
const { data } = await res.json();

Example response (200)

application/json

{
  "data": {
    "expiresAtMs": "string",
    "intentId": "d54daa1bcef482122fedd0b7c675ff7c"
  }
}