Skip to content
parchmentdocs
Open app

Transactions

Transaction-kind builders and gas sponsorship of two-step order transactions

post/sponsor

Request body (required)

SponsorRequest · application/json
  • expiresAtMsstringrequired

    Unix ms after which the service refuses the proof; at most 120 s after its clock.

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

    The session key: a live delegate of the account the kind trades on.

    Example0x77b909b550ed11c45f1378c03c0954c0d77d320cdc938e35509564b1e505ce0d
  • senderSignaturestringrequired

    Base64 Ed25519 UserSignature by sender of the session proof personal message (Parchment session-key sponsorship v1\nsender: {sender}\naccountId: {account}\ntxKindSha256: {sha256}\nexpiresAtMs: {expiresAtMs}): the signature signPersonalMessage returns.

  • txKindBase64stringrequired

    Base64 transaction-kind bytes (the txBytesBase64 of /transactions/{action}).

Responses

  • Gas sponsorship of a session-key (delegate) trade: request-open-as-delegate, request-close-as-delegate (Close All: up to 16 closes in one transaction), cancel-order-as-delegate (up to 16), emergency-close-as-delegate, close-retired-as-delegate. Owner actions are not sponsored (the wallet pays). Body: sender (the session key address, a live delegate of the account the kind trades on), txKindBase64 (the txBytesBase64 from /transactions/{action}), senderSignature (base64 Ed25519 UserSignature by sender, from signPersonalMessage, of the five lines "Parchment session-key sponsorship v1", "sender: <sender>", "accountId: <account>", "txKindSha256: <sha256>", "expiresAtMs: <decimal>" joined by \n, no trailing newline; addresses 0x + 64 lowercase hex, txKindSha256 the lowercase hex SHA-256 of the kind bytes) and expiresAtMs (n-suffixed decimal unix ms, later than the service clock and at most 120000 ms after it); no other field. Returns txBytesBase64 (full TransactionData with the sponsor as gas owner, address-balance gas, single-use, valid in validEpoch only), sponsorSignature, digest, sender, sponsor, action, gasMode, gasBudget, gasPrice, estimatedGas, validEpoch. The session key signs txBytesBase64 unchanged; execute with [sessionSignature, sponsorSignature]. An identical request while its signature is unresolved returns the same transaction.

    application/json

    • dataSponsoredrequired

      The sponsor-signed TransactionData.

      • actionstringrequired

        A transaction action the sponsor pays gas for.

        One ofrequest-openrequest-open-as-delegaterequest-closerequest-close-as-delegatecancel-ordercancel-order-as-delegateemergency-closeemergency-close-as-delegateclose-retiredclose-retired-as-delegate
      • digeststringrequired
        Pattern^[1-9A-HJ-NP-Za-km-z]{32,44}$
        ExamplecgQt9nJzVJejFdAFSrw36bZHABJGw7sEWRF8Vd43uZnz
      • estimatedGasstringrequired

        Simulated computation + storage (MIST), before the storage rebate.

        Pattern^-?(0|[1-9][0-9]*)n$
        Example3976000n
      • gasBudgetstringrequired
        Pattern^-?(0|[1-9][0-9]*)n$
        Example50000000n
      • gasModestringrequired

        How the sponsor pays gas.

        One ofaddress-balance
      • gasPricestringrequired
        Pattern^-?(0|[1-9][0-9]*)n$
        Example750n
      • senderstringrequired
        Pattern^0x[0-9a-f]{64}$
        Example0x77b909b550ed11c45f1378c03c0954c0d77d320cdc938e35509564b1e505ce0d
      • sponsorstringrequired
        Pattern^0x[0-9a-f]{64}$
        Example0x77b909b550ed11c45f1378c03c0954c0d77d320cdc938e35509564b1e505ce0d
      • sponsorSignaturestringrequired

        Base64 sponsor UserSignature; execute with [user_signature, sponsor_signature].

      • txBytesBase64stringrequired

        Base64 BCS TransactionData the wallet signs as-is.

      • validEpochstringrequired

        The only epoch the transaction can execute in.

        Pattern^-?(0|[1-9][0-9]*)n$
        Example912n

Example request

curl -X POST 'https://api.parchment.trade/sponsor' \
  -H 'Content-Type: application/json' \
  -d '{
  "expiresAtMs": "1796677200000n",
  "sender": "0x77b909b550ed11c45f1378c03c0954c0d77d320cdc938e35509564b1e505ce0d",
  "senderSignature": "string",
  "txKindBase64": "string"
}'
const res = await fetch("https://api.parchment.trade/sponsor", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    "expiresAtMs": "1796677200000n",
    "sender": "0x77b909b550ed11c45f1378c03c0954c0d77d320cdc938e35509564b1e505ce0d",
    "senderSignature": "string",
    "txKindBase64": "string"
  }),
});
const { data } = await res.json();

Example response (200)

application/json
{
  "data": {
    "action": "request-open",
    "digest": "cgQt9nJzVJejFdAFSrw36bZHABJGw7sEWRF8Vd43uZnz",
    "estimatedGas": "3976000n",
    "gasBudget": "50000000n",
    "gasMode": "address-balance",
    "gasPrice": "750n",
    "sender": "0x77b909b550ed11c45f1378c03c0954c0d77d320cdc938e35509564b1e505ce0d",
    "sponsor": "0x77b909b550ed11c45f1378c03c0954c0d77d320cdc938e35509564b1e505ce0d",
    "sponsorSignature": "string",
    "txBytesBase64": "string",
    "validEpoch": "912n"
  }
}
post/sponsor/execute

Request body (required)

SponsorExecuteRequest · application/json
  • signaturesstring[]required
  • txBytesBase64stringrequired

Responses

  • application/json

    • dataSponsorExecutedrequired
      • digeststringrequired
        Pattern^[1-9A-HJ-NP-Za-km-z]{32,44}$
        ExamplecgQt9nJzVJejFdAFSrw36bZHABJGw7sEWRF8Vd43uZnz
      • effectsBcsBase64stringrequired
      • orderIdsstring[]required
      • successbooleanrequired

Example request

curl -X POST 'https://api.parchment.trade/sponsor/execute' \
  -H 'Content-Type: application/json' \
  -d '{
  "signatures": [],
  "txBytesBase64": "string"
}'
const res = await fetch("https://api.parchment.trade/sponsor/execute", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    "signatures": [],
    "txBytesBase64": "string"
  }),
});
const { data } = await res.json();

Example response (200)

application/json
{
  "data": {
    "digest": "cgQt9nJzVJejFdAFSrw36bZHABJGw7sEWRF8Vd43uZnz",
    "effectsBcsBase64": "string",
    "orderIds": [
      "0x8a79598616df8d6e8de46f0234cf3d4e468c05fa00ed82fb783ecc43823555d1"
    ],
    "success": true
  }
}

Build a transaction

post/transactions/{action}

Path parameters

  • actionstringrequired

    open-account, transfer-account, deposit, withdraw, request-open, request-open-as-delegate, request-close, request-close-as-delegate, cancel-order, cancel-order-as-delegate, expire-order, emergency-close, emergency-close-as-delegate, close-retired, close-retired-as-delegate, sweep-surplus, claim-pending-mint, harvest, bind-referrer, bind-trading-referrer, register-builder, create-builder, set-builder-fee, set-builder-create-fee, pause-builder, resume-builder, transfer-builder, approve-builder, revoke-builder-approval, set-builder-payout, stake, unstake, claim, claim-daily, open-crate, open-crates, claim-quest, collect-mint, release-unlocked, exit-early, exit-early-bounded, install-treasury, auth-register, game-attach, grant-delegate, revoke-delegate, grant-close-delegate, grant-session-and-trigger, or revoke-session-and-trigger. The keeper-only award-achievement, complete-quest, grant-season-reward, liquidate, liquidate-retired, and sweep are refused with 403 keeper_only

    One ofopen-accounttransfer-accountdepositwithdrawrequest-openrequest-open-as-delegaterequest-closerequest-close-as-delegatecancel-ordercancel-order-as-delegateexpire-orderemergency-closeemergency-close-as-delegateclose-retiredclose-retired-as-delegatesweep-surplusclaim-pending-mintharvestbind-referrerbind-trading-referrerregister-builderset-builder-payoutcreate-builderset-builder-feeset-builder-create-feepause-builderresume-buildertransfer-builderapprove-builderrevoke-builder-approvalstakeunstakeclaimclaim-dailyopen-crateopen-cratesclaim-questcollect-mintrelease-unlockedexit-earlyexit-early-boundedinstall-treasuryauth-registergame-attachgrant-delegaterevoke-delegategrant-close-delegategrant-session-and-triggerrevoke-session-and-trigger

Request body (required)

PublicTxInput · application/json

The action's typed input: the PublicTxInput branch titled with the path's action, camelCase, every integer an n-suffixed decimal string ("5000000n").

The body of POST /transactions/{action}: the input of the path's action (the anyOf branch whose title is that action, or x-parchment-action-inputs[action]). camelCase, every integer an n-suffixed decimal string ("5000000n").

One of 49 shapes

Responses

  • Transaction-kind bytes (txBytesBase64) and the Move calls they make. claim-daily, claim-quest and open-crate grant XP/cosmetics only and return no coin. collect-mint issues the pending fee-backed achievement reward into the owner's locked ledger (a 7-day lock, then a 30-day linear vest); nothing is spendable at collection. release-unlocked (sender, optional who, default the sender; anyone may send it) pays the vested part to the ledger's owner, never to the caller. exit-early (sender only) pays the vested part in full and the unvested remainder less a penalty that falls linearly from 50% at the end of the lock to 0% at the end of the vest (forfeits go to stakers). exit-early-bounded (sender, unlocks, maxPenalty) exits exactly the quoted ledger entries (the game profile's earlyExitUnlocks) and aborts on chain (locked_mint::EPenaltyAboveMax, 5) if it would forfeit more than maxPenalty (pass earlyExitPenaltyNow); neither exit is sponsored. request-open* and request-close* carry the two-step order note. emergency-close* and close-retired* push the signed Lazer update into the market's price storage first and quote with the same update; expire-order quotes without the push. The trading pause, the close pause and a market's opensPaused/closesPaused stop opens; other category pauses stop only their category, and pause-all sets every category. No pause stops an exit: request-close*, emergency-close* and close-retired* run under every pause, and only the market's oracle kill switch stops them (request-close* aborts order::ERequestsPaused, 15; the others abort trade::EOracleKilled, 20); the bytes are still returned. liquidate, liquidate-retired and sweep are 403 keeper_only. Cancel, expire, session arm and force_close_session always run; harvest is blocked. A pending fill under the trading or close pause refunds with outcome 5 (paused), under the kill switch with outcome 6 (killed); both refund the exec fee. sponsor and an incoming txKind are rejected.

    application/json

    • dataBuiltTxrequired

      The unsigned transaction and the Move calls it makes.

      • commandsMoveCallView[]required
      • notestring | null

        Free-text guidance (e.g. how a two-step order is filled); null for most actions.

      • txBytesBase64stringrequired

        The BCS TransactionKind (a programmable transaction), base64.

Example request

curl -X POST 'https://api.parchment.trade/transactions/open-account' \
  -H 'Content-Type: application/json' \
  -d '{
  "sender": "0x77b909b550ed11c45f1378c03c0954c0d77d320cdc938e35509564b1e505ce0d",
  "shared": {
    "0x0000000000000000000000000000000000000000000000000000000000000006": "1n"
  }
}'
const res = await fetch("https://api.parchment.trade/transactions/open-account", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    "sender": "0x77b909b550ed11c45f1378c03c0954c0d77d320cdc938e35509564b1e505ce0d",
    "shared": {
      "0x0000000000000000000000000000000000000000000000000000000000000006": "1n"
    }
  }),
});
const { data } = await res.json();

Example response (200)

application/json
{
  "data": {
    "commands": [
      {
        "function": "string",
        "module": "string",
        "package": "string",
        "typeArguments": [
          "0xdba34672e30cb065b1f93e3ab55318768fd6fef66c15942c9f7cb846e2f900e7::usdc::USDC"
        ]
      }
    ],
    "note": "string",
    "txBytesBase64": "string"
  }
}