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

> Learn to configure a custom SQS URL in Osmosis Agent Toolkit with 3 methods. Guide explains overriding default endpoints for flexible integration.

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

---

**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`](https://github.com/jonator/osmosis-agent-toolkit/blob/main/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`](https://github.com/jonator/osmosis-agent-toolkit/blob/main/client.ts) sets the default `sqsUrl` parameter to `https://sqsprod.osmosis.zone`:

```typescript
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`](https://github.com/jonator/osmosis-agent-toolkit/blob/main/client.ts), the code uses the standard `URL` constructor:

```typescript
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.

```typescript
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:

```typescript
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.

```typescript
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`](https://github.com/jonator/osmosis-agent-toolkit/blob/main/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:

```typescript
// 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:

```typescript
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`](https://github.com/jonator/osmosis-agent-toolkit/blob/main/packages/core/src/queries/sqs/client.ts) | Implements the SQS query client; default endpoint is defined here. | Constructor default (`https://sqsprod.osmosis.zone`) – [L8](https://github.com/jonator/osmosis-agent-toolkit/blob/main/packages/core/src/queries/sqs/client.ts#L8); URL assembly – [L51](https://github.com/jonator/osmosis-agent-toolkit/blob/main/packages/core/src/queries/sqs/client.ts#L51) |
| [`packages/core/src/toolkit.ts`](https://github.com/jonator/osmosis-agent-toolkit/blob/main/packages/core/src/toolkit.ts) | High-level façade that instantiates the client internally. | Internal client creation – [L18](https://github.com/jonator/osmosis-agent-toolkit/blob/main/packages/core/src/toolkit.ts#L18) |
| [`packages/mcp/src/server.ts`](https://github.com/jonator/osmosis-agent-toolkit/blob/main/packages/mcp/src/server.ts) | Example entry-point that creates a toolkit instance (uses default client). | Toolkit construction – [L17-L18](https://github.com/jonator/osmosis-agent-toolkit/blob/main/packages/mcp/src/server.ts#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`](https://github.com/jonator/osmosis-agent-toolkit/blob/main/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`](https://github.com/jonator/osmosis-agent-toolkit/blob/main/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`](https://github.com/jonator/osmosis-agent-toolkit/blob/main/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.