Signed Private Requests - DerivaDEX Docs

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.

{
  "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.

{
  "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.

{
  "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.
`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.

​Endpoints

​Submission envelope

​Common content fields

​Order content

​Modify-order content

​Cancel-order content

​Cancel-all content

​Profile-update content

​Delegated-session deny-list update

​Withdraw content

​Withdraw-DDX content

​Delegated sessions

​Successful receipt

​Safety failures

​HTTP errors

​Related references