# How OsmosisSqsQueryClient Integrates with the Osmosis Sidecar Query Service

> Learn how the OsmosisSqsQueryClient integrates with the Osmosis Sidecar Query service. This TypeScript HTTP wrapper simplifies REST requests and deserializes JSON responses.

- Repository: [Jon Ator/osmosis-agent-toolkit](https://github.com/jonator/osmosis-agent-toolkit)
- Tags: how-to-guide
- Published: 2026-03-05

---

**The `OsmosisSqsQueryClient` is a TypeScript HTTP wrapper that constructs REST requests, handles query parameters, and deserializes JSON responses from the Osmosis Sidecar Query Service (SQS) into strongly-typed interfaces.**

The `OsmosisSqsQueryClient` serves as the primary bridge between the `osmosis-agent-toolkit` SDK and the Osmosis Sidecar Query Service. This lightweight client abstracts the complexity of URL construction, parameter encoding, and response parsing, exposing three high-level methods for fetching swap quotes and token prices. Higher-level components such as `OsmosisAgentToolkit` and the swap tools consume these methods to obtain live market data without managing HTTP plumbing.

## What Is the Osmosis Sidecar Query Service?

The **Osmosis Sidecar Query Service (SQS)** is a RESTful API endpoint maintained by Osmosis that exposes real-time price quotes, routing information, and token price data for the Osmosis AMM. It accepts parameters for token denominations and amounts, calculates optimal swap routes, and returns JSON payloads containing estimated outputs, price impact, and fee breakdowns.

## OsmosisSqsQueryClient Architecture and Design

### Core Responsibilities

The client, defined in [`packages/core/src/queries/sqs/client.ts`](https://github.com/jonator/osmosis-agent-toolkit/blob/main/packages/core/src/queries/sqs/client.ts), encapsulates three critical functions:

1. **URL Construction**: Builds endpoints for `/router/quote` and `/tokens/prices` with the base URL `https://sqsprod.osmosis.zone`.
2. **Parameter Encoding**: Automatically appends `humanDenoms=false` to ensure raw minimal denominations are used, and formats token amounts as concatenated strings (e.g., `1000000uosmo`).
3. **Type-Safe Deserialization**: Casts JSON responses to TypeScript interfaces defined in [`router.ts`](https://github.com/jonator/osmosis-agent-toolkit/blob/main/router.ts) and [`prices.ts`](https://github.com/jonator/osmosis-agent-toolkit/blob/main/prices.ts).

### Type Safety with router.ts

The [`packages/core/src/queries/sqs/router.ts`](https://github.com/jonator/osmosis-agent-toolkit/blob/main/packages/core/src/queries/sqs/router.ts) file defines the contract between the client and the SQS API:

```typescript
export type SidecarOutGivenInQuoteResponse = {
  amount_in: { denom: string; amount: string };
  amount_out: string;
  // …additional fields (fee, price impact, route, etc.)
};

export type SidecarInGivenOutQuoteResponse = {
  amount_out: { denom: string; amount: string };
  amount_in: string;
  // …additional fields (fee, price impact, route, etc.)
};

```

These types guarantee that callers receive predictable object shapes when processing swap quotes.

## How OsmosisSqsQueryClient Communicates with SQS

### Constructing Out-Given-In Quotes

The `getOutGivenInQuote` method in [`client.ts`](https://github.com/jonator/osmosis-agent-toolkit/blob/main/client.ts) fetches the expected output for a specified input:

```typescript
async getOutGivenInQuote(tokenIn, tokenOutDenom) {
  const url = this.url('/router/quote');
  url.searchParams.set('tokenIn', `${tokenIn.amount}${tokenIn.denom}`);
  url.searchParams.set('tokenOutDenom', tokenOutDenom);
  const response = await fetch(url);
  return (await response.json()) as SidecarOutGivenInQuoteResponse;
}

```

This method concatenates the amount and denomination into a single string (e.g., `1000000uosmo`) and sets it as the `tokenIn` query parameter.

### Constructing In-Given-Out Quotes

Conversely, `getInGivenOutQuote` calculates the required input for a desired output:

```typescript
async getInGivenOutQuote(tokenOut, tokenInDenom) {
  const url = this.url('/router/quote');
  url.searchParams.set('tokenOut', `${tokenOut.amount}${tokenOut.denom}`);
  url.searchParams.set('tokenInDenom', tokenInDenom);
  const response = await fetch(url);
  return (await response.json()) as SidecarInGivenOutQuoteResponse;
}

```

Both methods use the same `/router/quote` endpoint but vary the parameters to specify the direction of the quote calculation.

### Fetching Token Prices

The `getPrices` method retrieves USD-denominated prices for a list of token denominations:

```typescript
async getPrices(denoms: string[]) {
  const url = this.url('/tokens/prices');
  url.searchParams.set('base', denoms.join(','));
  const response = await fetch(url);
  const priceMap = (await response.json()) as PriceMap;
  return denoms.reduce((acc, denom) => {
    acc[denom] = getPrice(priceMap, denom) ?? '0';
    return acc;
  }, {} as Record<string, string>);
}

```

This method joins the denomination array into a comma-separated string for the `base` parameter, then uses the `getPrice` helper from [`prices.ts`](https://github.com/jonator/osmosis-agent-toolkit/blob/main/prices.ts) to extract individual prices from the nested response map.

## Integration with OsmosisAgentToolkit

The `OsmosisAgentToolkit` class in [`packages/core/src/toolkit.ts`](https://github.com/jonator/osmosis-agent-toolkit/blob/main/packages/core/src/toolkit.ts) orchestrates the client lifecycle:

```typescript
export class OsmosisAgentToolkit {
  protected readonly _sqsClient = new OsmosisSqsQueryClient();

  constructor(mnemonic: string) {
    this._account = new Account(mnemonic);
    this._accountTool = new AccountTool(this._account, this._sqsClient);
    this._swapQuoteInGivenOutTool = new SwapQuoteInGivenOutTool(
      this._sqsClient,
      this._quoteAmountOutMemory,
    );
    // …other tools receive the same client instance
  }

  get sqsClient() { return this._sqsClient; }
}

```

By instantiating a single `OsmosisSqsQueryClient` and injecting it into `AccountTool`, `SwapQuoteInGivenOutTool`, and `SwapQuoteOutGivenInTool`, the toolkit ensures consistent configuration and connection pooling across all market data operations.

## Practical Code Examples

### Getting an Out-Given-In Quote

```typescript
import { OsmosisSqsQueryClient } from 'osmosis-agent-toolkit/packages/core/src/queries/sqs/client.js';

const sqs = new OsmosisSqsQueryClient();
const tokenIn = { amount: '1000000', denom: 'uosmo' }; // 1 OSMO
const tokenOutDenom = 'ibc/498A0751C798A0D9A389AA3691123DADA57DAA4FE165D5C75894505B876BA6E4'; // Noble USDC

sqs.getOutGivenInQuote(tokenIn, tokenOutDenom)
  .then(quote => {
    console.log('Expected output amount:', quote.amount_out);
    console.log('Route:', quote.route);
  })
  .catch(err => console.error('Quote failed:', err));

```

### Getting an In-Given-Out Quote

```typescript
const tokenOut = { amount: '500000', denom: 'ibc/498A0751C798A0D9A389AA3691123DADA57DAA4FE165D5C75894505B876BA6E4' }; // 0.5 USDC
const tokenInDenom = 'uosmo';

sqs.getInGivenOutQuote(tokenOut, tokenInDenom)
  .then(quote => console.log('Required OSMO amount:', quote.amount_in));

```

### Fetching Token Prices

```typescript
const denoms = [
  'uosmo',
  'ibc/498A0751C798A0D9A389AA3691123DADA57DAA4FE165D5C75894505B876BA6E4',
];

sqs.getPrices(denoms).then(prices => {
  console.log('OSMO price:', prices['uosmo']);
  console.log('USDC price:', prices['ibc/498A0751C798A0D9A389AA3691123DADA57DAA4FE165D5C75894505B876BA6E4']);
});

```

## Key Source Files Reference

| File | Purpose | Link |
|------|---------|------|
| [`packages/core/src/queries/sqs/client.ts`](https://github.com/jonator/osmosis-agent-toolkit/blob/main/packages/core/src/queries/sqs/client.ts) | Implements `OsmosisSqsQueryClient` with HTTP logic for Sidecar endpoints. | [client.ts](https://github.com/jonator/osmosis-agent-toolkit/blob/main/packages/core/src/queries/sqs/client.ts) |
| [`packages/core/src/queries/sqs/router.ts`](https://github.com/jonator/osmosis-agent-toolkit/blob/main/packages/core/src/queries/sqs/router.ts) | TypeScript interfaces `SidecarOutGivenInQuoteResponse` and `SidecarInGivenOutQuoteResponse` for type-safe deserialization. | [router.ts](https://github.com/jonator/osmosis-agent-toolkit/blob/main/packages/core/src/queries/sqs/router.ts) |
| [`packages/core/src/queries/sqs/prices.ts`](https://github.com/jonator/osmosis-agent-toolkit/blob/main/packages/core/src/queries/sqs/prices.ts) | `PriceMap` type and `getPrice` helper for extracting USD-denominated values from Sidecar price responses. | [prices.ts](https://github.com/jonator/osmosis-agent-toolkit/blob/main/packages/core/src/queries/sqs/prices.ts) |
| [`packages/core/src/toolkit.ts`](https://github.com/jonator/osmosis-agent-toolkit/blob/main/packages/core/src/toolkit.ts) | `OsmosisAgentToolkit` class that instantiates and injects the SQS client into higher-level tools. | [toolkit.ts](https://github.com/jonator/osmosis-agent-toolkit/blob/main/packages/core/src/toolkit.ts) |
| [`packages/core/src/tools/swap.ts`](https://github.com/jonator/osmosis-agent-toolkit/blob/main/packages/core/src/tools/swap.ts) | Swap quote tools (`SwapQuoteInGivenOutTool`, `SwapQuoteOutGivenInTool`) that consume the SQS client. | [swap.ts](https://github.com/jonator/osmosis-agent-toolkit/blob/main/packages/core/src/tools/swap.ts) |
| [`packages/core/src/tools/account.ts`](https://github.com/jonator/osmosis-agent-toolkit/blob/main/packages/core/src/tools/account.ts) | `AccountTool` that retrieves token price data via the SQS client for balance calculations. | [account.ts](https://github.com/jonator/osmosis-agent-toolkit/blob/main/packages/core/src/tools/account.ts) |

## Summary

The `OsmosisSqsQueryClient` serves as the dedicated HTTP adapter for the Osmosis Sidecar Query Service within the `osmosis-agent-toolkit` SDK. Key integration points include:

- **Direct REST Communication**: Constructs URLs for `/router/quote` and `/tokens/prices` endpoints, automatically appending `humanDenoms=false` for raw denomination handling.
- **Type-Safe Deserialization**: Leverages `SidecarOutGivenInQuoteResponse`, `SidecarInGivenOutQuoteResponse`, and `PriceMap` interfaces to ensure compile-time safety.
- **Singleton Pattern**: `OsmosisAgentToolkit` instantiates a single client instance and injects it into `AccountTool`, `SwapQuoteInGivenOutTool`, and `SwapQuoteOutGivenInTool`, ensuring consistent configuration across the SDK.
- **Three Core Methods**: Exposes `getOutGivenInQuote`, `getInGivenOutQuote`, and `getPrices` to fetch live swap estimates and USD-denominated token values.

## Frequently Asked Questions

### How does OsmosisSqsQueryClient handle authentication?

The `OsmosisSqsQueryClient` does not require authentication for read-only operations. It communicates with the public Osmosis Sidecar Query Service endpoint at `https://sqsprod.osmosis.zone`, which exposes market data without API keys. The client simply constructs the request URL and performs an unauthenticated `fetch` call.

### What is the difference between getOutGivenInQuote and getInGivenOutQuote?

**`getOutGivenInQuote`** calculates how much of a target token you will receive given a specific input amount and denomination. It sets the `tokenIn` and `tokenOutDenom` query parameters. **`getInGivenOutQuote`** performs the inverse calculation, determining how much input token is required to obtain a specific output amount, using `tokenOut` and `tokenInDenom` parameters instead.

### How does the client ensure type safety when parsing SQS responses?

The client uses TypeScript interfaces defined in [`packages/core/src/queries/sqs/router.ts`](https://github.com/jonator/osmosis-agent-toolkit/blob/main/packages/core/src/queries/sqs/router.ts) to cast JSON responses. Methods like `getOutGivenInQuote` explicitly return `SidecarOutGivenInQuoteResponse`, while `getInGivenOutQuote` returns `SidecarInGivenOutQuoteResponse`. This compile-time typing prevents property access errors and ensures consumers receive objects with guaranteed fields like `amount_out`, `amount_in`, and `route`.

### Can I use OsmosisSqsQueryClient independently of OsmosisAgentToolkit?

Yes, the `OsmosisSqsQueryClient` is a standalone class that can be instantiated directly without the full toolkit. You can import it from [`packages/core/src/queries/sqs/client.ts`](https://github.com/jonator/osmosis-agent-toolkit/blob/main/packages/core/src/queries/sqs/client.ts) and call its methods directly, as shown in the practical code examples. This is useful when you only need price data or swap quotes without the full agent toolkit functionality like transaction signing or account management.