Signed Private Requests - DerivaDEX Docs

Signed private requests are wallet-authorized actions submitted to the operator through REST. They cover placing orders, canceling orders, canceling all orders in one strategy, updating profile settings, and requesting collateral withdrawals.

Endpoints

Method	Path	Purpose	Body or response
`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",
    "amount": "0.1",
    "price": "1800",
    "stopPrice": "0",
    "sessionKeySignature": null,
    "signature": "0x..."
  }
}

Field	Type	Meaning
`t`	enum	Request type. Supported values are `Order`, `CancelOrder`, `CancelAll`, `ProfileUpdate`, and `Withdraw`.
`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	Monotonically increasing request nonce for the signer.
`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.
`client_timestamp_ms`	gateway replay-window deployments	integer milliseconds	Client wall-clock timestamp included in the signed payload.
`recv_window_ms`	gateway replay-window deployments	integer milliseconds	Maximum age window for the signed payload.

Replay-window fields are paired. Send both client_timestamp_ms and recv_window_ms when the target deployment enforces replay windows; sending only one is malformed. The current public cap for recv_window_ms is 60000, and timestamps more than 1000ms ahead of server time are rejected.

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	Monotonically increasing signer nonce.
`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`.

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	Monotonically increasing signer nonce.
`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	Monotonically increasing signer nonce.
`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	Monotonically increasing signer nonce.
`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, and nonce.

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	Monotonically increasing signer nonce.
`signature`	hex string	EIP-712 signature over `WithdrawParams`.

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 expiry or action-scope violations return 403 Forbidden. A denied delegated-session signer also returns 403 Forbidden.

Successful receipt

Accepted requests return a receipt with t: "Sequenced".

{
  "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-failure receipt

A request can also return a structured safety-failure receipt.

{
  "t": "SafetyFailure",
  "c": {
    "message": "Safety failure encountered during sequencing validation",
    "inner": "OMFLessThanIMF"
  }
}

Receipt field	Type	Meaning
`message`	string	Human-readable rejection detail.
`inner`	enum	Safety-failure reason. See Error Reference.

HTTP errors

These errors happen before the request returns a sequenced or safety-failure receipt.

Error reason	Status	Meaning
`InvalidRequestPayload`	`400`	The encrypted body decrypted to malformed request content, or required replay-window fields were missing or only partly populated on deployments that enforce them.
`SignerNotFound`	`401`	Signature recovery succeeded, but the signer is not a recognized trader.
`Forbidden`	`403`	Delegated-session expiry, deny-list, action-scope, or policy authorization rejected the request.
`KycNotFound`	`404`	Required KYC state is missing or expired.
`IllegalNonce`	`412`	The signer nonce did not increase monotonically.
`ExpiredTimestamp`	`412`	The signed replay window has expired on deployments that enforce replay windows.
`FutureTimestamp`	`412`	The client timestamp is too far ahead of server time on deployments that enforce replay windows.
`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.
`ServiceUnavailable`	`503`	A required dependency was not ready, including current mark-price availability.

​Endpoints

​Submission envelope

​Common content fields

​Order content

​Cancel-order content

​Cancel-all content

​Profile-update content

​Delegated-session deny-list update

​Withdraw content

​Delegated sessions

​Successful receipt

​Safety-failure receipt

​HTTP errors

​Related references