How the Osmosis Agent Toolkit Handles Network Latency When Querying the SQS Service

The Osmosis Agent Toolkit relies entirely on the environment's native fetch implementation for SQS queries, implementing no request timeouts, retry logic, or circuit breakers, which means applications must handle network latency mitigation themselves.

The jonator/osmosis-agent-toolkit provides TypeScript utilities for interacting with the Osmosis Sidecar Query Service (SQS). When querying this service, the toolkit takes a minimal approach to network latency, delegating all connection handling to the standard fetch API without wrapping calls in additional resilience patterns.

Default Network Behavior in OsmosisSqsQueryClient

At the core of SQS interactions sits the OsmosisSqsQueryClient class defined in packages/core/src/queries/sqs/client.ts. This client constructs HTTPS URLs for the SQS endpoint (defaulting to https://sqsprod.osmosis.zone) and executes requests using unmodified fetch calls:

// packages/core/src/queries/sqs/client.ts
async getOutGivenInQuote(...) {
  const url = this.url('/router/quote')
  // … set query parameters …
  const response = await fetch(url)          // ← direct fetch, no timeout
  return (await response.json()) as SidecarOutGivenInQuoteResponse
}

Because the implementation invokes fetch without an AbortController signal or timeout parameter, the request remains open as long as the underlying TCP connection persists. Consequently, the toolkit exposes raw round-trip latency directly to consumers, including any server-side processing delays from the SQS infrastructure.

Latency Propagation to Swap Tools

All higher-level abstractions inherit this behavior. In packages/core/src/tools/swap.ts, tools like SwapQuoteOutGivenInTool and SwapQuoteInGivenOutTool instantiate the client internally and delegate quote fetching to methods such as getOutGivenInQuote():

const quote = await sqsClient.getOutGivenInQuote(tokenIn, tokenOutDenom);

No buffering, caching layer, or asynchronous polling mechanism intercepts these calls to mask latency spikes. The latency characteristics of the network path between the application and sqsprod.osmosis.zone transmit directly through the entire call stack.

Implementing Custom Latency Controls

Since the base client does not enforce deadlines, applications requiring stricter latency controls must extend OsmosisSqsQueryClient. Below is a pattern for injecting a timeout using AbortController:

function fetchWithTimeout(url: URL, timeoutMs = 5000): Promise<Response> {
  const controller = new AbortController();
  const timer = setTimeout(() => controller.abort(), timeoutMs);
  return fetch(url, { signal: controller.signal }).finally(() => clearTimeout(timer));
}

class TimedSqsClient extends OsmosisSqsQueryClient {
  protected async fetchUrl(url: URL) {
    return fetchWithTimeout(url, 3000); // 3‑second timeout
  }

  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 this.fetchUrl(url);
    return (await response.json()) as SidecarOutGivenInQuoteResponse;
  }
}

This subclass overrides the fetch mechanism while preserving the URL construction logic from the parent. Developers can similarly implement exponential back-off or circuit-breaker patterns by wrapping these methods at the application level.

Summary

• The OsmosisSqsQueryClient in packages/core/src/queries/sqs/client.ts uses raw fetch without timeouts or retries.
• Tools like SwapQuoteOutGivenInTool inherit this behavior directly from the base client.
• Network latency manifests as unmasked round-trip time to the SQS endpoint.
• Consumers must extend the client or wrap calls to implement AbortController timeouts, retry logic, or circuit breakers.

Frequently Asked Questions

Does the Osmosis Agent Toolkit implement request timeouts for SQS queries?

No. The OsmosisSqsQueryClient passes URLs directly to the fetch API without attaching an AbortController signal or timeout parameter. Requests wait indefinitely until the underlying network stack closes the connection or the server responds.

Can I configure retry logic for failed SQS connections?

The toolkit does not provide built-in retry mechanisms. You must implement retry logic at the application level by catching exceptions from the client methods and re-invoking them according to your own back-off strategy.

How do I add a timeout to SQS queries using this toolkit?

Extend the OsmosisSqsQueryClient class and override the fetch method to include an AbortController with a desired timeout duration. This allows you to enforce deadlines while reusing the toolkit's URL construction and response parsing logic.

Do high-level tools like SwapQuoteOutGivenInTool handle latency differently than the base client?

No. Tools such as SwapQuoteOutGivenInTool and SwapQuoteInGivenOutTool instantiate the base OsmosisSqsQueryClient and call its methods directly, inheriting the same raw fetch behavior without additional latency mitigation.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}