Overview

The GammaSwap V2 protocol provides HTTP, WebSocket, and on-chain interfaces for building integrations with AI agents, trading algorithms and third party tools.

The recommended integration method is the official TypeScript SDK:

@gammaswap/v2-exchange-sdk

The SDK provides five specialized clients.

Client	Purpose	Connects to
InfoClient	Read exchange and account data	Exchange HTTP API
ExchangeClient	Submit signed exchange actions	Exchange HTTP API
DepositClient	Read deposit state and submit deposits	Onchain Contracts
ExchangeWebSocketClient	Subscribe to live market updates	Market WebSocket
OracleWebSocketClient	Subscribe to live oracle prices	Oracle WebSocket

Exchange HTTP API

The Exchange HTTP API provides public endpoints for:

• Asset metadata

• Account balances

• Positions

• Order-book snapshots

• Top-of-book data

• Resolution prices

• Agent approval status

• Orders

• Cancels

• Cancel-and-replace operations

• Claims

• Withdrawals

• Agent approval and revocation

Read-only requests do not require a wallet or signature. Exchange actions are authenticated using EIP-712 signatures.

Market WebSocket

The market WebSocket publishes real-time updates for subscribed asset IDs.

Update types include:

• Orders

• Trades

• Cancels

• Market resolutions

Applications maintaining a local order book should use the HTTP API to load an initial snapshot and use WebSocket updates to keep it current.

If the connection is interrupted or the SDK detects that resynchronization is required, reload the full order-book snapshot before processing subsequent updates.

Oracle WebSocket

The oracle WebSocket publishes live prices for subscribed symbol IDs.

Each price update includes:

• Symbol ID

• Price

• Timestamp

After a reconnect or stale-price notification, consumers should accept the next live price update.

Deposits

Deposits are submitted directly to the configured chain through the DepositClient.

The deposit client supports:

• Discovering settlement and ledger contract addresses

• Reading pending and processed balances

• Checking deposit-processing state

• Reading token balances and allowances

• Approving the deposit ledger or Permit2

• Depositing settlement tokens

• Signing and submitting permit-based deposits

A wallet, RPC URL, and matching chain ID are required for on-chain transactions.

Agent wallets

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

Agent wallets can submit:

• Orders

• Cancels

• Cancel-and-replace actions

• Claims

The master account remains the owner of the positions, balances, and orders. The agent wallet is only the signer.

Data conventions

Blockchain integers are represented as decimal strings in JSON.

SDK order and transfer inputs use human-readable decimal strings:

• size and amount support up to two decimal places.

• price supports up to one decimal place.

• Addresses use standard EVM hexadecimal format.

• Order IDs and action hashes use bytes32 hexadecimal strings.

• false represents a buy order.

• true represents a sell order.

The SDK validates and converts these values before sending requests.