# How to Configure a GraphQL Backend for the Ergo Blockchain in Nautilus Wallet

> Learn how to configure a GraphQL backend for Ergo blockchain in Nautilus Wallet. Enter a valid endpoint URL in Wallet Settings and ensure server compatibility for seamless integration.

- Repository: [Nautilus Team/nautilus-wallet](https://github.com/nautls/nautilus-wallet)
- Tags: how-to-guide
- Published: 2026-03-07

---

**Configure a GraphQL backend for the Ergo blockchain in Nautilus Wallet by entering a compliant endpoint URL in Settings → Connections → GraphQL Server, ensuring the server implements the Ergo GraphQL schema and reports version 0.4.4 or higher.**

Nautilus Wallet communicates with the Ergo blockchain through the `GraphQLService` class defined in [`src/chains/ergo/services/graphQlService.ts`](https://github.com/nautls/nautilus-wallet/blob/main/src/chains/ergo/services/graphQlService.ts). To configure a GraphQL backend, you must provide a compatible endpoint URL that the wallet validates for schema compliance, version compatibility, and network alignment before establishing a connection.

## Prerequisites for Your GraphQL Backend

Before configuring Nautilus Wallet, ensure your GraphQL server meets the technical requirements enforced by the wallet's validation layer.

### Ergo Schema Compatibility

Your GraphQL backend must implement the standard Ergo GraphQL schema, exposing the required query types: `addresses`, `blockHeaders`, `boxes`, `tokens`, and `mempool`. The `GraphQLService` relies on these fields to fetch blockchain state, transaction data, and token information.

### Version and Network Requirements

According to [`src/chains/ergo/services/graphQlService.ts`](https://github.com/nautls/nautilus-wallet/blob/main/src/chains/ergo/services/graphQlService.ts), Nautilus enforces a `MIN_SERVER_VERSION` of `[0, 4, 4]` (version 0.4.4). The wallet also validates the server's network type via the `validateServerNetwork` function—main-net endpoints must report `"mainnet"`, while test-net endpoints must report `"testnet"`. Mismatches trigger UI errors such as "wrong server network" or "unsupported server version".

## Configuring the GraphQL Endpoint in Nautilus

You can configure the GraphQL backend through the wallet's user interface or by modifying the source constants before building.

### Via the User Interface

The simplest method uses the Global Settings panel:

1. Open **Settings → Connections → GraphQL Server** (defined at line 334 of [`src/views/settings/GlobalSettings.vue`](https://github.com/nautls/nautilus-wallet/blob/main/src/views/settings/GlobalSettings.vue)).
2. Enter the full URL of your GraphQL endpoint, for example: `https://my-ergo-node.example.com/api/graphql`.
3. Click **Save**.

Nautilus validates the URL immediately, checking the server version against `MIN_SERVER_VERSION` and verifying the network type. Upon successful validation, the wallet writes the value to `browser.storage.local` under the `settings` key as `graphQLServer`. The `GraphQLService` constructor calls `#loadServerUrl()` to retrieve this value on initialization:

```typescript
// src/chains/ergo/services/graphQlService.ts
#loadServerUrl() {
  storage.local
    .get("settings")
    .then((s) => this.setUrl((s.graphQLServer as string) ?? DEFAULT_SERVER_URL));
}

```

### Programmatic Configuration

To verify the stored configuration programmatically, access the browser's local storage:

```javascript
await browser.storage.local.get('settings').then(s => console.log(s.graphQLServer));

```

The `GraphQLService` instance (initialized at line 29 of [`graphQlService.ts`](https://github.com/nautls/nautilus-wallet/blob/main/graphQlService.ts)) uses this URL for all subsequent GraphQL operations.

## Advanced Configuration Options

For deployments requiring high availability or custom defaults, you can modify the fallback server list or change the hard-coded default URL.

### Adding Fallback Servers

Nautilus supports automatic failover through the `FALLBACK_GRAPHQL_SERVERS` constant. Edit [`src/chains/ergo/services/graphQlService.ts`](https://github.com/nautls/nautilus-wallet/blob/main/src/chains/ergo/services/graphQlService.ts) (lines 41-43) to include additional endpoints:

```typescript
const FALLBACK_GRAPHQL_SERVERS = MAINNET
  ? ["https://gql.ergoplatform.com/", "https://my-fallback.example.com/"]
  : [];

```

When the primary server fails, the wallet attempts connections to these fallback URLs in sequence.

### Changing Build-Time Defaults

To set a new default GraphQL endpoint for all wallet installations, modify the `DEFAULT_SERVER_URL` constant in [`graphQlService.ts`](https://github.com/nautls/nautilus-wallet/blob/main/graphQlService.ts) (lines 45-47):

```typescript
export const DEFAULT_SERVER_URL = MAINNET
  ? "https://explore.sigmaspace.io/api/graphql"
  : "https://gql-testnet.ergoplatform.com/";

```

After updating the constant, rebuild the extension using `pnpm build` or your preferred build command.

## Validating Your Configuration

After configuration, confirm the active endpoint by inspecting the `graphQLService` instance or checking the stored settings. The wallet rejects connections to servers reporting incorrect versions or networks, displaying validation errors in the UI settings panel. Ensure your endpoint returns the correct `network` field in its schema and meets the minimum version requirement of 0.4.4.

## Summary

- **Schema Requirement**: GraphQL backends must implement Ergo standard types (`addresses`, `boxes`, `tokens`, `mempool`).
- **Version Check**: Servers must report version 0.4.4 or higher (`MIN_SERVER_VERSION` in [`graphQlService.ts`](https://github.com/nautls/nautilus-wallet/blob/main/graphQlService.ts)).
- **UI Configuration**: Update the URL at Settings → Connections → GraphQL Server; validation occurs automatically.
- **Storage**: URLs persist in `browser.storage.local` under `settings.graphQLServer`.
- **Fallbacks**: Define backup endpoints in `FALLBACK_GRAPHQL_SERVERS` for automatic failover.
- **Build Defaults**: Modify `DEFAULT_SERVER_URL` to change the initial default for new installations.

## Frequently Asked Questions

### What Ergo GraphQL schema fields must my backend implement?

Your GraphQL backend must expose the `addresses`, `blockHeaders`, `boxes`, `tokens`, and `mempool` query fields. The `GraphQLService` in Nautilus Wallet queries these fields to retrieve blockchain data, transaction inputs, and token metadata. Missing fields will cause query failures when the wallet attempts to sync state.

### How does Nautilus validate the GraphQL server before connecting?

Nautilus validates servers through version and network checks. The `GraphQLService` verifies that the server reports a version equal to or greater than `0.4.4` (defined as `MIN_SERVER_VERSION` in [`src/chains/ergo/services/graphQlService.ts`](https://github.com/nautls/nautilus-wallet/blob/main/src/chains/ergo/services/graphQlService.ts)). It also calls `validateServerNetwork` to ensure the server's `network` field matches the wallet's current network type (`"mainnet"` or `"testnet"`). Validation errors appear in the Global Settings UI.

### Can I configure multiple GraphQL backends for automatic failover?

Yes. While the UI only configures the primary endpoint, you can enable automatic failover by editing the `FALLBACK_GRAPHQL_SERVERS` constant in [`src/chains/ergo/services/graphQlService.ts`](https://github.com/nautls/nautilus-wallet/blob/main/src/chains/ergo/services/graphQlService.ts). Provide an array of backup URLs; Nautilus will attempt these servers sequentially if the primary endpoint becomes unreachable.

### Where is the GraphQL server URL stored in Nautilus Wallet?

The URL is stored in the browser's local storage under the key `settings` as the property `graphQLServer`. The `GraphQLService` loads this value during construction via the `#loadServerUrl()` private method, falling back to `DEFAULT_SERVER_URL` if no user configuration exists. You can inspect this value using the browser console: `await browser.storage.local.get('settings')`.