> 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/concepts/authentication.md). # 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. ```ts 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. ```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", }); ``` 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
ValueTypeDescription
0EOAThe account signs its own action
4AgentAn 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: ```json { "action": {}, "chainId": "84532", "orderHash": "0x...", "signature": "0x..." } ``` The action field name depends on the endpoint:
EndpointAction field
POST /ordersorder
POST /cancelscancel
POST /cancel-replacecancelReplace
POST /withdrawalswithdrawal
POST /claimclaim
POST /agents/approveapproval
POST /agents/revokerevocation
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: ```ts 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.
ActionHash helper
OrderhashFillOrderJS
CancelhashCancelOrderJS
Cancel-replacehashCancelReplaceOrderJS
Replacement orderhashFillOrderJS
WithdrawalhashWithdrawalOrderJS
ClaimhashClaimOrderJS
Agent approvalhashApproveAgentOrderJS
Inner agent approvalhashAgentApprovalJS
Agent revocationhashRevokeAgentOrderJS
Example: ```ts 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. ```ts await masterClient.approveAgent({ agent: agentWallet.address, }); ``` An agent order specifies the master account as `sender`: ```ts 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`. ```ts 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: ```json { "type": "subscribe", "assetId": "1" } ``` Oracle subscription: ```json { "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. --- # 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/concepts/authentication.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.