> 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/getting-started/quick-start.md).
# Quick Start
This guide creates the SDK clients, reads exchange data, submits a signed order, and subscribes to live updates.
### 1. Install the SDK
```bash
npm install @gammaswap/v2-exchange-sdk ethers
```
### 2. Configure the environment
```bash
EXCHANGE_API_URL=https://exchange-api.gammaswap.com/api
MARKET_WS_URL=wss://exchange-api.gammaswap.com/ws/
ORACLE_WS_URL=wss://exchange-api.gammaswap.com/oracle-ws/
CHAIN_ID=84532
RPC_URL=https://your-rpc-provider.example
PRIVATE_KEY=0x...
```
Keep private keys in a server-side secret manager. Do not include them in frontend bundles or commit them to source control.
### 3. Read asset metadata
Read-only methods use `InfoClient` and do not require a wallet.
```ts
import { createInfoClient } from "@gammaswap/v2-exchange-sdk";
const info = createInfoClient({
apiUrl: process.env.EXCHANGE_API_URL!,
});
const assetId =
"261336857817713630688382311349658711122006440411137";
const asset = await info.getAsset(assetId);
console.log(asset);
```
Example response:
```json
{
"assetId": "261336857817713630688382311349658711122006440411137",
"epoch": "12",
"registered": true,
"expiration": "1730000000",
"assetType": "2",
"strikePrice": "999000",
"ledger": "0x1111111111111111111111111111111111111111"
}
```
### 4. Load an order-book snapshot
```ts
const epoch = "12";
const book = await info.getOrderBook({
assetId,
epoch,
});
console.log(book.bids);
console.log(book.asks);
```
Example response:
```json
{
"assetId": "261336857817713630688382311349658711122006440411137",
"epoch": "12",
"ts": 1730000000,
"seqId": 123,
"bids": [],
"asks": []
}
```
### 5. Create a signed exchange client
```ts
import { createExchangeClient } from "@gammaswap/v2-exchange-sdk";
import { Wallet } from "ethers";
const wallet = new Wallet(process.env.PRIVATE_KEY!);
const exchange = createExchangeClient({
apiUrl: process.env.EXCHANGE_API_URL!,
wallet,
chainId: process.env.CHAIN_ID!,
});
```
### 6. Place an order
```ts
const order = await exchange.placeOrder({
assetId,
epoch,
side: false,
price: "99.9",
size: "10.25",
});
console.log(order);
```
Order input conventions:
Field
Meaning
side: false
Buy
side: true
Sell
price
Human decimal string with up to one decimal place
size
Human decimal string with up to two decimal places
timeInForce
Optional; defaults to GTC
nonce
Optional; generated by the SDK
Example response:
```json
{
"orderId": "0x1111111111111111111111111111111111111111111111111111111111111111",
"filled": "0",
"remaining": "1025",
"cancelled": "0",
"status": "ACCEPTED",
"reason": ""
}
```
### 7. Subscribe to market updates
Load the REST order-book snapshot before applying live updates.
```ts
import {
createExchangeWebSocketClient,
} from "@gammaswap/v2-exchange-sdk";
const marketStream = createExchangeWebSocketClient({
websocketUrl: process.env.MARKET_WS_URL!,
onError: (error) => console.error("Market stream error", error),
});
const unsubscribeBook = await marketStream.subscribeOrderBook(assetId, {
onUpdate: (update) => {
console.log("Market update", update);
},
onOrder: (update) => {
console.log("Order update", update);
},
onTrade: (update) => {
console.log("Trade update", update);
},
onCancel: (update) => {
console.log("Cancel update", update);
},
onResolution: (update) => {
console.log("Resolution update", update);
},
onResyncRequired: async (resyncAssetId) => {
const freshBook = await info.getOrderBook({
assetId: resyncAssetId,
epoch,
});
console.log("Reloaded order book", freshBook);
},
});
```
When the subscription is no longer needed:
```ts
await unsubscribeBook();
marketStream.close();
```
### 8. Subscribe to oracle prices
```ts
import {
createOracleWebSocketClient,
} from "@gammaswap/v2-exchange-sdk";
const oracleStream = createOracleWebSocketClient({
websocketUrl: process.env.ORACLE_WS_URL!,
stalePriceTimeoutMs: 30_000,
onError: (error) => console.error("Oracle stream error", error),
});
const unsubscribePrice = await oracleStream.subscribePrice("1", {
onPrice: (update) => {
console.log(
"Oracle price",
update.symbolId,
update.price,
update.ts,
);
},
onStale: (symbolId) => {
console.warn("Oracle price is stale", symbolId);
},
});
```
When the subscription is no longer needed:
```ts
await unsubscribePrice();
oracleStream.close();
```
### 9. Create a deposit client
Deposits communicate directly with onchain contracts.
```ts
import { createDepositClient } from "@gammaswap/v2-exchange-sdk";
const deposit = createDepositClient({
rpcUrl: process.env.RPC_URL!,
wallet,
chainId: process.env.CHAIN_ID!,
});
```
Check the connected wallet’s settlement-token balance:
```ts
const balance = await deposit.getSettlementTokenBalance();
console.log(balance);
```
Before submitting a deposit, approve the required spender using the relevant deposit-ledger or Permit2 approval method.
### Next steps
* Use `InfoClient` to read balances, positions, books, and resolutions.
* Use `ExchangeClient` to place orders, cancel orders, claim, and withdraw.
* Use an agent wallet to separate automated signing from the master wallet.
* Use `DepositClient` for token approvals and deposits.
* Use the WebSocket clients for real-time market and oracle updates.
---
# 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/getting-started/quick-start.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.