> ## Documentation Index > Fetch the complete documentation index at: https://docs.derivadex.com/llms.txt > Use this file to discover all available pages before exploring further. # Signed Private Requests > Reference for submitting signed DerivaDEX requests, including request formats, intent fields, delegated sessions, replay-window fields, receipts, and errors. Signed private requests are wallet-authorized actions submitted to the operator through REST. They cover placing orders, modifying orders, canceling orders, canceling all orders in one strategy, updating profile settings, and requesting collateral or DDX withdrawals. ## Endpoints | Method | Path | Purpose | Body or response | | ------ | -------------------- | ------------------------------------------------------------------------------ | -------------------------------------------------- | | `GET` | `/v2/time` | Returns the operator time snapshot used before signing replay-window requests. | `serverTimeMs`, `timeValue`, and `clockTickLenMs`. | | `GET` | `/v2/encryption-key` | Returns the current operator public key for request encryption. | The public key used as the encryption recipient. | | `POST` | `/v2/request` | Accepts one signed and encrypted private request. | Encrypted bytes, not a JSON object. | ## Submission envelope The signed plaintext is a JSON object with request-type field `t` and content field `c`. ```json theme={null} { "t": "Order", "c": { "symbol": "ETHP", "strategy": "main", "side": "Bid", "orderType": 0, "nonce": "0x3137373038373530313938323238333436363300000000000000000000000000", "clientTimestampMs": 1770875019823, "recvWindowMs": 5000, "amount": "0.1", "price": "1800", "stopPrice": "0", "sessionKeySignature": null, "signature": "0x..." } } ``` | Field | Type | Meaning | | ----- | ------ | -------------------------------------------------------------------------------------------------------------------------------------- | | `t` | enum | Request type. Supported values are `Order`, `ModifyOrder`, `CancelOrder`, `CancelAll`, `ProfileUpdate`, `Withdraw`, and `WithdrawDDX`. | | `c` | object | Request content for the type named by `t`. | Encrypt the UTF-8 JSON bytes and send the encrypted byte payload to `POST /v2/request`. Do not wrap the encrypted bytes in another JSON object. ## Common content fields | Field | Applies to | Type | Meaning | | --------------------- | ------------------------------------------------ | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `nonce` | all request kinds | `bytes32` hex string | Uniqueness salt signed into the request. Clients should generate a fresh nonce for each new intent, but the operator does not use nonce order as the replay check. | | `clientTimestampMs` | all request kinds | integer milliseconds | Operator time snapshot value signed into the request. Fetch it from the same configured operator's `GET /v2/time` response before signing. | | `recvWindowMs` | all request kinds | integer milliseconds | Maximum signed replay window in milliseconds. Client helpers default to `5000`; the operator rejects `0` and values above `60000`. | | `signature` | all request kinds | hex string | EIP-712 signature for the fields in that request type. | | `sessionKeySignature` | order, modify-order, cancel, cancel-all requests | hex string or `null` | Delegated-session payload. When present, the delegated session key signs the request. | Replay-window fields are paired. Send both `clientTimestampMs` and `recvWindowMs`; sending only one returns `ReplayFieldMissing` or `InvalidRequestPayload` depending on the malformed field. Timestamps at least `1000ms` ahead of operator time are rejected, and expired requests fail before duplicate or collision handling. ## Order content `Order` places one order. | Field | Type | Meaning | | --------------------- | -------------------- | --------------------------------------------------------------------- | | `symbol` | string | Market symbol, such as `ETHP`. | | `strategy` | string | Trader strategy label. | | `side` | enum | `Bid` or `Ask`; EIP-712 signing uses `0` for `Bid` and `1` for `Ask`. | | `orderType` | enum integer | `0` limit, `1` market, `2` stop, `3` limit-post-only. | | `nonce` | `bytes32` hex string | Uniqueness salt signed into the request. | | `clientTimestampMs` | integer milliseconds | Operator time value from `GET /v2/time`, signed into `OrderParams`. | | `recvWindowMs` | integer milliseconds | Signed replay window. | | `amount` | decimal string | Order size, scaled at six decimal places for signing. | | `price` | decimal string | Limit price. Use `0` for market orders. | | `stopPrice` | decimal string | Stop trigger price. Use `0` when the order is not a stop order. | | `sessionKeySignature` | hex string or `null` | Delegated-session payload for session-key orders. | | `signature` | hex string | EIP-712 signature over `OrderParams`. | ## Modify-order content `ModifyOrder` atomically cancels one order and places the replacement order. | Field | Type | Meaning | | --------------------- | -------------------- | --------------------------------------------------------------------------- | | `orderHash` | hex string | Hash of the order intent to modify. | | `symbol` | string | Market symbol, such as `ETHP`. | | `strategy` | string | Trader strategy label. | | `side` | enum | `Bid` or `Ask`; EIP-712 signing uses `0` for `Bid` and `1` for `Ask`. | | `orderType` | enum integer | `0` limit, `1` market, `2` stop, `3` limit-post-only. | | `nonce` | `bytes32` hex string | Uniqueness salt signed into the request. | | `clientTimestampMs` | integer milliseconds | Operator time value from `GET /v2/time`, signed into `ModifyOrderParams`. | | `recvWindowMs` | integer milliseconds | Signed replay window. | | `amount` | decimal string | Replacement order size, scaled at six decimal places for signing. | | `price` | decimal string | Replacement limit price. Use `0` for market orders. | | `stopPrice` | decimal string | Replacement stop trigger price. Use `0` when the order is not a stop order. | | `sessionKeySignature` | hex string or `null` | Delegated-session payload for session-key modify requests. | | `signature` | hex string | EIP-712 signature over `ModifyOrderParams`. | ## Cancel-order content `CancelOrder` cancels one order by hash. | Field | Type | Meaning | | --------------------- | -------------------- | ------------------------------------------------------------------------- | | `symbol` | string | Market symbol. | | `orderHash` | hex string | Hash of the order intent to cancel. | | `nonce` | `bytes32` hex string | Uniqueness salt signed into the request. | | `clientTimestampMs` | integer milliseconds | Operator time value from `GET /v2/time`, signed into `CancelOrderParams`. | | `recvWindowMs` | integer milliseconds | Signed replay window. | | `sessionKeySignature` | hex string or `null` | Delegated-session payload for session-key cancels. | | `signature` | hex string | EIP-712 signature over `CancelOrderParams`. | ## Cancel-all content `CancelAll` cancels all orders for one strategy and symbol. | Field | Type | Meaning | | --------------------- | -------------------- | ----------------------------------------------------------------------- | | `symbol` | string | Market symbol. | | `strategy` | string | Strategy whose orders should be canceled. | | `nonce` | `bytes32` hex string | Uniqueness salt signed into the request. | | `clientTimestampMs` | integer milliseconds | Operator time value from `GET /v2/time`, signed into `CancelAllParams`. | | `recvWindowMs` | integer milliseconds | Signed replay window. | | `sessionKeySignature` | hex string or `null` | Delegated-session payload for session-key cancel-all requests. | | `signature` | hex string | EIP-712 signature over `CancelAllParams`. | ## Profile-update content `ProfileUpdate` changes trader-level profile settings. | Field | Type | Meaning | | ------------------------------ | -------------------- | --------------------------------------------------------------------------- | | `nonce` | `bytes32` hex string | Uniqueness salt signed into the request. | | `clientTimestampMs` | integer milliseconds | Operator time value from `GET /v2/time`, signed into `UpdateProfileParams`. | | `recvWindowMs` | integer milliseconds | Signed replay window. | | `payFeesInDdx` | boolean | Requested value for the trader's pay-fees-in-DDX setting. | | `referralAddress` | address or `null` | Optional one-time referral address mutation. | | `deniedDelegatedSessionUpdate` | object or `null` | Optional delegated-session deny-list update. | | `signature` | hex string | EIP-712 signature over `UpdateProfileParams`. | EIP-712 signing maps profile-update fields to `payFeesInDdxState`, `referralAddress`, `deniedDelegatedSessionAction`, `deniedDelegatedSessionAddress`, `deniedDelegatedSessionExpiry`, `nonce`, `clientTimestampMs`, and `recvWindowMs`. ### Delegated-session deny-list update | Form | Fields | Meaning | | ------ | --------------------- | ------------------------------------------------------------ | | Add | `delegated`, `expiry` | Denies a delegated session key until its Unix-second expiry. | | Remove | address string | Removes the delegated session key from the deny list. | | Empty | `null` | Leaves the deny list unchanged. | ## Withdraw content `Withdraw` requests a collateral withdrawal. | Field | Type | Meaning | | ------------------- | -------------------- | ---------------------------------------------------------------------- | | `strategyId` | string | Strategy label to withdraw from. | | `currency` | address | ERC-20 collateral token address. | | `amount` | decimal string | Amount to withdraw, scaled at six decimal places for signing. | | `nonce` | `bytes32` hex string | Uniqueness salt signed into the request. | | `clientTimestampMs` | integer milliseconds | Operator time value from `GET /v2/time`, signed into `WithdrawParams`. | | `recvWindowMs` | integer milliseconds | Signed replay window. | | `signature` | hex string | EIP-712 signature over `WithdrawParams`. | ## Withdraw-DDX content `WithdrawDDX` requests a DDX withdrawal. | Field | Type | Meaning | | ------------------- | -------------------- | ------------------------------------------------------------------------- | | `amount` | decimal string | Amount of DDX to withdraw, scaled at six decimal places for signing. | | `nonce` | `bytes32` hex string | Uniqueness salt signed into the request. | | `clientTimestampMs` | integer milliseconds | Operator time value from `GET /v2/time`, signed into `WithdrawDDXParams`. | | `recvWindowMs` | integer milliseconds | Signed replay window. | | `signature` | hex string | EIP-712 signature over `WithdrawDDXParams`. | ## Delegated sessions Delegated sessions are supported for order, modify-order, cancel-order, and cancel-all requests. | Field or value | Meaning | | --------------------- | ------------------------------------------------------------------------------------------------------------------- | | `sessionKeySignature` | Encoded delegated-session authorization payload included in the request content. | | Session signer | The session key signs the request hash when `sessionKeySignature` is present. | | Trader signer | The trader wallet signs the delegated-session payload that authorizes the session key. | | `expiry` | Unix timestamp after which the session key is no longer valid. | | `acl_scope` | Allowed session actions. Codes are `0` unrestricted, `1` order, `2` modify-order, `3` cancel-order, `4` cancel-all. | Delegated-session payload decode failures, expired payloads, and action-scope violations return `SignedRequestAuthenticationFailed`. A trusted deny-list rejection for a delegated-session signer returns `Forbidden`. ## Successful receipt Accepted requests return a receipt with `t: "Sequenced"` after trusted sequencing assigns a request index and the process observes the commit. The receipt is a signed sequencing acknowledgement, not a restart-safe retry record. After an ambiguous send or process loss, recover through committed-state or domain queries such as request index, order hash, transaction state, or event state. ```json theme={null} { "t": "Sequenced", "c": { "nonce": "0x...", "requestHash": "0x...", "requestIndex": 123, "sender": "0x...", "enclaveSignature": "0x..." } } ``` | Receipt field | Type | Meaning | | ------------------ | -------------------- | ---------------------------------------------------- | | `nonce` | `bytes32` hex string | Nonce from the accepted request. | | `requestHash` | hex string | Hash of the accepted request. | | `requestIndex` | integer | Operator sequencing index assigned to the request. | | `sender` | address | Trader address recovered from the request signature. | | `enclaveSignature` | hex string | Operator enclave signature over the receipt. | ## Safety failures Trusted validation failures return an HTTP error body. They do not allocate a `requestIndex`. ```json theme={null} { "error_reason": "SafetyFailure", "safety_failure": "OMFLessThanIMF", "message": "Safety failure encountered during sequencing validation" } ``` | Error field | Type | Meaning | | ---------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------- | | `error_reason` | enum | Always `SafetyFailure` for trusted validation failures, except safety-specific dependency failures such as current mark-price unavailability. | | `safety_failure` | enum | Safety-failure reason. See [Error Reference](/reference-public/error-reference). | | `message` | string | Human-readable rejection detail. | ## HTTP errors These errors happen before the request returns a sequenced receipt. The JSON discriminator is `error_reason`. Transport failures without an HTTP response have no `error_reason`. A response-body read failure after `POST /v2/request` is also unknown completion. Automatic retry must reuse the same signed JSON body while the replay window remains valid. | Error reason | Status | Meaning | | ----------------------------------- | -----: | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `InvalidRequestPayload` | `400` | The encrypted body decrypted to malformed request content, including duplicate keys, invalid JSON, wrong field types, `null` replay fields, negative replay fields, or out-of-range replay fields. | | `ReplayFieldMissing` | `400` | `clientTimestampMs` or `recvWindowMs` is missing from a submitted signed request. | | `ReplayWindowZero` | `400` | `recvWindowMs` is `0`. | | `ReplayWindowTooLarge` | `400` | `recvWindowMs` is above `60000`. | | `ReplayTimestampOverflow` | `400` | The replay-window expiry cannot be represented safely. | | `SignedRequestAuthenticationFailed` | `401` | The signature, current EIP-712 type, or delegated-session proof does not authorize the submitted request. | | `Forbidden` | `403` | Trusted trader deny-list state rejected the delegated-session signer. | | `NonceCollision` | `409` | The same trader, request family, and nonce already have a different retained signed identity. | | `NoChangesRequested` | `409` | A profile-update request was proven to be a no-op before request indexing. No receipt or `requestIndex` is created. | | `ReplayTimestampExpired` | `412` | The signed replay window has expired. | | `ReplayTimestampTooFarInFuture` | `412` | `clientTimestampMs` is at least `1000ms` ahead of operator time. | | `NotAcceptingRequests` | `421` | The operator cannot currently accept this request path. | | `InvalidEncryption` | `422` | The operator could not decrypt the submitted bytes. | | `SafetyFailure` | `422` | Request validation rejected the action before normal sequencing. | | `RateLimit` | `429` | The trader or gateway request bucket was exceeded. | | `InternalServerError` | `500` | The operator failed before returning a final result. | | `TrustedTimeUnavailable` | `503` | The operator cannot prove trusted replay-validation time. | | `ServiceUnavailable` | `503` | A required dependency was not ready, including current mark-price availability. | ## Related references * [REST API](/api-reference/rest) * [How to Sign DerivaDEX Requests with EIP-712](/how-to-guides/sign-requests-with-eip712) * [How to Encrypt Requests for the Operator](/how-to-guides/encrypt-operator-requests) * [Rate Limits and Access Tiers](/reference-public/rate-limits-and-access-tiers) * [Error Reference](/reference-public/error-reference)