Skip to main content

Local Action Signing

The two-step wallet flow (POST /actions/hash, then POST /actions) costs one extra HTTP round trip per action. The submit endpoint recomputes the signing hash from the submitted payload; there is no server-side state between the two calls. A client that reproduces the canonical bytes locally can therefore skip /actions/hash entirely and submit signed actions in one round trip.

The TypeScript SDK ships this as canonicalActionPayloadJson(), actionSigningHashHex(), deriveOrderIdHex(), and signAction() (see the @sentico-labs/sdk signing module). This page is the normative spec for any other language.

Hash definition​

signing_hash = blake3( "SENTICORE/ACTION_PAYLOAD/v1" || canonical_bytes )
  • blake3 with default parameters, 32-byte output.
  • The domain string is prepended as raw ASCII bytes (no length prefix).
  • canonical_bytes is the canonical JSON encoding of the action payload, UTF-8, defined below.

Sign the 32-byte hash with the wallet key. The backend accepts:

  • raw ECDSA over the 32-byte hash, and
  • EIP-191 personal_sign over the same 32-byte hash.

The submitted signature is 65 bytes in EVM order: r || s || v. Recovery byte v may be 0/1 or 27/28.

Canonical JSON encoding​

  1. No whitespace anywhere.
  2. Field order is the declaration order given in the tables below, NOT alphabetical. This is the single most common integration mistake: the canonicalPayload echoed by POST /actions/hash is alphabetically sorted for display; hashing that JSON produces a different, invalid hash.
  3. Field names are the canonical snake_case wire names.
  4. Optional fields are always present, serialized as null when absent — with one exception: client_order_id is omitted entirely when absent (it is never emitted as null). It appears in the canonical bytes only when you set it.
  5. Account ids: 0x + 40 lowercase hex chars. Order ids: 0x + 64 lowercase hex chars.
  6. Integers are serialized as bare JSON numbers (no quotes). Quantities and prices are u64 atomic units; use a big-integer type in languages where 2^53 is a concern.
  7. Enums: side is "Bid"/"Ask", book is "YES"/"NO"; time_in_force (gtc, ioc, fok, post_only), stp_mode (cancel_maker, cancel_taker, reject, skip_self), trigger_direction, conditional_kind are snake_case strings.
  8. The action is externally tagged: {"<Variant>":{...}}. The outcome place-order variant is canonically tagged PlaceOrder (the public request alias OutcomePlaceOrder is input-only and never part of the canonical bytes).

Envelope field order​

#FieldType
1accounthex(20)
2nonceu64
3nonce_reservation_idstring | null
4client_order_idstring (omitted when absent)
5tsu64 (unix ms)
6actiontagged object

client_order_id is optional. When present it appears here, between nonce_reservation_id and ts, and changes both the signing hash and the derived OrderId. When absent it is omitted from the bytes entirely (it is the one optional field that is not serialized as null), so the golden vectors below — none of which set it — remain byte-identical. A client that never sets client_order_id does not need to change anything.

Variant field order​

VariantFields in canonical order
SpotPlaceOrdermarket, side, price, qty, stp_mode, time_in_force, is_market, reduce_only, expires_at
PlaceOrder (outcome)market, book, side, price, qty, stp_mode, time_in_force, is_market, reduce_only, expires_at
Cancelorder_id
AmendOrderorder_id, new_qty
SpotQuoteReplacemarket, legs[]
QuoteReplacemarket, legs[]
spot legcancel_order_id, side, price, qty, stp_mode, time_in_force, is_market, reduce_only, expires_at
outcome legcancel_order_id, book, side, price, qty, stp_mode, time_in_force, is_market, reduce_only, expires_at

Golden vectors​

These vectors are asserted byte-for-byte by the backend test suite (senticore-types) and the TypeScript SDK test suite. Validate your implementation against all three before going live.

Vector 1: SpotPlaceOrder​

Canonical bytes:

{"account":"0x1111111111111111111111111111111111111111","nonce":4810,"nonce_reservation_id":null,"ts":1765500000000,"action":{"SpotPlaceOrder":{"market":7,"side":"Bid","price":998400,"qty":1000,"stp_mode":null,"time_in_force":"post_only","is_market":false,"reduce_only":false,"expires_at":null}}}

Signing hash:

0xc8d02209196c492de5b39c90d7efd356548784ddd464603913b59afab911b42f

Vector 2: Cancel​

Canonical bytes:

{"account":"0x1111111111111111111111111111111111111111","nonce":4811,"nonce_reservation_id":null,"ts":1765500000001,"action":{"Cancel":{"order_id":"0x2222222222222222222222222222222222222222222222222222222222222222"}}}

Signing hash:

0xaecabe7c50eaa0a1a6f59b75687b64dce6f96fcaef509319051baff0e78eb38a

Vector 3: SpotQuoteReplace (one replace leg, reserved nonce)​

Canonical bytes:

{"account":"0x1111111111111111111111111111111111111111","nonce":4812,"nonce_reservation_id":"res-1","ts":1765500000002,"action":{"SpotQuoteReplace":{"market":7,"legs":[{"cancel_order_id":"0x2222222222222222222222222222222222222222222222222222222222222222","side":"Bid","price":998500,"qty":1189,"stp_mode":null,"time_in_force":"post_only","is_market":false,"reduce_only":false,"expires_at":null}]}}}

Signing hash:

0x0b635be460cf6d9ae3a9fe11c1b5d5176c942e9b6139f88dac142baa1818584c

TypeScript example​

import {
  actionSigningHashHex,
  deriveOrderIdHex,
  signAction,
  type LocalActionPayload
} from "@sentico-labs/sdk";

const payload: LocalActionPayload = {
  account: "0x1111111111111111111111111111111111111111",
  nonce: 4810,
  ts: 1765500000000,
  action: {
    kind: "SpotPlaceOrder",
    market: 7,
    side: "Bid",
    price: 998400,
    qty: 1000,
    timeInForce: "post_only",
  },
};

const signedAction = signAction(payload, process.env.SENTICORE_PRIVATE_KEY!);

console.log({
  signingHash: actionSigningHashHex(payload),
  derivedOrderId: deriveOrderIdHex(payload),
});

await client.trading.submitSignedAction(signedAction, {
  idempotencyKey: "client-order-4810",
});

Nonce model (windowed replay protection)​

For locally signed actions, the signed nonce is part of the hash. The server cannot rewrite it after signing. The signing bytes and the v1 domain are unchanged — only the validation rule below changed; existing golden vectors and locally-signing clients keep working.

A signed nonce n is accepted if and only if it is inside the account's replay window and has not already been used:

  • nonceFloor <= n < nonceFloor + nonceWindow (currently nonceWindow = 256),
  • and n has not already been consumed or is not already in-flight.

nonceFloor is the lowest still-acceptable nonce (the next strict nonce). This means gaps and out-of-order submission are allowed: you may pipeline any unused nonces in the open window in any order, without waiting for an ack or pre-reserving a range. A strict, sequential client (nonceFloor, nonceFloor+1, …) is just the simplest valid case.

Reject classes (machine-readable code, with discovery fields):

  • nonce_below_floor — n < nonceFloor: permanently stale/consumed. Pick a fresh in-window nonce; do not retry the same value.
  • nonce_outside_window — n >= nonceFloor + nonceWindow: too far ahead. Retry after the floor advances (fill your lower nonces first).
  • nonce_replayed — n is in-window but already used/in-flight. Pick a different unused in-window nonce.
  • nonce_mismatch — legacy/uncategorized nonce reject.

Every nonce reject carries nonceFloor and nonceWindow so you can recompute the valid open interval, plus nextUsableNonce (= nonceFloor) as a convenience hint.

Example reject:

{
  "accepted": false,
  "ok": false,
  "seq": null,
  "derivedOrderId": null,
  "error": "nonce 4600 is below replay window; nonceFloor=4810 nonceWindow=256",
  "code": "nonce_below_floor",
  "nextUsableNonce": 4810,
  "nonceFloor": 4810,
  "nonceWindow": 256
}

Reservations are deprecated​

Nonce reservations existed only to escape the old strict-contiguous rule. Under the windowed model any unused in-window nonce is accepted, so reservations are no longer required. The reserve endpoint and nonceReservationId remain accepted for backward compatibility but are deprecated — new integrations should omit nonceReservationId (keep it absent or null) and simply pick in-window nonces.

Notes​

  • POST /actions/hash stays available as a debugging and reference endpoint; compare its hash against your local result during integration.
  • POST /actions/hash can fill nonce: 0 for its returned reference payload. That convenience does not apply to locally signed actions.
  • The SDK can hash BigInt values above 2^53-1, but submit-ready JSON objects reject values that JavaScript would round. Keep public-beta price/quantity atoms inside JS safe integers for the JSON path, or use a raw encoder that preserves the decimal bytes exactly.
  • deriveOrderIdHex(payload) uses blake3("SENTICORE/ORDER_ID/v1" || canonical_bytes) for place orders. For quote-replace place legs, use deriveQuoteReplaceOrderIdHex(payload, legIndex). Because client_order_id is part of canonical_bytes when present, setting it changes the derived OrderId. It influences the derived id only; it is not stored in order state or the state_root.
  • Any change to the canonical encoding will ship under a new domain string (.../v2); v1 vectors stay valid for the lifetime of the v1 domain.
Last updated on