Skip to content
parchmentdocs
Open app

Orders

Keeper-filled two-step order requests

Account orders

get/accounts/{owner}/orders

Path parameters

  • ownerstringrequired

    Wallet address

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

Query parameters

  • statusstring

    pending, final, unfilled, or all. unfilled: finalized orders that never traded (cancelled, expired, refunded, void), paged like final; a service that predates it answers 400 bad_request.

    One ofpendingfinalunfilledall
  • 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
  • cursorstring

    Opaque cursor from the previous page's nextCursor.

    Example0xc00d9a508112ec1dff7df53f35f096e26af4ec600dc291264b483d27aeb18b75

Responses

  • Two-step order requests for the owner ({ orders: Order[], nextCursor }). Order is { orderId, accountId, owner, requester, marketId, kind: open|close, isLong, margin, leverage, positionId, acceptablePriceWad (advisory: stored and emitted, never enforced at fill), minFactorBps, maxFeeBps, execFee, requestedMs, fillDeadlineMs, cancelAfterMs, emergencyAfterMs, status: pending|filled|liquidated|cancelled|expired|refunded|void|emergency_closed|unknown, reason: null|paused|killed|closed|fee|risk|band|session|retry|revoked (revoked = outcome 15 OUTCOME_REFUND_REVOKED: the submitting delegate was no longer live; looked up for at most 8 orders per read within 2 s, else null; band is reserved: outcome 12 OUTCOME_REFUND_BAND is kept, not renumbered, for history only; there is no signed band, two-step fills are at the plain mid and no fill is refunded with it any more; session = outcome 13 OUTCOME_SESSION_CLOSED: refunded because the equity session force close was pending or already closed the position; retry = outcome 14 OUTCOME_REFUND_LIQ_PAUSED: refunded in full, exec fee included, because the bounded liquidated-position reconciliation could not drain the backlog; nothing is paused and the request can be retried; the retired outcome 4 reads unknown with a null reason), fillPriceWad, fillPriceTsMs, fillLatencyMs, refund, requestDigest, finalDigest, finalizedMs }. Every integer, fillLatencyMs included, is an n-suffixed decimal string ("5000000n"); request-side fields can be null until the request event is indexed. nextCursor is an opaque page token or null. The service's typed response, as public camelCase JSON.

    application/json

    • dataOrdersPagerequired

      Newest request first.

      • nextCursorstring | null

        <sort_ms>:<order_id> of the last row.

      • ordersOrder[]required

Example request

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

Example response (200)

application/json
{
  "data": {
    "nextCursor": "string",
    "orders": [
      {
        "acceptablePriceWad": "74250000000000000000n",
        "accountId": "0xad23e722f3542ae36c276c1b303e30ae77c840a84db89c7215fa87bf92006691",
        "cancelAfterMs": "30000n",
        "emergencyAfterMs": "15000n",
        "execFee": "800000n",
        "execFeeRefunded": "800000n",
        "feeOwed": "800000n",
        "fillDeadlineMs": "1796677200000n",
        "fillLatencyMs": "1200n",
        "fillPriceTsMs": "1796677200000n",
        "fillPriceWad": "74250000000000000000n",
        "finalDigest": "9QFEqkR62F5JgU4sGyDeZnHqCs6ZDHCe5GbZmYPwvH5Q",
        "finalizedMs": "1796677200000n",
        "isLong": true,
        "kind": "open",
        "leverage": "10n",
        "margin": "100000000n",
        "marketId": "0x6e6238eb4f69bfcc3e884a7d20904eb0995ca2e42c95dc8560d5a417486ab645",
        "maxFeeBps": "8n",
        "minFactorBps": "10000n",
        "orderId": "0x8a79598616df8d6e8de46f0234cf3d4e468c05fa00ed82fb783ecc43823555d1",
        "owner": "0x77b909b550ed11c45f1378c03c0954c0d77d320cdc938e35509564b1e505ce0d",
        "positionId": "1042n",
        "reason": "paused",
        "refund": "100000000n",
        "requestDigest": "2Cf5C9Hf1FJNNQy1d637AK2z64rtUUkU6GPmHh9ncA2B",
        "requestedMs": "1796677200000n",
        "requester": "0x77b909b550ed11c45f1378c03c0954c0d77d320cdc938e35509564b1e505ce0d",
        "status": "pending"
      }
    ]
  }
}

Live order stream for an owner (SSE)

get/accounts/{owner}/orders/stream

Path parameters

  • ownerstringrequired

    Owner wallet address (0x-prefixed Sui address)

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

Responses

  • Server-Sent Events: the owner's two-step orders as they land, and the owner's deposits and withdrawals. No retry hint and no event ids: the stream opens with a heartbeat { timestampMs } at once, then one every 10 s. event order: { type: "landed", source, owner, orderId, marketId, side, size, positionId, outcome, reason, fillPrice, priceTs, txDigest }: source is keeper (the filler's own landed transaction, provisional) or indexer (the indexed finalize, authoritative; an order usually arrives from both); side is long, short or null when unknown; outcome is filled or refunded; size (the order's margin, USDC base units), positionId (null for refunds) and fillPrice (1e18-scaled, null when refunded) are plain decimal strings or null; priceTs is a number of milliseconds or null; reason is the refund reason or order status, null when filled. event funds: { kind, owner, accountId, amount, txDigest }: kind is deposit or withdraw, amount a plain decimal string in USDC base units. event reset {}: events may have been missed (a slow reader or a reconnect upstream); refetch the owner's orders and account. The stream closes after 54 to 60 minutes or after 30 s of downstream backpressure; EventSource then reconnects after its default delay, and nothing missed in between is replayed (refetch the owner's orders and account on reconnect).

    text/event-stream

    string

Example request

curl -N 'https://api.parchment.trade/accounts/0x77b909b550ed11c45f1378c03c0954c0d77d320cdc938e35509564b1e505ce0d/orders/stream' \
  -H 'Accept: text/event-stream'
const events = new EventSource("https://api.parchment.trade/accounts/0x77b909b550ed11c45f1378c03c0954c0d77d320cdc938e35509564b1e505ce0d/orders/stream");
events.onmessage = (event) => console.log(JSON.parse(event.data));

Example response (200)

text/event-stream
data: "string"

Submit an order digest hint

post/orders/digest-hint

Request body (required)

DigestHintRequest · application/json
  • digeststringrequired

    Non-empty base58 transaction digest.

    ExamplecgQt9nJzVJejFdAFSrw36bZHABJGw7sEWRF8Vd43uZnz

Responses

  • application/json

    • dataHintAcceptedrequired
      • orderIdsstring[]required

Example request

curl -X POST 'https://api.parchment.trade/orders/digest-hint' \
  -H 'Content-Type: application/json' \
  -d '{
  "digest": "cgQt9nJzVJejFdAFSrw36bZHABJGw7sEWRF8Vd43uZnz"
}'
const res = await fetch("https://api.parchment.trade/orders/digest-hint", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    "digest": "cgQt9nJzVJejFdAFSrw36bZHABJGw7sEWRF8Vd43uZnz"
  }),
});
const { data } = await res.json();

Example response (200)

application/json
{
  "data": {
    "orderIds": [
      "0x8a79598616df8d6e8de46f0234cf3d4e468c05fa00ed82fb783ecc43823555d1"
    ]
  }
}

Order

get/orders/{orderId}

Path parameters

  • orderIdstringrequired

    OrderRequest object id

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

Responses

  • One two-step order ({ order: Order }, same shape as the account list). Poll it until status != pending.

    application/json

    • dataOrderResponserequired
      • orderOrderrequired

        One two-step order request.

        • acceptablePriceWadstring | null

          Scaled by 1e18 (WAD).

          Pattern^-?(0|[1-9][0-9]*)n$
          Example74250000000000000000n
        • accountIdstringrequired
          Pattern^0x[0-9a-f]{64}$
          Example0xad23e722f3542ae36c276c1b303e30ae77c840a84db89c7215fa87bf92006691
        • cancelAfterMsstring | null

          Milliseconds.

          Pattern^-?(0|[1-9][0-9]*)n$
          Example30000n
        • emergencyAfterMsstring | null

          Milliseconds.

          Pattern^-?(0|[1-9][0-9]*)n$
          Example15000n
        • execFeestring | null
          Pattern^-?(0|[1-9][0-9]*)n$
          Example800000n
        • execFeeRefundedstring | null
          Pattern^-?(0|[1-9][0-9]*)n$
          Example800000n
        • feeOwedstring | null
          Pattern^-?(0|[1-9][0-9]*)n$
          Example800000n
        • fillDeadlineMsstring | null

          Milliseconds.

          Pattern^-?(0|[1-9][0-9]*)n$
          Example1796677200000n
        • fillLatencyMsstring | null

          finalized_ms - requested_ms of a filled or liquidated order.

          Pattern^-?(0|[1-9][0-9]*)n$
          Example1200n
        • fillPriceTsMsstring | null

          Milliseconds.

          Pattern^-?(0|[1-9][0-9]*)n$
          Example1796677200000n
        • fillPriceWadstring | null

          Scaled by 1e18 (WAD).

          Pattern^-?(0|[1-9][0-9]*)n$
          Example74250000000000000000n
        • finalDigeststring | null
          Pattern^[1-9A-HJ-NP-Za-km-z]{32,44}$
          Example9QFEqkR62F5JgU4sGyDeZnHqCs6ZDHCe5GbZmYPwvH5Q
        • finalizedMsstring | null

          Milliseconds.

          Pattern^-?(0|[1-9][0-9]*)n$
          Example1796677200000n
        • isLongboolean | null
        • kindstringrequired
          One ofopenclose
        • leveragestring | null
          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
        • maxFeeBpsstring | null

          Basis points (1/10000).

          Pattern^-?(0|[1-9][0-9]*)n$
          Example8n
        • minFactorBpsstring | null

          Basis points (1/10000).

          Pattern^-?(0|[1-9][0-9]*)n$
          Example10000n
        • orderIdstringrequired
          Pattern^0x[0-9a-f]{64}$
          Example0x8a79598616df8d6e8de46f0234cf3d4e468c05fa00ed82fb783ecc43823555d1
        • ownerstringrequired
          Pattern^0x[0-9a-f]{64}$
          Example0x77b909b550ed11c45f1378c03c0954c0d77d320cdc938e35509564b1e505ce0d
        • positionIdstring | null
          Pattern^-?(0|[1-9][0-9]*)n$
          Example1042n
        • reasonnull | string
        • refundstring | null
          Pattern^-?(0|[1-9][0-9]*)n$
          Example100000000n
        • requestDigeststring | null
          Pattern^[1-9A-HJ-NP-Za-km-z]{32,44}$
          Example2Cf5C9Hf1FJNNQy1d637AK2z64rtUUkU6GPmHh9ncA2B
        • requestedMsstring | null

          Milliseconds.

          Pattern^-?(0|[1-9][0-9]*)n$
          Example1796677200000n
        • requesterstring | null

          Sender of the request (the owner or a delegate).

          Pattern^0x[0-9a-f]{64}$
          Example0x77b909b550ed11c45f1378c03c0954c0d77d320cdc938e35509564b1e505ce0d
        • statusstringrequired

          Outcome of a two-step order request.

          One ofpendingfilledliquidatedcancelledexpiredrefundedvoidemergency_closedunknown

Example request

curl 'https://api.parchment.trade/orders/0x8a79598616df8d6e8de46f0234cf3d4e468c05fa00ed82fb783ecc43823555d1'
const res = await fetch("https://api.parchment.trade/orders/0x8a79598616df8d6e8de46f0234cf3d4e468c05fa00ed82fb783ecc43823555d1");
const { data } = await res.json();

Example response (200)

application/json
{
  "data": {
    "order": {
      "acceptablePriceWad": "74250000000000000000n",
      "accountId": "0xad23e722f3542ae36c276c1b303e30ae77c840a84db89c7215fa87bf92006691",
      "cancelAfterMs": "30000n",
      "emergencyAfterMs": "15000n",
      "execFee": "800000n",
      "execFeeRefunded": "800000n",
      "feeOwed": "800000n",
      "fillDeadlineMs": "1796677200000n",
      "fillLatencyMs": "1200n",
      "fillPriceTsMs": "1796677200000n",
      "fillPriceWad": "74250000000000000000n",
      "finalDigest": "9QFEqkR62F5JgU4sGyDeZnHqCs6ZDHCe5GbZmYPwvH5Q",
      "finalizedMs": "1796677200000n",
      "isLong": true,
      "kind": "open",
      "leverage": "10n",
      "margin": "100000000n",
      "marketId": "0x6e6238eb4f69bfcc3e884a7d20904eb0995ca2e42c95dc8560d5a417486ab645",
      "maxFeeBps": "8n",
      "minFactorBps": "10000n",
      "orderId": "0x8a79598616df8d6e8de46f0234cf3d4e468c05fa00ed82fb783ecc43823555d1",
      "owner": "0x77b909b550ed11c45f1378c03c0954c0d77d320cdc938e35509564b1e505ce0d",
      "positionId": "1042n",
      "reason": "paused",
      "refund": "100000000n",
      "requestDigest": "2Cf5C9Hf1FJNNQy1d637AK2z64rtUUkU6GPmHh9ncA2B",
      "requestedMs": "1796677200000n",
      "requester": "0x77b909b550ed11c45f1378c03c0954c0d77d320cdc938e35509564b1e505ce0d",
      "status": "pending"
    }
  }
}