Signing Direct Requests

The recommended way to submit signed exchange actions is through ExchangeClient.

Use direct signing only when implementing a custom HTTP client or integrating the Exchange API without the SDK client wrapper.

Direct signing requires exact agreement on:

• Action type

• Field names

• Field order

• Solidity integer widths

• Addresses

• Numeric conversion

• Chain ID

• Verifying contract

• EIP-712 domain

Changing any signed field after calculating the digest invalidates the signature.

EIP-712 domain

Signed exchange actions use this domain:

name: GammaSwap Exchange
version: 2
chainId: request chain ID
verifyingContract: exchange verifying contract

The domain prevents a signature from being reused against another chain or exchange deployment.

Signed request wrapper

Most signed HTTP endpoints use this outer structure:

{
  "action": {},
  "chainId": "84532",
  "orderHash": "0x...",
  "signature": "0x..."
}

The action field depends on the endpoint:

Endpoint	Action field
POST /orders	order
POST /cancels	cancel
POST /cancel-replace	cancelReplace
POST /withdrawals	withdrawal
POST /claim	claim
POST /agents/approve	approval
POST /agents/revoke	revocation

The field name orderHash is historical.

It contains the EIP-712 digest of the signed action, even when the action is a cancel, withdrawal, claim, approval, or revocation.

It is not a hash of the outer HTTP request body and does not include signature.

Signature types

Value	Type	Meaning
0	EOA	The sender signs directly
4	Agent	An approved agent signs for a master account

Signing process

A direct client signs an action in this order:

1. Construct the complete action object.

2. Convert human inputs into exact protocol integers.

3. Construct the EIP-712 domain.

4. Calculate the action-specific struct hash.

5. Calculate the final EIP-712 digest.

6. Sign the digest.

7. Serialize bigint fields as decimal strings.

8. Send the action, chain ID, digest, and signature.

The final digest is constructed as:

keccak256("\x19\x01" || domainSeparator || actionStructHash)

Hash helpers

The SDK exports helpers for each action type.

Action	Endpoint	Hash helper
Order	POST /orders	hashFillOrderJS
Cancel	POST /cancels	hashCancelOrderJS
Cancel-replace	POST /cancel-replace	hashCancelReplaceOrderJS
Replacement order	POST /cancel-replace	hashFillOrderJS
Withdrawal	POST /withdrawals	hashWithdrawalOrderJS
Claim	POST /claim	hashClaimOrderJS
Agent approval	POST /agents/approve	hashApproveAgentOrderJS
Inner agent approval	POST /agents/approve	hashAgentApprovalJS
Agent revocation	POST /agents/revoke	hashRevokeAgentOrderJS

Sign an order

import {
  getExchangeDomain,
  hashFillOrderJS,
  signOrderJS,
} from "@gammaswap/v2-exchange-sdk";
import { Wallet } from "ethers";

const wallet = new Wallet(
  process.env.PRIVATE_KEY!,
);

const chainId = 84532n;

const verifyingContract =
  "0x1111111111111111111111111111111111111111";

const assetId =
  261336857817713630688382311349658711122006440411137n;

const epoch = 12n;
const nonce = 113377280000000000n;

const order = {
  typ: 2n,
  nonce,
  signer: wallet.address,
  signatureType: 0n,
  sender: wallet.address,
  epoch,
  side: false,
  assetId,
  size: 1025n,
  price: 999000n,
  timeInForce: 0n,
  approvalNonce: 0n,
};

const domain = getExchangeDomain(
  chainId,
  verifyingContract,
);

const orderHash =
  hashFillOrderJS(order, domain);

const signature =
  signOrderJS(orderHash, wallet);

Serialize the request

Bigint values must be serialized as decimal strings before JSON encoding.

const body = {
  order: {
    typ: order.typ.toString(),
    nonce: order.nonce.toString(),
    signer: order.signer,
    signatureType:
      order.signatureType.toString(),
    sender: order.sender,
    epoch: order.epoch.toString(),
    side: order.side,
    assetId: order.assetId.toString(),
    size: order.size.toString(),
    price: order.price.toString(),
    timeInForce:
      order.timeInForce.toString(),
    approvalNonce:
      order.approvalNonce.toString(),
  },
  chainId: chainId.toString(),
  orderHash,
  signature,
};

Serialized request body:

{
  "order": {
    "typ": "2",
    "nonce": "113377280000000000",
    "signer": "0x2222222222222222222222222222222222222222",
    "signatureType": "0",
    "sender": "0x2222222222222222222222222222222222222222",
    "epoch": "12",
    "side": false,
    "assetId": "261336857817713630688382311349658711122006440411137",
    "size": "1025",
    "price": "999000",
    "timeInForce": "0",
    "approvalNonce": "0"
  },
  "chainId": "84532",
  "orderHash": "0x...",
  "signature": "0x..."
}

Submit the request

const response = await fetch(
  "https://exchange-api.gammaswap.com/api/orders",
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
    },
    body: JSON.stringify(body),
  },
);

const result = await response.json();

Successful response:

{
  "orderId": "0x3333333333333333333333333333333333333333333333333333333333333333",
  "filled": "0",
  "remaining": "1025",
  "cancelled": "0",
  "status": "ACCEPTED",
  "reason": ""
}

Cancel-and-replace signing

Cancel-and-replace contains two separately signed actions:

• The replacement order

• The cancel-replace action

Sign the replacement order first:

const replacementOrderHash =
  hashFillOrderJS(replacement, domain);

const replacementSignature =
  signOrderJS(
    replacementOrderHash,
    wallet,
  );

The cancel-replace action includes replacementOrderHash.

const cancelReplace = {
  // Cancel-replace fields
  replacementOrderHash,
};

Calculate and sign the cancel-replace digest:

const orderHash =
  hashCancelReplaceOrderJS(
    cancelReplace,
    domain,
  );

const signature =
  signOrderJS(orderHash, wallet);

The HTTP body includes both signatures:

{
  "cancelReplace": {},
  "replacement": {},
  "chainId": "84532",
  "orderHash": "0x...",
  "signature": "0x...",
  "replacementOrderHash": "0x...",
  "replacementSignature": "0x..."
}

Agent approval signing

Agent approval contains two signatures:

1. An inner signature over the agent approval.

2. An outer signature over the approve-agent action.

Use:

hashAgentApprovalJS

for the inner agent approval and:

hashApproveAgentOrderJS

for the outer approval action.

Address handling

Normalize relevant address fields consistently before hashing and sending requests.

The API normalizes signed address fields to lowercase when validating hashes and signatures.

A difference in address representation can produce a different digest if the direct signing implementation does not follow the same normalization rules.

Numeric handling

Do not use floating-point JavaScript numbers when building signed actions.

Use exact integer values:

const price = 999000n;
const size = 1025n;

Do not sign:

const price = 99.9;
const size = 10.25;

Human decimal inputs must be converted before hashing.

Common signature failures

A request can fail authentication if:

• The wrong chain ID is used.

• The wrong verifying contract is used.

• A signed field changes before submission.

• Human decimal values are signed instead of protocol integers.

• Fields are encoded in the wrong order.

• An incorrect Solidity integer width is used.

• The submitted digest does not match the action.

• The recovered signer does not match the action’s signer.

• An agent approval is missing, inactive, or expired.

• The wrong approval nonce is used.

• The signature type does not match the signing flow.

Common API errors include:

ORDER_HASH_MISMATCH
CANCEL_ORDER_HASH_MISMATCH
CANCEL_REPLACE_ORDER_HASH_MISMATCH
WITHDRAWAL_ORDER_HASH_MISMATCH
APPROVE_AGENT_ORDER_HASH_MISMATCH
REVOKE_ORDER_HASH_MISMATCH
INVALID_SIGNATURE
INVALID_APPROVAL_SIGNATURE

For most integrations, use ExchangeClient instead of constructing direct signatures manually.