> 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/api-reference/exchange-methods.md). # 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. ```ts 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. ```ts const result = await exchange.placeOrder({ assetId: "261336857817713630688382311349658711122006440411137", epoch: "12", side: false, price: "99.9", size: "10.25", }); ``` Endpoint: ``` POST /orders ``` Response: ```json { "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. ```ts const result = await exchange.placeAgentOrder({ sender: "0x1111111111111111111111111111111111111111", assetId: "261336857817713630688382311349658711122006440411137", epoch: "12", side: false, price: "99.9", size: "10.25", }); ``` Endpoint: ``` POST /orders ``` Response: ```json { "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. ```ts const result = await exchange.cancelOrder({ assetId: "261336857817713630688382311349658711122006440411137", epoch: "12", orderHash: "0x1111111111111111111111111111111111111111111111111111111111111111", }); ``` Endpoint: ``` POST /cancels ``` Response: ```json { "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. ```ts const result = await exchange.cancelAll({ assetId: "261336857817713630688382311349658711122006440411137", epoch: "12", }); ``` Endpoint: ``` POST /cancels ``` The SDK uses the zero hash internally to request cancel-all. Response: ```json { "id": "0x4444444444444444444444444444444444444444444444444444444444444444", "orderIds": [ "0x1111111111111111111111111111111111111111111111111111111111111111", "0x2222222222222222222222222222222222222222222222222222222222222222" ], "status": "CANCELLED" } ``` ### `cancelAgentOrder` Cancels one master-account order as an approved agent. ```ts const result = await exchange.cancelAgentOrder({ sender: "0x1111111111111111111111111111111111111111", assetId: "261336857817713630688382311349658711122006440411137", epoch: "12", orderHash: "0x2222222222222222222222222222222222222222222222222222222222222222", }); ``` Endpoint: ``` POST /cancels ``` Response: ```json { "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. ```ts const result = await exchange.cancelAllAgent({ sender: "0x1111111111111111111111111111111111111111", assetId: "261336857817713630688382311349658711122006440411137", epoch: "12", }); ``` Endpoint: ``` POST /cancels ``` Response: ```json { "id": "0x6666666666666666666666666666666666666666666666666666666666666666", "orderIds": [ "0x1111111111111111111111111111111111111111111111111111111111111111", "0x2222222222222222222222222222222222222222222222222222222222222222" ], "status": "CANCELLED" } ``` ### `cancelReplaceOrder` Cancels one order and submits a replacement order in the same request. ```ts 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: ```json { "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. ```ts 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: ```json { "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. ```ts const result = await exchange.claim({ assetId: "261336857817713630688382311349658711122006440411137", epoch: "12", }); ``` Endpoint: ``` POST /claim ``` Response: ```json { "id": "0xdddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddd", "status": "CLAIMED" } ``` Possible `status` values: ``` CLAIMED CLAIM_FAILED ``` ### `claimAgent` Claims available funds for a master account as an approved agent. ```ts const result = await exchange.claimAgent({ sender: "0x1111111111111111111111111111111111111111", assetId: "261336857817713630688382311349658711122006440411137", epoch: "12", }); ``` Endpoint: ``` POST /claim ``` Response: ```json { "id": "0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee", "status": "CLAIMED" } ``` If `approvalNonce` is omitted, the SDK fetches it through `InfoClient`. ### `withdraw` Submits a signed withdrawal request. ```ts const result = await exchange.withdraw({ amount: "100.00", receiver: "0x2222222222222222222222222222222222222222", }); ``` Endpoint: ``` POST /withdrawals ``` Response: ```json { "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. ```ts const result = await exchange.approveAgent({ agent: "0x2222222222222222222222222222222222222222", }); ``` Endpoint: ``` POST /agents/approve ``` Response: ```json { "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. ```ts const result = await exchange.revokeAgent({}); ``` Endpoint: ``` POST /agents/revoke ``` Response: ```json { "id": "0xabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcd", "status": "SUCCESS" } ``` Possible `status` values: ``` SUCCESS FAIL ``` ### `signAgentApproval` Creates the inner agent-approval signature without submitting an HTTP request. ```ts const signature = await exchange.signAgentApproval({ agent: "0x2222222222222222222222222222222222222222", approvalNonce: "1730000300000", }); ``` SDK response: ```ts "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 | --- # 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/api-reference/exchange-methods.md?ask=&goal= ``` `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.