@tomo-inc/agentql

TypeScript SDK for the current AgentQL hosted surfaces.

Links

• Website: https://agentql.tomo.inc/
• Docs: https://docs-agentql.tomo.inc/
• npm: https://www.npmjs.com/package/@tomo-inc/agentql
• Repository: https://github.com/AgentQL/sdk-ts

Install

npm install @tomo-inc/agentql

First Call

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: "bnbchain",
  address: "0xbb4CdB9CBd36B01bD1cBaEBF2De08d9173bc095c"
});

const chainId = await aql.rpc.bnbchain.call("eth_chainId");

If you only want to make hosted REST or RPC calls, apiKey is usually the only constructor option you need.

Constructor Options

Most users only need apiKey for the first call.

| Option | Required | Description | | --- | --- | --- | | apiKey | Yes | Bearer token used for hosted AgentQL requests. | | gatewayBaseUrl | No | Override the hosted gateway base URL. Defaults to https://gw-aql.tomo.services. | | mcpServerUrl | No | Override the hosted MCP base URL. Defaults to https://mcp-aql.tomo.services. | | timeoutMs | No | Apply an HTTP timeout to SDK requests. | | headers | No | Attach extra request headers. Useful for your own observability or gateway-side attribution. | | fetch | No | Only needed when the runtime does not already provide fetch. In modern browsers, Bun, Node.js 18+, and most edge runtimes, you usually do not need to pass this. | | webSocketFactory | No | Required only when using market.subscribe(). It lets the caller provide a runtime-specific authenticated websocket implementation. |

headers is fully optional. For example, a header like X-Client-Name can be used to identify your application in logs, but it is not required by the SDK.

Runtime Requirements

• A runtime with fetch
• For market websocket subscriptions, a runtime-specific webSocketFactory that can establish an authenticated hosted websocket connection

If your runtime already provides fetch, you do not need to pass it into the SDK constructor.

Built-in hosted defaults:

• gateway: https://gw-aql.tomo.services
• MCP: https://mcp-aql.tomo.services

API Surface

The current public surface includes:

| Area | Methods | | --- | --- | | market | getAssetProfile, getMarketProfile, getPriceSnapshot, getOHLCVWindow, subscribe | | rpc.bnbchain | call, batch | | rpc.solana | call, batch | | mcp | initialize, toolsList, sessionCreate, sessionAttach |

Market WebSocket Usage

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: "pair-1",
      chain: "bnbchain",
      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();

WebSocket note

Hosted market websocket access uses bearer auth.

Because standard browser WebSocket constructors do not provide a portable way to attach Authorization headers, market.subscribe() currently requires the caller to inject a runtime-specific webSocketFactory.

This keeps the SDK honest about the hosted auth model instead of pretending the default browser websocket API is sufficient.

The subscription event surface is strongly typed:

• "price", "ohlcv", "ready", "heartbeat", "gap", "overflow", "sourceDegraded", "sourceSwitched", and "event" receive StreamEvent
• "error" receives Error
• "close" receives CloseEvent

RPC note

rpc.<chain>.call() unwraps JSON-RPC success responses and throws AgentQLError when the JSON-RPC body contains an error.

rpc.<chain>.batch() intentionally returns the raw JSON-RPC response array so the caller can handle partial success and partial failure cases explicitly.

MCP note

Hosted MCP stays on its own mcpServerUrl. Do not replace it with gatewayBaseUrl.

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: "bnbchain",
    address: "0xabc"
  });
} catch (error) {
  if (error instanceof AgentQLError) {
    console.error(error.message, error.status, error.traceId, error.requestId);
  }
  throw error;
}

AgentQLError normalizes REST failures, JSON-RPC failures, websocket error payloads, and lower-level runtime transport failures.