How to Configure a Custom SQS URL in Osmosis Agent Toolkit: 3 Methods Explained

Instantiate OsmosisSqsQueryClient with your custom endpoint URL and pass it to toolkit components, or extend OsmosisAgentToolkit to override the default https://sqsprod.osmosis.zone production endpoint.

The Osmosis Agent Toolkit connects to the Sidecar Query Service (SQS) API to fetch swap quotes and account data. By default, it targets the production endpoint at https://sqsprod.osmosis.zone. If you need to configure a custom SQS URL for staging environments, local development, or private deployments, the toolkit provides flexible configuration options through its OsmosisSqsQueryClient class.

Understanding the Default SQS Configuration

The OsmosisSqsQueryClient class in packages/core/src/queries/sqs/client.ts handles all SQS API communication. Understanding how it manages endpoints is essential before overriding the defaults.

The Default Production Endpoint

The constructor at line 8 of client.ts sets the default sqsUrl parameter to https://sqsprod.osmosis.zone:

constructor(private readonly sqsUrl: string = 'https://sqsprod.osmosis.zone') {}

When you instantiate the client without arguments, it automatically connects to the Osmosis production SQS infrastructure.

How the Endpoint Is Used

Every API request constructs the full URL using the sqsUrl property as the base. At line 51 of client.ts, the code uses the standard URL constructor:

const response = await fetch(new URL(path, this.sqsUrl), {
  // request configuration
});

This means changing the sqsUrl value at instantiation affects every subsequent request path automatically.

Method 1: Direct Client Instantiation (Recommended)

The quickest way to configure a custom SQS URL is to instantiate OsmosisSqsQueryClient directly with your endpoint and pass this client to the specific tools that require SQS access.

import { OsmosisSqsQueryClient } from '@osmosis-agent-toolkit/core'

// Define your custom SQS endpoint
const customUrl = 'https://my-custom-sqs.example.com'

// Create a client pointing to your custom endpoint
const sqsClient = new OsmosisSqsQueryClient(customUrl)

// Use the client directly for swap quotes
const quote = await sqsClient.getOutGivenInQuote(
  { amount: '1000', denom: 'uosmo' },
  'ibc/ATOM',
)

Because OsmosisSqsQueryClient is exported from the core package, you can use it independently without modifying the higher-level toolkit internals.

Using the Custom Client with Toolkit Tools

When using specific tools like AccountTool or swap quote utilities that accept an SQS client dependency, pass your custom instance:

import { AccountTool } from '@osmosis-agent-toolkit/core'

const accountTool = new AccountTool(sqsClient, mnemonic)

This approach keeps your changes localized and avoids side effects on other toolkit components.

Method 2: Extending OsmosisAgentToolkit

If you prefer using the high-level OsmosisAgentToolkit API—which bundles account handling, swap tools, and other utilities—you can extend the class to override the internal _sqsClient with your custom endpoint.

import { OsmosisAgentToolkit } from '@osmosis-agent-toolkit/core'
import { OsmosisSqsQueryClient } from '@osmosis-agent-toolkit/core'

const mnemonic = 'your twelve-word mnemonic here'
const customUrl = 'https://my-custom-sqs.example.com'

class CustomToolkit extends OsmosisAgentToolkit {
  constructor(mnemonic: string) {
    // Initialize parent with mnemonic
    super(mnemonic)
    
    // Replace the internal SQS client with custom endpoint
    // Note: _sqsClient is protected; this requires TypeScript ignore or proper inheritance
    this._sqsClient = new OsmosisSqsQueryClient(customUrl)
  }
}

// Usage
const toolkit = new CustomToolkit(mnemonic)
const quote = await toolkit.swapQuoteOutGivenInTool.quote({
  tokenIn: { amount: '500', denom: 'uosmo' },
  tokenOutDenom: 'ibc/ATOM',
})

Overriding the Internal SQS Client

The OsmosisAgentToolkit class stores the SQS client in a protected _sqsClient property, as seen in packages/core/src/toolkit.ts at line 18. By extending the class and reassigning this property after the parent constructor runs, you redirect all internal tools to your custom endpoint.

Note: Accessing _sqsClient requires TypeScript's @ts-ignore comment or proper protected member access within a subclass, as shown in the example above.

Method 3: Forking and Modifying the Constructor

For a permanent, cleaner public API change, fork the repository and modify the OsmosisAgentToolkit constructor to accept an optional sqsUrl parameter:

// In packages/core/src/toolkit.ts (modified)
constructor(mnemonic: string, sqsUrl?: string) {
  this._account = new Account(mnemonic)
  this._sqsClient = new OsmosisSqsQueryClient(sqsUrl) // uses custom URL if provided
  // ... initialize other tools
}

After this modification, usage becomes straightforward:

const toolkit = new OsmosisAgentToolkit(
  mnemonic, 
  'https://my-custom-sqs.example.com'
)

This approach eliminates the need for class extension and provides a clear, documented configuration option for all users of your fork.

Key Source Files Reference

Understanding the codebase structure helps when implementing custom configurations:

File	Role	Relevant Lines
packages/core/src/queries/sqs/client.ts	Implements the SQS query client; default endpoint is defined here.	Constructor default (https://sqsprod.osmosis.zone) – L8; URL assembly – L51
packages/core/src/toolkit.ts	High-level façade that instantiates the client internally.	Internal client creation – L18
packages/mcp/src/server.ts	Example entry-point that creates a toolkit instance (uses default client).	Toolkit construction – L17-L18

Summary

• Default Behavior: OsmosisSqsQueryClient automatically uses https://sqsprod.osmosis.zone when instantiated without arguments, as defined in packages/core/src/queries/sqs/client.ts.
• Direct Instantiation: Create OsmosisSqsQueryClient with a custom URL string and pass it to tools requiring SQS access for immediate configuration without modifying internal classes.
• Class Extension: Extend OsmosisAgentToolkit and override the protected _sqsClient property to use a custom endpoint while maintaining the high-level toolkit API.
• Permanent Fork: Modify the OsmosisAgentToolkit constructor in packages/core/src/toolkit.ts to accept an optional sqsUrl parameter for a cleaner public interface.

Frequently Asked Questions

What is the default SQS endpoint used by Osmosis Agent Toolkit?

The default endpoint is https://sqsprod.osmosis.zone. This value is hardcoded as the default parameter in the OsmosisSqsQueryClient constructor located at line 8 of packages/core/src/queries/sqs/client.ts.

Can I use a local SQS instance for development?

Yes. Instantiate OsmosisSqsQueryClient with your local development URL, such as http://localhost:3000, and pass this client to your tools. This approach allows you to test against local SQS instances without modifying the toolkit's source code.

Is the sqsUrl parameter required when creating OsmosisSqsQueryClient?

No, the sqsUrl parameter is optional. When omitted, the constructor defaults to the production endpoint https://sqsprod.osmosis.zone. Providing a custom string overrides this default for that specific instance.

How do I verify which SQS endpoint my toolkit instance is using?

Check the sqsUrl property on your OsmosisSqsQueryClient instance directly. If you are using the high-level OsmosisAgentToolkit, inspect the _sqsClient property (which is protected) or monitor network requests to confirm the base URL being used in API calls.

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