Use Typescript-SDK
Use the published TypeScript SDK when your runtime already uses TypeScript or modern JavaScript and you want one typed client across Market, RPC, and MCP.
The published SDK lives on npm. For most first calls, apiKey is the only constructor option you need.
Install
npm install @tomo-inc/agentqlFirst call
Prepare the API key
Create the API key first if needed, then keep {docsAPIKeyEnvironmentVariable} ready.
Construct the client
The SDK already defaults to the hosted AgentQL gateway and MCP endpoints, so
the first constructor usually only needs apiKey.
Start with one market read
Call market.getPriceSnapshot() first.
import { AgentQL } from "@tomo-inc/agentql";const aql = new AgentQL({ apiKey: process.env.AQL_API_KEY!});const price = await aql.market.getPriceSnapshot({ marketKind: "dex", chain: "ethereum", address: "0xC02aaA39b223FE8D0A0E5C4F27eAD9083C756Cc2"});In normal usage, you only need apiKey and the method you want to
call.
Constructor options
| Option | Required | Notes |
|---|---|---|
apiKey | Yes | Bearer token used for hosted AgentQL requests. |
gatewayBaseUrl | No | Only override this when you need a non-default gateway endpoint. |
mcpServerUrl | No | Only override this when you need a non-default MCP endpoint. |
timeoutMs | No | Apply an HTTP timeout to SDK requests. |
headers | No | Attach extra request headers for your own observability or attribution. |
fetch | No | Only needed when the runtime does not already provide fetch. |
webSocketFactory | No | Only needed when using market.subscribe(). |
Runtime notes
- Most runtimes only need built-in
fetch - Modern browsers, Bun, Node.js 18+, and most edge runtimes already provide
fetch market.subscribe()needs a runtime-specificwebSocketFactory- Base URL overrides are advanced usage, not part of the normal first-call path
Market WebSocket subscription
import { AgentQL, type StreamEvent, type WebSocketFactory} from "@tomo-inc/agentql";const webSocketFactory: WebSocketFactory = (url) => { return new WebSocket(url);};const aql = new AgentQL({ apiKey: process.env.AQL_API_KEY!, webSocketFactory});const subscription = aql.market.subscribe({ profile: "standard", targets: [ { marketKind: "dex", targetId: "0xC02aaA39b223FE8D0A0E5C4F27eAD9083C756Cc2", chain: "ethereum", eventFamily: "price" } ]});const unsubscribe = subscription.on("price", (event: StreamEvent) => { console.log(event.event_type, event.payload);});subscription.on("error", (error) => { console.error(error);});subscription.on("close", (event) => { console.log("closed", event.code, event.reason);});unsubscribe();subscription.close();Standard browser WebSocket constructors do not provide a
portable way to attach Authorization headers. That is why the
SDK requires an injected webSocketFactory instead of hiding the
hosted auth model.
Error handling
import { AgentQL, AgentQLError } from "@tomo-inc/agentql";const aql = new AgentQL({ apiKey: process.env.AQL_API_KEY!});try { await aql.market.getPriceSnapshot({ marketKind: "dex", chain: "ethereum", address: "0xabc" });} catch (error) { if (error instanceof AgentQLError) { console.error(error.message, error.status, error.traceId, error.requestId); } throw error;}AgentQLError normalizes HTTP failures, JSON-RPC failures, websocket error
payloads, and lower-level runtime transport failures into one SDK-facing error
shape.
Package links
Related pages
- Get API Key: prepare the API key used by the SDK constructor.
- Use HTTP: compare the SDK call against the raw hosted HTTP path.
- Use MCP: keep the hosted MCP transport boundary clear when using the SDK.
- Use Market WebSocket: compare SDK subscriptions against the raw market websocket contract.