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

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. 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, 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).
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:

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

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

The GraphQLService instance (initialized at line 29 of 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 (lines 41-43) to include additional endpoints:

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 (lines 45-47):

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).
• 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). 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. 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').

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