Agent Wallets

An agent wallet is a separate EVM wallet that is approved to sign exchange actions for a master account.

Agent wallets allow applications and automated trading systems to sign actions without using the master account’s private key for every request.

The master account continues to own:

• Balances

• Positions

• Orders

• Claims

• Withdrawable funds

The agent wallet is only the signer for supported exchange actions.

Supported agent actions

An approved agent can submit:

• Orders

• Cancels

• Cancel-all requests

• Cancel-and-replace requests

• Claims

Agent withdrawals are not supported by the documented SDK methods.

Generate an agent wallet

Use Wallet.createRandom() to generate a new EVM wallet.

import { Wallet } from "ethers";

const agentWallet = Wallet.createRandom();

console.log("Agent address:", agentWallet.address);

The generated private key is available as:

agentWallet.privateKey

Store the private key in a server-side secret manager.

Do not:

• Commit the private key to source control

• Include it in a frontend bundle

• Store it in browser local storage

• Print it in production logs

• Share it with the master wallet’s users

Create the master client

The master wallet must approve and revoke agents.

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

const masterWallet = new Wallet(
  process.env.MASTER_PRIVATE_KEY!,
);

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

Approve the agent

Approve the generated agent address with the master wallet.

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

Response:

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

Possible statuses:

SUCCESS
FAIL

The SDK:

1. Validates the master and agent addresses.

2. Ensures the agent differs from the master.

3. Creates the inner agent-approval signature.

4. Creates the signed outer approval action.

5. Submits the approval to POST /agents/approve.

An explicit approval nonce can also be provided:

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

Create an agent client

Create a separate ExchangeClient using the agent wallet.

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

The configured wallet is now the agent signer.

For agent methods, pass the master account as sender.

Place an agent order

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

Response:

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

Cancel an order as an agent

const result = await agentClient.cancelAgentOrder({
  sender: masterWallet.address,
  assetId:
    "261336857817713630688382311349658711122006440411137",
  epoch: "12",
  orderHash:
    "0x1111111111111111111111111111111111111111111111111111111111111111",
});

Response:

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

Cancel all orders as an agent

const result = await agentClient.cancelAllAgent({
  sender: masterWallet.address,
  assetId:
    "261336857817713630688382311349658711122006440411137",
  epoch: "12",
});

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

Cancel and replace as an agent

const result =
  await agentClient.cancelReplaceAgentOrder({
    sender: masterWallet.address,
    assetId:
      "261336857817713630688382311349658711122006440411137",
    epoch: "12",
    cancelOrderHash:
      "0x1111111111111111111111111111111111111111111111111111111111111111",
    side: false,
    price: "99.8",
    size: "10.25",
  });

The replacement order must use the same market and side as the cancelled order.

Claim as an agent

const result = await agentClient.claimAgent({
  sender: masterWallet.address,
  assetId:
    "261336857817713630688382311349658711122006440411137",
  epoch: "12",
});

Response:

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

Approval nonces

Agent actions contain both:

• An action nonce

• An agent approvalNonce

The action nonce identifies the signed action.

The approval nonce identifies the active agent approval.

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

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

Check agent status

Create an InfoClient to check the current approval.

import { createInfoClient } from "@gammaswap/v2-exchange-sdk";

const info = createInfoClient({
  apiUrl: "https://exchange-api.gammaswap.com/api",
});

const approval =
  await info.getAgentApproval(masterWallet.address);

Response:

{
  "agent": "0x2222222222222222222222222222222222222222",
  "nonce": "1730000300000",
  "status": "active"
}

Possible statuses:

active
inactive
expired

Get only the parsed approval nonce:

const approvalNonce =
  await info.getAgentApprovalNonce(
    masterWallet.address,
  );

SDK response:

1730000300000n

Revoke the agent

Agent revocation must be signed by the master wallet.

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

Response:

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

After revocation, the agent can no longer submit actions for the master account.

Signing without submitting

Use signAgentApproval to create the inner agent-approval signature without submitting the complete approval request.

const signature =
  await masterClient.signAgentApproval({
    agent: agentWallet.address,
    approvalNonce: "1730000300000",
  });

This does not approve the agent by itself.

Use approveAgent to submit the complete approval.

Multiple trading processes

Nonce uniqueness is local to one NonceManager instance.

If several processes use the same agent wallet, coordinate their action nonces with:

• A shared NonceManager

• A centralized nonce service

• A shared atomic counter

• Explicit coordinated nonces

For independent trading processes, use a separate agent wallet for each process when possible.