Authentication

GammaSwap uses different authentication mechanisms depending on the operation.

Operation	Authentication
Read-only HTTP request	None
Signed exchange action	EIP-712 wallet signature
Agent exchange action	Approved agent EIP-712 signature
Market WebSocket subscription	None
Oracle WebSocket subscription	None
Deposit transaction	On-chain wallet transaction
Deposit permit	Wallet-signed permit

Read-only requests

InfoClient methods do not require a wallet or signature.

const balance = await info.getBalance(
  "0x1111111111111111111111111111111111111111",
);

The queried account does not need to match any locally configured wallet.

Signed exchange actions

ExchangeClient signs exchange actions using its configured ethers wallet.

import { createExchangeClient } from "@gammaswap/v2-exchange-sdk";
import { Wallet } from "ethers";

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

const exchange = createExchangeClient({
  apiUrl: "https://exchange-api.gammaswap.com/api",
  wallet,
  chainId: "84532",
});

Signed actions include:

• Orders

• Cancels

• Cancel-and-replace requests

• Claims

• Withdrawals

• Agent approvals

• Agent revocations

EIP-712 domain

Signed exchange actions use this EIP-712 domain:

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

The chain ID and verifying contract prevent the same signature from being reused against another chain or exchange deployment.

Signature types

Value	Type	Description
0	EOA	The account signs its own action
4	Agent	An approved agent signs for a master account

For an EOA action:

• signer is the configured wallet.

• sender is normally the same wallet.

• signatureType is 0.

• approvalNonce is 0 when the action contains that field.

For an agent action:

• signer is the agent wallet.

• sender is the master account.

• signatureType is 4.

• approvalNonce identifies the active agent approval.

Signed request wrapper

Most signed HTTP requests use this outer structure:

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

The action field name 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 not an order.

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

Signing process

A direct API client signs an action in this order:

1. Construct the complete action object.

2. Convert numeric fields into their exact protocol integers.

3. Construct the EIP-712 domain.

4. Calculate the action-specific struct hash.

5. Calculate the EIP-712 digest.

6. Sign the digest.

7. Send the original action, chain ID, digest, and signature.

Any change to a signed field changes the digest and invalidates the signature.

Signed fields include:

• Action type

• Nonce

• Signer

• Signature type

• Sender

• Market fields

• Amount or order values

• Chain ID

• Verifying contract

SDK signing

The recommended approach is to let ExchangeClient construct and sign the action:

const result = await exchange.placeOrder({
  assetId,
  epoch,
  side: false,
  price: "99.9",
  size: "10.25",
});

The SDK fills:

• signer

• sender for EOA requests

• signatureType

• chainId

• Action-type identifier

• nonce when omitted

• timeInForce when omitted

• orderHash

• signature

Direct signing helpers

Low-level helpers are available for applications that construct direct HTTP requests.

Action	Hash helper
Order	hashFillOrderJS
Cancel	hashCancelOrderJS
Cancel-replace	hashCancelReplaceOrderJS
Replacement order	hashFillOrderJS
Withdrawal	hashWithdrawalOrderJS
Claim	hashClaimOrderJS
Agent approval	hashApproveAgentOrderJS
Inner agent approval	hashAgentApprovalJS
Agent revocation	hashRevokeAgentOrderJS

Example:

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

const domain = getExchangeDomain(
  chainId,
  verifyingContract,
);

const orderHash = hashFillOrderJS(order, domain);
const signature = signOrderJS(orderHash, wallet);

const body = {
  order,
  chainId: chainId.toString(),
  orderHash,
  signature,
};

Agent authentication

An agent must be approved by the master account before it can submit agent actions.

await masterClient.approveAgent({
  agent: agentWallet.address,
});

An agent order specifies the master account as sender:

await agentClient.placeAgentOrder({
  sender: masterWallet.address,
  assetId,
  epoch,
  side: false,
  price: "99.9",
  size: "10.25",
});

The SDK fetches the active approval nonce from InfoClient when it is omitted.

Agent approvals contain two signatures:

• An inner signature over the agent approval

• An outer signature over the approve-agent action

Cancel-and-replace authentication

Cancel-and-replace contains two separately signed components:

• cancelReplace

• replacement

The request includes:

• Cancel-replace action hash and signature

• Replacement-order hash and signature

The cancel-replace action commits to the replacement order’s hash.

Withdrawals

Withdrawals use EIP-712 authentication through ExchangeClient.

await exchange.withdraw({
  amount: "100.00",
  receiver: "0x1111111111111111111111111111111111111111",
});

If receiver is omitted, it defaults to the configured wallet address.

WebSocket authentication

The supplied market and oracle WebSocket protocols do not require authentication.

Clients subscribe using an assetId or symbolId.

Market subscription:

{
  "type": "subscribe",
  "assetId": "1"
}

Oracle subscription:

{
  "type": "subscribe",
  "symbolId": "1"
}

Deposit authentication

Deposit contract reads and transactions use the wallet configured on DepositClient.

Transactions are authorized through normal EVM wallet signatures.

Permit-based deposits use a separately signed deposit permit before submitting the on-chain transaction.