> For the complete documentation index, see [llms.txt](https://docs.gammaswap.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.gammaswap.com/developers/guides/agent-wallets.md).

# 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.

```ts
import { Wallet } from "ethers";

const agentWallet = Wallet.createRandom();

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

The generated private key is available as:

```ts
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.

```ts
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.

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

Response:

```json
{
  "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:

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

### Create an agent client

Create a separate `ExchangeClient` using the agent wallet.

```ts
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

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

Response:

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

### Cancel an order as an agent

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

Response:

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

### Cancel all orders as an agent

```ts
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

```ts
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

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

Response:

```json
{
  "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`.

```ts
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.

```ts
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:

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

Possible statuses:

```
active
inactive
expired
```

Get only the parsed approval nonce:

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

SDK response:

```ts
1730000300000n
```

### Revoke the agent

Agent revocation must be signed by the master wallet.

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

Response:

```json
{
  "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.

```ts
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.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.gammaswap.com/developers/guides/agent-wallets.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.