Exchange Methods

ExchangeClient signs exchange actions with the configured ethers wallet and submits them to the Exchange HTTP API.

The SDK constructs the EIP-712 action, generates missing nonces, calculates the action hash, creates the signature, and serializes the HTTP request.

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",
});

placeOrder

Places an order signed directly by the configured wallet.

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

Endpoint:

POST /orders

Response:

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

Possible status values:

ACCEPTED
CANCELLED
REJECTED
FILLED
PARTIALLY_FILLED

Possible rejection reasons include:

IOC
FOK
MARGIN
INVALID_ORDER
MARKET_RESOLVED
INTERNAL_ERROR
ALO
UNKNOWN

placeAgentOrder

Places an order signed by an approved agent for a master account.

const result = await exchange.placeAgentOrder({
  sender: "0x1111111111111111111111111111111111111111",
  assetId: "261336857817713630688382311349658711122006440411137",
  epoch: "12",
  side: false,
  price: "99.9",
  size: "10.25",
});

Endpoint:

POST /orders

Response:

{
  "orderId": "0x2222222222222222222222222222222222222222222222222222222222222222",
  "filled": "500",
  "remaining": "525",
  "cancelled": "0",
  "status": "PARTIALLY_FILLED",
  "reason": ""
}

The configured wallet is the agent signer. The sender field is the master account that owns the order.

If approvalNonce is omitted, the SDK fetches it through InfoClient.

cancelOrder

Cancels one order signed directly by the configured wallet.

const result = await exchange.cancelOrder({
  assetId: "261336857817713630688382311349658711122006440411137",
  epoch: "12",
  orderHash:
    "0x1111111111111111111111111111111111111111111111111111111111111111",
});

Endpoint:

POST /cancels

Response:

{
  "id": "0x3333333333333333333333333333333333333333333333333333333333333333",
  "orderIds": [
    "0x1111111111111111111111111111111111111111111111111111111111111111"
  ],
  "status": "CANCELLED"
}

Possible status values:

CANCELLED
CANCEL_FAILED
CANCEL_NOT_COMMITTED

cancelAll

Cancels all orders owned by the configured wallet for an asset and epoch.

const result = await exchange.cancelAll({
  assetId: "261336857817713630688382311349658711122006440411137",
  epoch: "12",
});

Endpoint:

POST /cancels

The SDK uses the zero hash internally to request cancel-all.

Response:

{
  "id": "0x4444444444444444444444444444444444444444444444444444444444444444",
  "orderIds": [
    "0x1111111111111111111111111111111111111111111111111111111111111111",
    "0x2222222222222222222222222222222222222222222222222222222222222222"
  ],
  "status": "CANCELLED"
}

cancelAgentOrder

Cancels one master-account order as an approved agent.

const result = await exchange.cancelAgentOrder({
  sender: "0x1111111111111111111111111111111111111111",
  assetId: "261336857817713630688382311349658711122006440411137",
  epoch: "12",
  orderHash:
    "0x2222222222222222222222222222222222222222222222222222222222222222",
});

Endpoint:

POST /cancels

Response:

{
  "id": "0x5555555555555555555555555555555555555555555555555555555555555555",
  "orderIds": [
    "0x2222222222222222222222222222222222222222222222222222222222222222"
  ],
  "status": "CANCELLED"
}

If approvalNonce is omitted, the SDK fetches it through InfoClient.

cancelAllAgent

Cancels all master-account orders for an asset and epoch as an approved agent.

const result = await exchange.cancelAllAgent({
  sender: "0x1111111111111111111111111111111111111111",
  assetId: "261336857817713630688382311349658711122006440411137",
  epoch: "12",
});

Endpoint:

POST /cancels

Response:

{
  "id": "0x6666666666666666666666666666666666666666666666666666666666666666",
  "orderIds": [
    "0x1111111111111111111111111111111111111111111111111111111111111111",
    "0x2222222222222222222222222222222222222222222222222222222222222222"
  ],
  "status": "CANCELLED"
}

cancelReplaceOrder

Cancels one order and submits a replacement order in the same request.

const result = await exchange.cancelReplaceOrder({
  assetId: "261336857817713630688382311349658711122006440411137",
  epoch: "12",
  cancelOrderHash:
    "0x1111111111111111111111111111111111111111111111111111111111111111",
  side: false,
  price: "99.8",
  size: "10.25",
  allOrNothing: false,
});

Endpoint:

POST /cancel-replace

Response:

{
  "id": "0x7777777777777777777777777777777777777777777777777777777777777777",
  "cancel": {
    "id": "0x8888888888888888888888888888888888888888888888888888888888888888",
    "orderIds": [
      "0x1111111111111111111111111111111111111111111111111111111111111111"
    ],
    "status": "CANCELLED"
  },
  "replacement": {
    "orderId": "0x9999999999999999999999999999999999999999999999999999999999999999",
    "filled": "0",
    "remaining": "1025",
    "cancelled": "0",
    "status": "ACCEPTED",
    "reason": ""
  },
  "status": "SUCCESS"
}

Possible top-level status values:

CANCEL_FAILED
REPLACEMENT_FAILED
CANCEL_COMMITTED_REPLACEMENT_FAILED
SUCCESS

The replacement must use the same market and side as the cancelled order. Cancel-all is not supported by cancel-and-replace.

cancelReplaceAgentOrder

Cancels and replaces a master-account order as an approved agent.

const result = await exchange.cancelReplaceAgentOrder({
  sender: "0x1111111111111111111111111111111111111111",
  assetId: "261336857817713630688382311349658711122006440411137",
  epoch: "12",
  cancelOrderHash:
    "0x2222222222222222222222222222222222222222222222222222222222222222",
  side: false,
  price: "99.8",
  size: "10.25",
  allOrNothing: false,
});

Endpoint:

POST /cancel-replace

Response:

{
  "id": "0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "cancel": {
    "id": "0xbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
    "orderIds": [
      "0x2222222222222222222222222222222222222222222222222222222222222222"
    ],
    "status": "CANCELLED"
  },
  "replacement": {
    "orderId": "0xcccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc",
    "filled": "0",
    "remaining": "1025",
    "cancelled": "0",
    "status": "ACCEPTED",
    "reason": ""
  },
  "status": "SUCCESS"
}

If approvalNonce is omitted, the SDK fetches it through InfoClient.

claim

Claims available funds for a resolved asset epoch.

const result = await exchange.claim({
  assetId: "261336857817713630688382311349658711122006440411137",
  epoch: "12",
});

Endpoint:

POST /claim

Response:

{
  "id": "0xdddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddd",
  "status": "CLAIMED"
}

Possible status values:

CLAIMED
CLAIM_FAILED

claimAgent

Claims available funds for a master account as an approved agent.

const result = await exchange.claimAgent({
  sender: "0x1111111111111111111111111111111111111111",
  assetId: "261336857817713630688382311349658711122006440411137",
  epoch: "12",
});

Endpoint:

POST /claim

Response:

{
  "id": "0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee",
  "status": "CLAIMED"
}

If approvalNonce is omitted, the SDK fetches it through InfoClient.

withdraw

Submits a signed withdrawal request.

const result = await exchange.withdraw({
  amount: "100.00",
  receiver: "0x2222222222222222222222222222222222222222",
});

Endpoint:

POST /withdrawals

Response:

{
  "id": "0xffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff",
  "status": "WITHDRAWN"
}

Possible status values:

WITHDRAWN
WITHDRAWAL_FAILED

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

approveAgent

Approves an agent wallet to sign exchange actions for the master account.

const result = await exchange.approveAgent({
  agent: "0x2222222222222222222222222222222222222222",
});

Endpoint:

POST /agents/approve

Response:

{
  "id": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
  "status": "SUCCESS"
}

Possible status values:

SUCCESS
FAIL

The agent must differ from the configured master wallet.

If approvalNonce is omitted, the SDK creates the required approval value.

revokeAgent

Revokes the master account’s current agent approval.

const result = await exchange.revokeAgent({});

Endpoint:

POST /agents/revoke

Response:

{
  "id": "0xabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcd",
  "status": "SUCCESS"
}

Possible status values:

SUCCESS
FAIL

signAgentApproval

Creates the inner agent-approval signature without submitting an HTTP request.

const signature = await exchange.signAgentApproval({
  agent: "0x2222222222222222222222222222222222222222",
  approvalNonce: "1730000300000",
});

SDK response:

"0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1b"

This is a local signing operation. It does not approve the agent by itself. Use approveAgent to sign and submit the complete agent-approval action.

Available methods

Method	Endpoint or action
placeOrder	POST /orders
placeAgentOrder	POST /orders
cancelOrder	POST /cancels
cancelAll	POST /cancels
cancelReplaceOrder	POST /cancel-replace
cancelAgentOrder	POST /cancels
cancelAllAgent	POST /cancels
cancelReplaceAgentOrder	POST /cancel-replace
claim	POST /claim
claimAgent	POST /claim
withdraw	POST /withdrawals
approveAgent	POST /agents/approve
revokeAgent	POST /agents/revoke
signAgentApproval	Local signing